scanf(3) — Subroutines
NAME
scanf, fscanf, sscanf − Converts formatted input
LIBRARY
Standard C Library (libc.so, libc.a)
SYNOPSIS
#include <stdio.h>
int scanf(
const char ∗format
[,pointer]...);
int fscanf(
FILE ∗stream,
const char ∗format
[,pointer]...);
int sscanf(
const char ∗string,
const char ∗format
[,pointer]...);
PARAMETERS
formatSpecifies the format conversion.
streamSpecifies the input stream.
stringSpecifies input to be read.
pointerPoints to the location to store the interpreted data.
DESCRIPTION
The scanf(), fscanf(), and sscanf() functions read character data, interpret it according to a format, and store the converted results into specified memory locations. The format parameter contains conversion specifications used to interpret the input. The pointer parameters specify where to store the interpreted data.
These functions read their input from the following sources:
scanf()Reads from standard input (stdin).
fscanf()Reads from the stream parameter.
sscanf()Reads from the character string specified by the string parameter.
If there are insufficient arguments for format, the function’s behavior is undefined. If format is exhausted while arguments remain, the excess arguments are evaluated as always but are otherwise ignored.
The format parameter can contain the following items:
•A conversion specification that directs the conversion of the next input field. Conversion specifications start with a % (percent sign).
•Any white space character (as determined by the isspace() function) that matches 0 (zero) or more white space characters in the input stream.
•Any character except % (percent sign) or a white space character that must match the next character in the input stream.
The input stream is broken into fields based on the following:
•White space
All conversion specifications except %c, %C, and %[ ignore leading white space and consider the first trailing white space character to delimit the field.
•Invalid character
If the input stream contains a character that is not allowed, this invalid character delimits the field and is considered the first character of the next field.
•Maximum width
If the conversion specification includes a maximum width and the field is not terminated by white space or an invalid character, then when that character position is reached in the input stream, the field is terminated.
Conversion Specifications
Each conversion specification in the format parameter has the following syntax:
•The character % (percent sign).
The scanf() functions can handle a format string that enables the system to process elements of the pointer list in variable order. In such a case, the normal conversion character % (percent sign) is replaced by %digit$, where digit is a decimal number in the range from 1 to NL_ARGMAX. Conversion is then applied to the specified pointer, rather than to the next unused pointer. This feature provides for the definition of format strings in an order appropriate to specific languages. If the variable ordering feature is used, it must be specified for all conversions except for conversion specifications that do not have corresponding pointers (conversion specifications with the ∗ (asterisk) assignment suppression and %% conversion specifications). If more than one conversion specification specifies the same digit, the results of the function are undefined.
•The optional assignment suppression character ∗ (asterisk).
•An optional decimal digit string that specifies the maximum field width.
•An optional h or l indicating the size of the receiving variable for some conversion specifiers, as follows:
—
An h followed by a d, i, o, u, or x conversion specifier indicates that the receiving variable will be treated as a short int or unsigned short int.
—
An l followed by a d, i, o, u, or x conversion specifier indicates that the receiving variable will be treated as a long int or unsigned long int.
—
An l followed by a e, f, or g indicates that the receiving variable will be treated as a double instead of a float.
•A conversion code character that specifies the type of conversion to be applied:
%Accepts a single % (percent sign) input at this point; no assignment is done.
d, iAccepts a decimal integer; the pointer parameter should be an integer pointer.
uAccepts an unsigned decimal integer; the pointer parameter should be an unsigned integer pointer.
oAccepts an octal integer; the pointer parameter should be an integer pointer.
xAccepts a hexadecimal integer; the pointer parameter should be an integer pointer.
e, f, gAccepts a floating-point number. The next field is converted accordingly and stored through the corresponding parameter, which should be a pointer to a float. The input format for floating-point numbers is a string of digits, with the following optional characteristics:
—
It can be a signed value.
—
It can be an exponential value, containing a decimal point followed by an exponent field, which consists of an E or an e followed by an optionally signed integer.
—
It can be one of the special values INF, NaNQ, or NaNS. This value is translated into the ANSI/IEEE value for infinity, quiet NaN, or signaling NaN, respectively.
pMatches an unsigned hexadecimal long integer, the same as the %p conversion of the printf() function. The corresponding argument will be a pointer to a pointer to void.
nNo input is consumed. The corresponding argument is a pointer to an integer into which is written the number of characters read from the input stream so far by this function. The assignment count returned at the completion of this function is not incremented.
sAccepts a string of characters. The pointer parameter should be a character pointer that points to an array of characters large enough to accept the string with a terminating null byte appended. The input field ends with a white-space character. A string of char values is output. If a field width is given, pointer refers to a character array, and the indicated number of char values is read.
SAccepts a string of characters. The pointer parameter should be a pointer to an array of wchar_t. The array must be large enough to accept the string with a terminating null wide character appended. The input field ends with a white-space character. A string of wchar_t is output. If the S conversion specifier has a field width, the behavior of the conversion is undefined.
cAccepts a single character or a series of characters. If there is no field width or a field width of 1 in the conversion specification, one character is accepted and the pointer parameter should be a char pointer. If there is a field width greater than 1, the indicated number of characters are accepted and the pointer parameter should be an array of char. The normal skip over white space is suppressed. Use %1s rather than %1c to read the next nonwhite-space character.
CAccepts a single character or a series of characters and converts to wchar_t type. If there is no field width or a field width of 1 in the conversion specification, one character is accepted and the pointer parameter should be a wchar_t pointer. If there is a field width greater than 1, the indicated number of characters are accepted and the pointer parameter should be an array of wchar_t. The normal skip over white space is suppressed. Use %1S rather than %1C to read the next nonwhite-space character.
[scanset]Accepts as input the characters included in the scanset. The scanset parameter explicitly defines the characters that are accepted in the string data as those enclosed within [ ] (square brackets). The corresponding pointer parameter should be an array of char. The leading white space that is normally skipped over is suppressed. A scanset in the form of [^scanset] is an exclusive scanset: the ^ (circumflex) serves as a complement operator and the following characters in the scanset are not accepted as input. Conventions used in the construction of the scanset follow:
—
You can represent a range of characters by the construct First-Last. Thus, you can express [0123456789] as [0-9]. The First parameter must be lexically less than or equal to Last, or else the - (dash) stands for itself. The - also stands for itself whenever it is the first or the last character in the scanset.
—
You can include the ] (right bracket) as an element of the scanset if it is the first character of the scanset. In this case, it is not interpreted as the bracket that closes the scanset. If the scanset is an exclusive scanset, the ] is preceded by the ^ (circumflex) to make the ] an element of the scanset. The corresponding pointer parameter must point to a character array large enough to hold the data field and that ends with 0 (zero). The 0 is added automatically.
The conversion specification syntax is summarized by the following synopsis:
%[digit$][∗][width][sizecode]convcode
The results from the conversion are placed in ∗pointer unless you specify assignment suppression with an ∗ (asterisk). Assignment suppression provides a way to describe an input field that is to be skipped. The input field is a string of nonwhite-space characters. It extends to the next inappropriate character or until the field width, if specified, is exhausted.
The conversion code indicates how to interpret the input field. The corresponding pointer must usually be of a restricted type. You should not specify the pointer parameter for a suppressed field.
A scanf() function ends at the end of the file, the end of the control string, or when an input character conflicts with the control string. If scanf() ends with an input character conflict, the conflicting character is not read from the input stream.
Unless there is a match in the control string, trailing white space (including a newline character) is not read.
The success of literal matches and suppressed assignments cannot be directly determined. The scanf() function returns the number of successfully matched and assigned input items.
NOTES
AES Support Level:
Full use.
RETURN VALUES
The scanf(), fscanf(), or sscanf() function returns the number of successfully matched and assigned input items. This number can be 0 (zero) if there was an early conflict between an input character and the control string. If the input ends before the first conflict or conversion, EOF (End-of-File) is returned.
ERRORS
The fscanf() function fails if either the stream is unbuffered, or the stream’s buffer needed to be flushed and the function call caused an underlying read() or lseek() to be invoked and that operation fails. In addition, if the any of the following conditions occur, the scanf(), fscanf(), and sscanf(), functions set errno to the corresponding value.
[EAGAIN]The O_NONBLOCK flag is set for the underlying stream and the process would be delayed by the read operation.
[EBADF]The file descriptor underlying the stream is not a valid file descriptor or is not open for reading.
[EINTR]The read operation was interrupted by a signal that was caught and no data was transferred.
[EIO]The call is attempting to read from the process’s controlling terminal and either the process is ignoring or blocking the SIGTTIN signal or the process group is orphaned.
[ENOMEM]Insufficient memory is available for the operation.