sscanf_s、_sscanf_s_l、swscanf_s、_swscanf_s_lsscanf_s, _sscanf_s_l, swscanf_s, _swscanf_s_l

从字符串中读取格式化数据。Reads formatted data from a string. 这些版本的 sscanf、_sscanf_l、swscanf、_swscanf_l 具有安全性增强功能,如 CRT 的安全性增强功能中所述。These versions of sscanf, _sscanf_l, swscanf, _swscanf_l have security enhancements, as described in Security Features in the CRT.

语法Syntax

int sscanf_s(
   const char *buffer,
   const char *format [,
   argument ] ...
);
int _sscanf_s_l(
   const char *buffer,
   const char *format,
   locale_t locale [,
   argument ] ...
);
int swscanf_s(
   const wchar_t *buffer,
   const wchar_t *format [,
   argument ] ...
);
int _swscanf_s_l(
   const wchar_t *buffer,
   const wchar_t *format,
   locale_t locale [,
   argument ] ...
);

参数Parameters

bufferbuffer
存储的数据Stored data

formatformat
窗体控件字符串。Format-control string. 有关详细信息,请参阅格式规范字段:scanf 和 wscanf 函数For more information, see Format Specification Fields: scanf and wscanf Functions.

自变量argument
可选自变量Optional arguments

localelocale
要使用的区域设置The locale to use

返回值Return Value

每个函数都将返回成功转换并分配的字段数;返回值不包括已读取但未分配的字段。Each of these functions returns the number of fields that are successfully converted and assigned; the return value does not include fields that were read but not assigned. 返回值为 0 表示没有分配任何字段。A return value of 0 indicates that no fields were assigned. 返回值是EOF是否有错误或如果在第一次转换之前到达字符串的末尾。The return value is EOF for an error or if the end of the string is reached before the first conversion.

如果缓冲区格式NULL指针,无效参数处理程序调用中所述,参数验证If buffer or format is a NULL pointer, the invalid parameter handler is invoked, as described in Parameter Validation. 如果允许执行继续,则这些函数将返回-1 并设置errnoEINVALIf execution is allowed to continue, these functions return -1 and set errno to EINVAL

有关这些及其他错误代码的信息,请参阅 errno、_doserrno、_sys_errlist 和 _sys_nerrFor information about these and other error codes, see errno, _doserrno, _sys_errlist, and _sys_nerr.

备注Remarks

Sscanf_s函数将读取从数据缓冲区到每个给定的位置参数The sscanf_s function reads data from buffer into the location that's given by each argument. 格式字符串之后的自变量指定指向具有中的类型说明符对应的类型的变量的指针格式The arguments after the format string specify pointers to variables that have a type that corresponds to a type specifier in format. 与不同安全级别较低版本sscanf,缓冲区大小参数是必需的当你使用类型字段字符cCsS,或用括起来的字符串控件集 []Unlike the less secure version sscanf, a buffer size parameter is required when you use the type field characters c, C, s, S, or string control sets that are enclosed in []. 必须紧跟在需要缓冲区大小的缓冲区参数后提供缓冲区大小(以字符为单位)作为附加参数。The buffer size in characters must be supplied as an additional parameter immediately after each buffer parameter that requires it. 例如,如果你正在读入一个字符串,则将传递该字符串的缓冲区大小,如下所示:For example, if you are reading into a string, the buffer size for that string is passed as follows:

wchar_t ws[10];
swscanf_s(in_str, L"%9s", ws, (unsigned)_countof(ws)); // buffer size is 10, width specification is 9

缓冲区大小包括终止 null 字符。The buffer size includes the terminating null. 可以使用宽度规范字段来确保读入的标记可放入缓冲区中。A width specification field may be used to ensure that the token that's read in will fit into the buffer. 如果未使用任何宽度规范字段,并且读取的标记太大以致缓冲区中无法容纳,则不会向该缓冲区写入任何内容。If no width specification field is used, and the token read in is too big to fit in the buffer, nothing is written to that buffer.

对于字符,可读取单个字符,如下所示:In the case of characters, a single character may be read as follows:

wchar_t wc;
swscanf_s(in_str, L"%c", &wc, 1);

此示例从输入字符串读取单个字符,然后将其存储在宽字符缓冲区中。This example reads a single character from the input string and then stores it in a wide-character buffer. 在读取非 null 终止的字符串的多个字符时,将无符号整数用作宽度规范和缓冲区大小。When you read multiple characters for non-null terminated strings, unsigned integers are used as the width specification and the buffer size.

