#include <stdio.h>

int scanf (const char *format[,argument]...);
int scanf_s(const char *format[,argument]...);

#include <wchar.h>

int wscanf(const wchar_t *format[,argument]...);
int wscanf_s(const wchar_t *format[,argument]...);

wscanf_s is a wide-character version of scanf_s; the format argument to wscanf_s is a wide-character string. wscanf_s and scanf_s behave identically if the stream is opened in ANSI mode. scanf_s doesn't currently support input from a UNICODE stream.

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, _countof(s)); // buffer size is 10, width specification is 9

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.

The following example shows that the buffer size parameter describes the maximum number of characters, not bytes. 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("%9S", ws, _countof(ws)); 

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. This example reads in a string of up to 9 single-byte-wide characters and puts them in a double-byte-wide character buffer. 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); 

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, _countof(c)); // not null terminated 

For more information, see scanf Format Specification.

Return Values

Returns the number of fields successfully converted and assigned; the return value does not include fields that were read but not assigned. A return value of 0 indicates that no fields were assigned. The 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. If format is a NULL pointer, scanf_s and wscanf_s return EOF and set errno to EINVAL.

Generic Text Routines

Requirements