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

buffer
存储的数据Stored data

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

argument
可选自变量Optional arguments

locale
要使用的区域设置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.

如果 bufferformatNULL 指针,则调用无效的参数处理程序,如参数验证中所述。If buffer or format is a NULL pointer, the invalid parameter handler is invoked, as described in Parameter Validation. 如果允许执行继续,则这些函数返回 -1 并将 errno 设置为 EINVALIf 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 函数将数据从 buffer 读入每个 argument 给定的位置。The sscanf_s function reads data from buffer into the location that's given by each argument. 格式字符串之后的参数指定指向类型与 format 中的类型说明符相对应的变量的指针。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.

备注

大小参数的类型具有 unsigned,而不具有 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.

format 参数控制输入字段的解释,并且格式和函数与 scanf_s 函数的 format 参数相同。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_ssscanf_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 sscanf_s sscanf_s swscanf_s
_stscanf_s_l _sscanf_s_l _sscanf_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/O Stream I/O
fscanf、_fscanf_l、fwscanf、_fwscanf_l fscanf, _fscanf_l, fwscanf, _fwscanf_l
scanf、_scanf_l、wscanf、_wscanf_l scanf, _scanf_l, wscanf, _wscanf_l
sprintf、_sprintf_l、swprintf、_swprintf_l、__swprintf_l sprintf, _sprintf_l, swprintf, _swprintf_l, __swprintf_l
snprintf、_snprintf、_snprintf_l、_snwprintf、_snwprintf_lsnprintf, _snprintf, _snprintf_l, _snwprintf, _snwprintf_l