char c[4];
sscanf_s(input, "%4c", &c, (unsigned)_countof(c)); // not null terminated

有关详细信息,请参阅 scanf_s、_scanf_s_l、wscanf_s、_wscanf_s_lscanf 类型字段字符For more information, see scanf_s, _scanf_s_l, wscanf_s, _wscanf_s_l and scanf Type Field Characters.

备注

大小参数属于类型无符号,而不size_tThe size parameter is of type unsigned, not size_t. 在编译为 64 位目标时,使用静态强制转换来转换 _countofsizeof到正确的大小的结果。When compiling for 64-bit targets, use a static cast to convert _countof or sizeof results to the correct size.

格式参数控件的输入解释字段,并具有相同形式和函数与格式参数scanf_s函数。The format argument controls the interpretation of the input fields and has the same form and function as the format argument for the scanf_s function. 如果在重叠的字符串之间发生复制,则此行为不确定。If copying occurs between strings that overlap, the behavior is undefined.

swscanf_s是宽字符版本的sscanf_s; 的自变量swscanf_s是宽字符字符串。swscanf_s is a wide-character version of sscanf_s; the arguments to swscanf_s are wide-character strings. sscanf_s不处理多字节的十六进制字符。sscanf_s does not handle multibyte hexadecimal characters. swscanf_s不处理 Unicode 全角十六进制或"兼容性区域"字符。swscanf_s does not handle Unicode full-width hexadecimal or "compatibility zone" characters. 否则为swscanf_ssscanf_s具有相同行为。Otherwise, swscanf_s and sscanf_s behave identically.

这些函数具有的版本 _l后缀是相同,只不过它们使用传入的区域设置参数而不是当前线程区域设置。The versions of these functions that have the _l suffix are identical except that they use the locale parameter that's passed in instead of the current thread locale.

一般文本例程映射Generic-Text Routine Mappings

TCHAR.H 例程TCHAR.H routine 未定义 _UNICODE 和 _MBCS_UNICODE & _MBCS not defined 已定义 _MBCS_MBCS defined 已定义 _UNICODE_UNICODE defined
_stscanf_s_stscanf_s sscanf_ssscanf_s sscanf_ssscanf_s swscanf_sswscanf_s
_stscanf_s_l_stscanf_s_l _sscanf_s_l_sscanf_s_l _sscanf_s_l_sscanf_s_l _swscanf_s_l_swscanf_s_l

要求Requirements

例程Routine 必需的标头Required header
sscanf_s_sscanf_s_lsscanf_s, _sscanf_s_l <stdio.h><stdio.h>
swscanf_s_swscanf_s_lswscanf_s, _swscanf_s_l <stdio.h> 或 <wchar.h><stdio.h> or <wchar.h>

有关其他兼容性信息,请参阅 兼容性For additional compatibility information, see Compatibility.

示例Example

// crt_sscanf_s.c
// This program uses sscanf_s to read data items
// from a string named tokenstring, then displays them.

#include <stdio.h>
#include <stdlib.h>

int main( void )
{
   char  tokenstring[] = "15 12 14...";
   char  s[81];
   char  c;
   int   i;
   float fp;

   // Input various data from tokenstring:
   // max 80 character string plus null terminator
   sscanf_s( tokenstring, "%s", s, (unsigned)_countof(s) );
   sscanf_s( tokenstring, "%c", &c, (unsigned)sizeof(char) );
   sscanf_s( tokenstring, "%d", &i );
   sscanf_s( tokenstring, "%f", &fp );

   // Output the data read
   printf_s( "String    = %s\n", s );
   printf_s( "Character = %c\n", c );
   printf_s( "Integer:  = %d\n", i );
   printf_s( "Real:     = %f\n", fp );
}
String    = 15
Character = 1
Integer:  = 15
Real:     = 15.000000

请参阅See also

流 I/OStream I/O
fscanf、_fscanf_l、fwscanf、_fwscanf_lfscanf, _fscanf_l, fwscanf, _fwscanf_l
scanf、_scanf_l、wscanf、_wscanf_lscanf, _scanf_l, wscanf, _wscanf_l
sprintf、_sprintf_l、swprintf、_swprintf_l、__swprintf_lsprintf, _sprintf_l, swprintf, _swprintf_l, __swprintf_l
snprintf、_snprintf、_snprintf_l、_snwprintf、_snwprintf_lsnprintf, _snprintf, _snprintf_l, _snwprintf, _snwprintf_l