Description | scanf() reads bytes from the standard input stream stdin according to a specified format.
fscanf() reads bytes from the stream pointed to by stream according to a specified format.
sscanf() reads bytes from the string s according to a specified format.
Each of these functions reads bytes, interprets them according to the directives given in the control string format, and stores the results in the areas specified by the arguments in arglist, if any. format is a character string, beginning and ending in its initial shift state, if defined. It is composed of zero or more directives and may include the following three types of characters: - characters of type
char, which are simply copied to the output stream (1: 1). - white-space characters, starting with a backslash (
\) (see isspace()). - conversion specifications beginning with the percent character (
%), each of which is associated with zero or more arguments in arglist. The results are undefined if fewer arguments are passed in arglist than are defined in format. If the number of arguments defined in format is greater than the arguments passed in arglist, the excess arguments are ignored.
The following applies to the current version of the C runtime system: Only characters from the EBCDIC character set are permitted. The scanf functions read each input character, but do not convert it or store it in a variable. If the input character does not match the character specified in format, input processing is aborted. The control string format may include zero or more characters producing white space. These characters have no control function. White-space characters in the input are treated as delimiters between input fields; they are not converted (see %c and %[] for exceptions). Leading white space in the input is ignored. Depending on which functionality is to be supported by the scanf functions, a different number of white-space characters are recognized (shown in the table below): Character | Meaning | Valid for following functionality | XPG4 | ANSI (BS2000) | KR (BS2000) | 'BLANK'
| Leerzeichen | x | x | x | \n
| Zeilenendezeichen | x | x | x | \t
| horizontaler Tabulator | x | x | x | \f
| Seitenwechsel | x | x | - | \v
| vertikaler Tabulator | - | x | - | \r
| Wagenrücklauf | - | x | - | Conversions can be applied to the n-th argument after the format in the argument list arglist, rather than to the next unused argument. In this case, the conversion character % is replaced by the sequence %n$, where n is a decimal integer in the range
[1, {NL_ARGMAX}], giving the position of the argument in the argument list. This feature provides for the definition of format strings that select arguments in an order appropriate to specific languages. In format strings containing the %n$ form of conversion specifications, it is unspecified whether numbered elements in the argument list arglist can be referenced from the format string format more than once. format can contain either form of a conversion specification, that is, % or %n$, but the two forms cannot normally be mixed within a single format string. The only exception to this is that %% or % * can be mixed with the %n$ form. All forms of fscanf() allow for the insertion of a language-dependent radix character in the input string. The radix character is defined in the program ́s locale (category
LC_NUMERIC). In the POSIX locale, or in a locale where the radix character is not defined, the radix character defaults to a period (.). Each conversion specification is introduced by the % character or by the character sequence % n $, after which the following appear in sequence: An optional assignment-suppressing character *. An optional non-zero decimal integer that specifies the maximum field width. Ein optionales Zeichen hh, h, l, ll, j, z, t or L, that specifies the size of the receiving object. A conversion character that specifies the type of conversion to be applied.
fscanf() executes each directive of the format in turn. If a directive fails, as detailed below, the function returns. Failures are described as input failures (due to the unavailability of input bytes) or matching failures (due to inappropriate input).
A directive composed of one or more white-space characters is executed by reading input until no more valid input bytes can be read, or up to the first byte which is not a white-space character (which remains unread). A directive that is an ordinary character is executed as follows. The next byte is read from the input and compared with the byte that comprises the directive; if the comparison shows that they are not equivalent, the directive fails, and the differing and subsequent bytes remain unread. A directive that is a conversion specification defines a set of matching input sequences, as described below for each conversion character. A conversion specification is executed in the following steps: Input white-space characters are skipped, unless the conversion specification includes a [ or one of the conversion characters c or n. An item is read from the input, unless the conversion specification includes an n conversion character. An input item is defined as the longest sequence of input bytes (up to any specified maximum field width) which is an initial subsequence of a matching sequence. The first byte, if any, after the input item remains unread. If the length of the input item is 0, the execution of the conversion specification fails; this condition is a matching failure, unless an error prevented input, in which case it is an input failure. Except in the case of a % conversion character, the input item (or, in the case of a % n conversion specification, the count of input bytes) is converted to a type appropriate to the conversion character. If the input item is not a matching sequence, the execution of the conversion specification fails; this condition is a matching failure. Unless assignment suppression was indicated by a *, the result of the conversion is placed in the object pointed to by the first argument following the format argument that has not already received a conversion result. If this object does not have an appropriate type, or if the result of the conversion cannot be represented in the space provided, the behavior is undefined. Conversion specifications can be given in XPG4-conformant environments as shown below: %[a$] [ n | *] { [{hh|h|l|ll|j|z|t}] {d|i|o|u|x|X} |
[{hh|h|l|ll|j|z|t}] n |
[l|L] {a|A|e|E|f|F|g|G} |
[l] {[...]|[^...]|c|s} |
{C|S|p} |
% } Conversion characters l
| l before d, i, o, u, x, X: conversion of an argument of type pointer to long int (d, i) or unsigned long int (o, u, x, X).
l before a, A, e, E, f, F, g, G: conversion of an argument of type pointer to double.
l before c, s, or [: conversion of an argument of type pointer to wchar_t.
l before n: The argument is of the type pointer to long int (no conversion).
| ll
| ll before d, i, o, u, x, X : conversion of an argument of type pointer to long long int (d, i) or unsigned long long int (o, u, x, X).
ll before n: The argument is of the type pointer to long long int.
| hh
| hh before d, i, o, u, x, X: conversion of an argument of type pointer to signed char (d, i) or unsigned char (o, u, x, X).
hh before n: The argument is of the type pointer to signed char (no conversion).
| h
| h before d, i, o, u, x, X:conversion of an argument of type pointer to short int (d, i) or unsigned short int (o, u, x, X).
h before n: The argument is of the type pointer to short int (no conversion).
| j
| j before d, i, o, u, x, X: conversion of an argument of type pointer to long int (d, i) or size_t (o, u, x, X).
j before n: The argument is of the type pointer to intmax_t (no conversion).
| z
| z before d, i, o, u, x, X: conversion of an argument of type pointer to signed long int (d, i) or size_t (o, u, x, X).
z before n: The argument is of the type pointer to signed long int (no conversion).
| t
| t before d, i, o, u, x, X: conversion of an argument of type pointer to ptrdiff_t (d, i) or unsigned long int (o, u, x, X).
t before n: The argument is of the type pointer to ptrdiff_t (no conversion).
| L
| L before a, A, e, E, f, F, g, G: conversion of an argument of type pointer to long double.
| d
| Matches an optionally signed decimal integer, whose format is the same as expected for strtol() with the value 10 for base. The corresponding argument must be of type pointer to int. | i
| Matches an optionally signed decimal integer, whose format is the same as expected for strtol() with the value 0 for base. The corresponding argument must be of type pointer to int. | o
| Matches an optionally signed octal integer, whose format is the same as expected for strtol() with the value 8 for base. The corresponding argument must be of type pointer to unsigned. | u
| Matches an optionally signed decimal integer, whose format is the same as expected for strtol() with the value 10 for base. The corresponding argument must be of type pointer to unsigned. | x, X
| Matches an optionally signed hexadecimal integer, whose format is the same as expected for strtol() with the value 16 for base. The corresponding argument must be of type pointer to unsigned. | a, A, e, E, f, F, g, G
|
| These conversion characters match an optionally signed floating-point number, whose format is the same as expected for strtod(). The corresponding argument must be of type pointer to float. | s
| Matches a sequence of bytes that are not white-space characters. The corresponding argument must be a pointer to the initial byte of a char array that is large enough to accept the sequence and a terminating null character byte, which will be added automatically. | S
| Matches a sequence of characters that are not white space. The sequence is converted to a sequence of wide character codes in the same manner as mbstowcs(). The corresponding argument must be a pointer to the first byte of an array of type wchar_t, which must be large enough to accept the sequence and a terminating null byte, which will be added automatically. If the field width is specified, it determines the maximum number of characters accepted. | [
| Matches a non-empty sequence of bytes from a set of expected bytes (the scanset). The corresponding argument must be a pointer to the initial byte of a char array that is large enough to accept the sequence and a terminating null byte, which is added automatically. The conversion specification
includes all subsequent bytes in the format string up to and including the matching right square bracket (]). The bytes between the square brackets (the scanlist) comprise the scanset, unless the byte after the left square bracket is a circumflex (^), in which case the scanset contains all bytes that do not appear in the scanlist between the circumflex and the right square bracket. As a special case, if the conversion specification begins with [] or [^], the right square bracket is included in the scanlist, and the next right square bracket is the matching right square bracket that ends the conversion specification. If a - is in the scanlist and is not the first character, nor the second where the first character is a ^, nor the last character, the behavior is undefined. | c
| Matches a sequence of bytes of the number specified by the field width (or 1 if no field width is present). The corresponding argument must be a pointer to the initial byte of a char array that is large enough to accept the sequence. No terminating null byte is added. The normal skip over whitespace characters is suppressed in this case; %1s should be used to read the next byte that is not a white-space character. | C
| Matches a sequence of characters of the number specified by the field width (1 if no field width is present in the directive). The sequence is converted to a sequence of wide character codes in the same manner as mbstowcs().
The corresponding argument must be a pointer to the first byte of an array of type wchar_t large enough to accept the sequence which is the result of the conversion. No null wide character code is added.
If the matched sequence begins with the initial shift state, the conversion is the same as expected for the mbstowcs() function; otherwise, the behavior of the conversion is undefined. The normal skip over white-space characters is suppressed in this case. | p
| Matches a set of sequences, which must be the same as the set of sequences that is produced by the %p conversion of the printf functions.
p must match the implementation for printf functions. The corresponding argument must be a pointer to a pointer to void. The interpretation of the input item is implementation-dependent; if the input item is not a value that was converted earlier during the same program execution, the behavior of the %p conversion is undefined. This is specially true for pointer outputs generated by other systems. | n
| No input is processed. The corresponding argument must be a pointer to the integer into which the number of input bytes read thus far by this call are to be entered. Execution of a % n conversion specification does not increment the assignment count returned at the completion of execution of the function. | %
| Matches a single %; no conversion or assignment occurs. The complete conversion specification must be %%. |
If a conversion specification is invalid, the behavior of scanf() is undefined. If end-of-file is encountered during input, conversion is terminated. If end-of-file occurs before any bytes matching the current conversion specification have been read (other than leading white-space characters, where permitted), execution of the current conversion specification terminates with an input failure. Otherwise, unless execution of the current conversion specification is terminated with a matching failure, execution of the following conversion specification (if any) is terminated with an input failure. Reaching the end of the string in a sscanf call is equivalent to encountering the end-of-file indicator during an fscanf call. If conversion terminates on a conflicting input, the offending input byte is left unread in the input stream. Any trailing white space (including newline characters) is left unread unless matched by a conversion specification. The success of literal matches and suppressed assignments cannot be directly determined, except via the % n conversion specification. BS2000
Conversion specifications (KR functionality)
(only available with C/C++ versions lower than V3) Conversion specifications contain directives that specify how input fields are to be interpreted and converted. They may be entered in the following format: % [ n | *] { [{h|l}] {d|o|x} |
[l] {e|f} |
[D|E|F|O|X} |
{c|s} |
{[...]|[^...]} |
% }
Every conversion specification must begin with a percent character (%). The remaining characters are interpreted as follows: * | Skip an assignment.
The next input field is read and converted, but not stored in a variable. | n | Maximum length of the input field to be converted.
If a white-space character or a character that does not match the type specified in the conversion specification appears before this entry, the length is truncated accordingly. | l
| l before d, o, x:
conversion of an argument of type pointer to long int (d) or unsigned long int (o, x). The specification is identical to the uppercase letters D, O, X.
l before e, f:
conversion of an argument of type pointer to double.
The specification is identical to the uppercase letters E, F.
| h
| h before d, o, x:
conversion of an argument of type pointer to short int (d) or unsigned short int (o, x).
| d
| A decimal integer value is expected. The corresponding argument must be a pointer to int. | o
| An octal integer value is expected. The corresponding argument may be a pointer to unsigned int or int. The value is internally represented as unsigned. | x
| A hexadecimal integer value is expected. The corresponding argument may be a pointer to unsigned int or int. The value is internally represented as unsigned. | e, f
| A floating-point number is expected. The corresponding argument must be a pointer to float. The floating-point number can contain a sign as well as an exponent (E or e, followed by an integer value). The radix character is determined by the locale (category LC_NUMERIC). The default is a period. | c
| A character is expected. The corresponding argument should be a pointer to char. In this case scanf() will also read blanks. %1s should be used to read the next non-blank character. c is suitable for reading strings that include blanks; to do so, a pointer to a char array must be passed as an argument, and a field length of n must be specified (e.g. %10c). The scanf() function does not automatically terminate the string with the null byte in this case. | s
| A string is expected. The corresponding argument must be a pointer to a char array that is large enough to accept the string and a terminating null byte. scanf() automatically terminates the string with the null byte. Leading white-space characters in the input are ignored; a trailing whitespace character is interpreted as a delimiter (end of the string). | [ ]
| A string is expected. The corresponding argument must be a pointer to a char array that is large enough to accept the string (including the automatically appended null byte). In this specification, as opposed to %s, blanks do not automatically function as delimiters. |
| [...]
| In this specification, characters are read in until the first
character not listed in the square brackets appears. Thus, the
string may only consist of the characters appearing within [ ];
any characters not specified are treated as delimiters. |
| [^...]
| In this specification, characters are read in until one of the
characters listed in the square brackets after ^ is encountered.
Only the characters specified within the [ ] are treated as
delimiters. | %
| Input of the % character, without conversion. (End) |
BS2000
Conversion specifications (ANSI functionality) Conversion specifications contain directives that specify how input fields are to be interpreted and converted. They may be entered in the following format: % [ n | *] { [{hh|h|l|ll|j|z|t}] {d|i|o|u|x|X} |
[{hh|h|l|ll|j|z|t}] n |
[l|L] {a|A|e|E|f|F|g|G} |
p |
[l] {[...]|[^...]|c|s} |
% }
Leading white-space characters in the input are ignored. Every conversion specification must begin with a percent character (%). The remaining characters are interpreted as follows: *
| Skip an assignment. The next input field is read and converted, but not stored in a variable. | n | Maximum length of the input field to be converted. If a white-space character or a character that does not match the type specified in the conversion specification appears before this entry, the length is truncated accordingly. | l
| l before d, i, o, u, x, X: conversion of an argument of type pointer to long int (d, i) or unsigned long int (o, u, x, X).
l before a, A, e, E, f, F, g, G: conversion of an argument of type pointer to double.
l before c, s, or [: conversion of an argument of type pointer to wchar_t.
l before n: The argument is of the type pointer to long int (no conversion).
| ll
| ll before d, i, o, u, x, X : conversion of an argument of type pointer to long long int (d, i) or unsigned long long int (o, u, x, X).
ll before n: The argument is of the type pointer to long long int.
| hh
| hh before d, i, o, u, x, X: conversion of an argument of type pointer to signed char (d, i) or unsigned char (o, u, x, X).
hh before n: The argument is of the type pointer to signed char (no conversion).
| h
| h before d, i, o, u, x, X:conversion of an argument of type pointer to short int (d, i) or unsigned short int (o, u, x, X).
h before n: The argument is of the type pointer to short int (no conversion).
| j
| j before d, i, o, u, x, X: conversion of an argument of type pointer to long int (d, i) or size_t (o, u, x, X).
j before n: The argument is of the type pointer to intmax_t (no conversion).
| z
| z before d, i, o, u, x, X: conversion of an argument of type pointer to signed long int (d, i) or size_t (o, u, x, X).
z before n: The argument is of the type pointer to signed long int (no conversion).
| t
| t before d, i, o, u, x, X: conversion of an argument of type pointer to ptrdiff_t (d, i) or unsigned long int (o, u, x, X).
t before n: The argument is of the type pointer to ptrdiff_t (no conversion).
| L
| L before a, A, e, E, f, F, g, G: conversion of an argument of type pointer to long double.
| d
| A decimal integer value is expected. The corresponding argument must be a pointer to int. | i
| An integer value is expected. The base (hexadecimal, octal, decimal) is determined from the structure of the input field. Leading 0x or 0X: hexadecimal; leading 0: octal; otherwise: decimal. The corresponding argument must be a pointer to int. | o
| An octal integer value is expected. The corresponding argument may be a pointer to unsigned int or int. The value is internally represented as unsigned. | u
| A decimal integer value is expected. The corresponding argument must be a pointer to unsigned int. | x, X
| A hexadecimal integer value is expected. The corresponding argument may be a pointer to unsigned int or int. The value is internally represented as unsigned. | a, A, e, E, f, F, g, G
|
| These conversion characters match an optionally signed floating-point number, whose format is the same as expected for strtod(). The corresponding argument must be of type pointer to float. | c
| Without conversion character l: A character is expected. The corresponding argument should be a pointer to char. In this case scanf() will also read blanks. %1s should be used to read the next non-blank character. c is suitable for reading strings that include blanks; to do so, a pointer to a char array must be passed as an argument, and a field length of n must be specified (e.g. %10c). The scanf() function does not automatically terminate the string with the null byte in this case. With conversion character l: A multibyte character-string that begins in the initial shift state is expected. Each character in the sequence is converted to a wide character as if by a call to the mbrtowc() function, with the conversion state described by an mbstate_t object initialized to zero before the first character is converted. No null wide character is added. The application shall ensure that the corresponding argument is a pointer to an array of wchar_t large enough to accept the resulting sequence of wide characters. | p
| An 8-digit pointer value is expected, analogous to the format %08.8x. The corresponding argument must be a pointer to a pointer to void. | s
| Without conversion character l: A string is expected. The corresponding argument must be a pointer to a char array that is large enough to accept the string and a terminating null byte. scanf() automatically terminates the string with the null byte. Leading white-space characters in the input are ignored; a trailing whitespace character is interpreted as a delimiter (end of the string). With conversion character l: A multibyte character-string that begins in the initial shift state is expected. Each character is converted to a wide character as if by a call to the mbrtowc() function, with the conversion state described by an mbstate_t object initialized to zero before the first character is converted.The application shall ensure that the corresponding argument is a pointer to an array of wchar_t large enough to accept the sequence and the terminating null wide character, which is added automatically. Leading white-space characters in the input are ignored; a trailing whitespace character is interpreted as a delimiter (end of the string). | []
| Without conversion character l: A string is expected. The corresponding argument must be a pointer to a char array that is large enough to accept the string (including the automatically appended null byte). In this specification, as opposed to %s, blanks do not automatically function as delimiters. With conversion character l: A multibyte character-string that begins in the initial shift state is expected. Each character in the sequence shall be converted to a wide character as if by a call to the mbrtowc() function, with the conversion state described by an mbstate_t object initialized to zero before the first character is converted. The application shall ensure that the corresponding argument is a pointer to an array of wchar_t large enough to accept the sequence and the terminating null wide character, which shall be added automatically. |
| [...]
| In this specification, characters are read until the first character not listed in the square brackets appears. Thus, the string may only consist of the characters appearing within [ ]; characters not specified therein are treated as delimiters.
The closing bracket ] can be included in the list of characters to be read by specifying it as the first character immediately after the opening bracket: [ ]...]. |
| [^...]
| In this specification, characters are read until one of the characters listed in the square brackets after ^ is encountered.
Only the characters specified within the [ ] are treated as delimiters. The closing bracket ] can be included in the list of delimiters by specifying it as the first character immediately after the ^ character: [^]...]. | n | No characters are read from the input field. The argument is of type pointer to int. This integer variable is assigned the number of characters processed thus far by scanf(). | % | Input of the % character, without conversion. (End) |
fscanf() and scanf() can mark the structure component st_atime for the file to which stream is assigned for changing (see sys/stat.h). The structure component st_atime is updated as soon as fgetc(), fgets(), fgetwc(), fgetws(), fread(), fscanf(), getc(), getchar(), gets() or scanf() are called successfully for stream and return data which is not was not provided by a preceding call to ungetc() or ungetwc().
|
