scanf_s、_scanf_s_l、wscanf_s、_wscanf_s_lscanf_s, _scanf_s_l, wscanf_s, _wscanf_s_l

读取标准输入流中的格式化数据。Reads formatted data from the standard input stream. 这些版本的 scanf、_scanf_l、wscanf、_wscanf_l 具有安全增强功能,如 CRT 中的安全功能所述。These versions of scanf, _scanf_l, wscanf, _wscanf_l have security enhancements, as described in Security Features in the CRT.


int scanf_s(  
   const char *format [,  
int _scanf_s_l(  
   const char *format,  
   locale_t locale [,  
int wscanf_s(  
   const wchar_t *format [,  
int _wscanf_s_l(  
   const wchar_t *format,  
   locale_t locale [,  


格式控制字符串。Format control string.

可选参数。Optional arguments.

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

返回值Return Value

返回已成功转换和分配的字段数量;返回值不包括已读取但未分配的字段。Returns the number of fields 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. 出现错误时,或者如果第一次尝试读取字符时遇到文件末尾字符或字符串末尾字符,则返回值为 EOFThe return value is EOF for an error, or if the end-of-file character or the end-of-string character is encountered in the first attempt to read a character. 如果 formatNULL 指针,则调用无效参数处理程序,如参数验证中所述。If format is a NULL pointer, the invalid parameter handler is invoked, as described in Parameter Validation. 如果允许继续执行,则 scanf_swscanf_s 返回 EOF,并将 errno 设置为 EINVALIf execution is allowed to continue, scanf_s and wscanf_s return EOF 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.


scanf_s 函数从标准输入流 stdin 中读取数据,并将数据写入到 argument 给定的位置。The scanf_s function reads data from the standard input stream stdin and writes the data into the location that's given by argument. 每个 argument 必须为指向类型的变量的指针,该类型与 format 中的类型说明符对应。Each argument must be a pointer to a variable of a type that corresponds to a type specifier in format. 如果在重叠的字符串之间发生复制,则此行为不确定。If copying occurs between strings that overlap, the behavior is undefined.

wscanf_sscanf_s 的宽字符版本;formatwscanf_s 参数是宽字符字符串。wscanf_s is a wide-character version of scanf_s; the format argument to wscanf_s is a wide-character string. 如果在 ANSI 模式下打开流,则 wscanf_sscanf_s 的行为相同。wscanf_s and scanf_s behave identically if the stream is opened in ANSI mode. scanf_s 当前不支持 UNICODE 流的输入。scanf_s doesn't currently support input from a UNICODE stream.

这些带有 _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.

scanfwscanf 不同,scanf_swscanf_s 要求为类型 cCsS 的所有输入参数或 [] 中附加的字符串控件集指定缓冲区大小。Unlike scanf and wscanf, scanf_s and wscanf_s require the buffer size to be specified for all input parameters of type c, C, s, S, or string control sets that are enclosed in []. 字符形式的缓冲区大小作为额外参数,紧跟在指针后面传递到缓冲区或变量。The buffer size in characters is passed as an additional parameter immediately following the pointer to the buffer or variable. 例如,如果您正在读取一个字符串,则将传递该字符串的缓冲区大小,如下所示:For example, if you are reading a string, the buffer size for that string is passed as follows:

char s[10];

scanf_s("%9s", s, (unsigned)_countof(s)); // buffer size is 10, width specification is 9

缓冲区大小包括终止 null 字符。The buffer size includes the terminating null. 您可以使用宽度规范字段来确保读入的标记可放入缓冲区中。You can use a width specification field 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.


大小参数的类型具有 unsigned,而不具有 size_tThe size parameter is of type unsigned, not size_t. 使用静态强制转换将 size_t 值转换为 unsigned,以进行 64 位生成配置。Use a static cast to convert a size_t value to unsigned for 64-bit build configurations.

以下示例说明缓冲区大小参数描述的是最大字符数而非最大字节数。The following example shows that the buffer size parameter describes the maximum number of characters, not bytes. 在调用 wscanf_s 时,缓冲区类型所指示的字符宽度与格式说明符指示的字符宽度不匹配。In the call to wscanf_s, the character width that is indicated by the buffer type does not match the character width that is indicated by the format specifier.

wchar_t ws[10];  
wscanf_s(L"%9S", ws, (unsigned)_countof(ws));  

S 格式说明符指明了与函数支持的默认宽度“相反的”字符宽度的用法。The S format specifier indicates the use of the character width that is "opposite" the default width that is supported by the function. 该字符宽度是单字节的,而函数支持双字节字符。The character width is single-byte, but the function supports double-byte characters. 此示例可读入最多 9 个单字节宽度字符的字符串,并将其放入一个双字节宽度字符缓冲区中。This example reads in a string of up to 9 single-byte-wide characters and puts them in a double-byte-wide character buffer. 这些字符被视为单字节值;头两个字符存储在 ws[0] 中,紧接着的两个字符存储在 ws[1] 中,依此类推。The characters are treated as single-byte values; the first two characters are stored in ws[0], the second two are stored in ws[1], and so on.

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

char c;

scanf_s("%c", &c, 1);

在读取非 null 终止的字符串的多个字符时,将整数用作宽度规范和缓冲区大小。When multiple characters for non-null terminated strings are read, integers are used as the width specification and the buffer size.

char c[4];

scanf_s("%4c", &c, (unsigned)_countof(c)); // not null terminated

有关详细信息,请参阅 scanf 宽度规范For more information, see scanf Width Specification.

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

TCHAR.H 例程TCHAR.H routine 未定义 _UNICODE 和 _MBCS_UNICODE & _MBCS not defined 已定义 _MBCS_MBCS defined 已定义 _UNICODE_UNICODE defined
_tscanf_s scanf_s scanf_s wscanf_s
_tscanf_s_l _scanf_s_l _scanf_s_l _wscanf_s_l

有关详细信息,请参阅格式规范字段:scanf 和 wscanf 函数For more information, see Format Specification Fields: scanf and wscanf Functions.


例程所返回的值Routine 必需的标头Required header
scanf_s, _scanf_s_lscanf_s, _scanf_s_l <stdio.h><stdio.h>
wscanf_s, _wscanf_s_lwscanf_s, _wscanf_s_l <stdio.h> 或 <wchar.h><stdio.h> or <wchar.h>

控制台在 Windows 8.x 应用商店Windows 8.x Store 应用程序中不受支持。The console is not supported in Windows 8.x 应用商店Windows 8.x Store apps. 与控制台 stdinstdoutstderr 关联的标准流句柄必须重定向,然后 C 运行时函数才可以在 Windows 8.x 应用商店Windows 8.x Store 应用中使用它们。The standard stream handles that are associated with the console—stdin, stdout, and stderr—must be redirected before C run-time functions can use them in Windows 8.x 应用商店Windows 8.x Store apps. 有关其他兼容性信息,请参阅 兼容性For additional compatibility information, see Compatibility.


// crt_scanf_s.c  
// This program uses the scanf_s and wscanf_s functions  
// to read formatted input.  

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

int main( void )  
   int      i,  
   float    fp;  
   char     c,  
   wchar_t  wc,  

   result = scanf_s( "%d %f %c %C %s %S", &i, &fp, &c, 1,  
                     &wc, 1, s, (unsigned)_countof(s), ws, (unsigned)_countof(ws) );  
   printf( "The number of fields input is %d\n", result );  
   printf( "The contents are: %d %f %c %C %s %S\n", i, fp, c,  
           wc, s, ws);  
   result = wscanf_s( L"%d %f %hc %lc %S %ls", &i, &fp, &c, 2,  
                      &wc, 1, s, (unsigned)_countof(s), ws, (unsigned)_countof(ws) );  
   wprintf( L"The number of fields input is %d\n", result );  
   wprintf( L"The contents are: %d %f %C %c %hs %s\n", i, fp,  
            c, wc, s, ws);  

当提供此输入时,该程序将生成以下输出:This program produces the following output when given this input:

71 98.6 h z Byte characters

36 92.3 y n Wide characters

The number of fields input is 6  
The contents are: 71 98.599998 h z Byte characters  
The number of fields input is 6  
The contents are: 36 92.300003 y n Wide characters  

请参阅See Also

浮点支持 Floating-Point Support
流 I/O Stream I/O
区域设置 Locale
fscanf、_fscanf_l、fwscanf、_fwscanf_l fscanf, _fscanf_l, fwscanf, _fwscanf_l
printf、_printf_l、wprintf、_wprintf_l printf, _printf_l, wprintf, _wprintf_l
sprintf、_sprintf_l、swprintf、_swprintf_l、__swprintf_l sprintf, _sprintf_l, swprintf, _swprintf_l, __swprintf_l
sscanf、_sscanf_l、swscanf、_swscanf_lsscanf, _sscanf_l, swscanf, _swscanf_l