scanf, _scanf_l, wscanf, _wscanf_l

Read formatted data from the standard input stream. More secure versions of these function are available; see scanf_s, _scanf_s_l, wscanf_s, _wscanf_s_l.

int scanf(
   const char *format [,
   argument]... 
);
int _scanf_l(
   const char *format,
   locale_t locale [,
   argument]... 
);
int wscanf(
   const wchar_t *format [,
   argument]... 
);
int _wscanf_l(
   const wchar_t *format,
   locale_t locale [,
   argument]... 
);

Parameters

  • format
    Format control string.

  • argument
    Optional arguments.

  • locale
    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. A return value of 0 indicates that no fields were assigned.

If format is a NULL pointer, the invalid parameter handler is invoked, as described in Parameter Validation. If execution is allowed to continue, these functions return EOF and set errno to EINVAL.

For information on these and other error codes, see _doserrno, errno, _sys_errlist, and _sys_nerr.

Remarks

The scanf function reads data from the standard input stream stdin and writes the data into the location given by argument. Each argument must be a pointer to a variable of a type that corresponds to a type specifier in format. If copying takes place between strings that overlap, the behavior is undefined.

Security noteSecurity Note

When reading a string with scanf, always specify a width for the %s format (for example, "%32s" instead of "%s"); otherwise, improperly formatted input can easily cause a buffer overrun. Alternately, consider using scanf_s, _scanf_s_l, wscanf_s, _wscanf_s_l or fgets.

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

The versions of these functions with the _l suffix are identical except that they use the locale parameter passed in instead of the current thread locale.

Generic-Text Routine Mappings

TCHAR.H routine

_UNICODE & _MBCS not defined

_MBCS defined

_UNICODE defined

_tscanf

scanf

scanf

wscanf

_tscanf_l

_scanf_l

_scanf_l

_wscanf_l

For more information, see Format Specification Fields — scanf functions and wscanf Functions.

Requirements

Routine

Required header

scanf, _scanf_l

<stdio.h>

wscanf, _wscanf_l

<stdio.h> or <wchar.h>

For additional compatibility information, see Compatibility in the Introduction.

Example

// crt_scanf.c
// compile with: /W3
 /* This program uses the scanf and wscanf functions
  * to read formatted input.
  */

#include <stdio.h>

int main( void )
{
   int   i, result;
   float fp;
   char  c, s[81];
   wchar_t wc, ws[81];
   result = scanf( "%d %f %c %C %80s %80S", &i, &fp, &c, &wc, s, ws ); // C4996
   // Note: scanf and wscanf are deprecated; consider using scanf_s and wscanf_s
   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( L"%d %f %hc %lc %80S %80ls", &i, &fp, &c, &wc, s, ws ); // C4996
   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);
}
  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

.NET Framework Equivalent

See Also

Reference

Floating-Point Support

Stream I/O

Locale

fscanf, _fscanf_l, fwscanf, _fwscanf_l

printf, _printf_l, wprintf, _wprintf_l

sprintf, _sprintf_l, swprintf, _swprintf_l, __swprintf_l

sscanf, _sscanf_l, swscanf, _swscanf_l