scanf(3S) scanf(3S)
NAME
scanf(), fscanf(), sscanf() - formatted input conversion, read from stream file
SYNOPSIS
DESCRIPTION
reads from the standard input stream stdin.
reads from the named input stream.
reads from the character string s.
Each function reads characters, interprets them according to the control string format argument, and stores the results in its pointer
arguments. If there are insufficient arguments for the format, the behavior is undefined. If the format is exhausted while arguments
remain, the excess arguments are ignored. The control string contains conversion specifications and other characters used to direct inter-
pretation of input sequences. The control string contains:
o White-space characters (blanks, tabs, newlines, or formfeeds) that cause input to be read up to the next non-white-space charac-
ter (except in two cases described below).
o An ordinary character (not that must match the next character of the input stream.
o Conversion specifications, consisting of the character an optional assignment suppressing character an optional numerical maxi-
mum-field width, an optional or indicating the size of the receiving variable and a conversion code.
o For Itanium(R)-based systems if the optional decimal floating point feature is installed and enabled, the following optional
character specifications are allowed:
An optional specifying that a following or conversion specifier applies to an argument with type pointer to
An optional specifying that a following or conversion specifier applies to an argument with type pointer to
An optional specifying that a following or conversion specifier applies to an argument with type pointer to
The behavior of the or conversion specifiers for decimal floating point numbers is the same as for double except hexadecimal
floating-point input is not accepted.
o The conversion specification can alternatively be prefixed by the character sequence instead of the character where n is a deci-
mal integer in the range is defined in The construction indicates that the value of the next input field should be placed in the
nth argument, rather than to the next unused one. The two forms of introducing a conversion specification, and must not be mixed
within a single format string with the following exception: Skip fields (see below) can be designated as or In the latter case, n
is ignored.
Unless the specification contains the conversion character (described below), a conversion specification directs the conversion of the next
input field. The result of a conversion specification is placed in the variable to which the corresponding argument points, unless indi-
cates assignment suppression. Assignment suppression provides a way to describe an input field to be skipped. An input field is defined
as a string of non-space characters; it extends to the next inappropriate character or until the field width, if specified, is exhausted.
For all descriptors except and white space leading an input field is ignored.
The conversion code indicates the interpretation of the input field; the corresponding pointer argument must be of a restricted type. For
a suppressed field, no pointer argument is given. The following conversion codes are legal:
A single is expected in the input at this point; no assignment is done.
A decimal integer is expected;
the corresponding argument should be an integer pointer.
An unsigned decimal integer is expected;
the corresponding argument should be an unsigned integer pointer.
An octal integer is expected;
the corresponding argument should be an unsigned integer pointer.
A hexadecimal integer is expected;
the corresponding argument should be an unsigned integer pointer. The and conversion characters are equivalent.
An integer is expected;
the corresponding argument should be an integer pointer. The value of the next input item, interpreted according to C
conventions, will be stored; a leading implies octal, a leading implies hexadecimal; otherwise, decimal is assumed.
An type is expected; the corresponding argument should be an pointer which is the 80-bit IEEE-754 double-extended type in
the architecture; should be used with the floating-point specifiers and
Cause the total number of bytes (including white space)
scanned since the function call to be stored; the corresponding argument should be an integer pointer. No input is con-
sumed. The function return value does not include assignments in the count of successfully matched and assigned input
items.
A floating-point number is expected;
the next field is converted accordingly and stored through the corresponding argument, which should be a pointer to a
float. The input format for floating-point numbers is an optionally signed string of digits, possibly containing a
radix character, followed by an optional exponent field consisting of an or an followed by an optional or space, fol-
lowed by an integer. For Itanium(R)-based systems only, hexadecimal floating-point input also is accepted: the format
is an optionally signed string of hexadecimal digits, possibly containing a radix character, followed by an optional
binary exponent field (indicating the power of two by which the significant part is to be scaled) consisting of a or a
followed by an optional or space, followed by a decimal integer. The conversion characters and behave the same as,
respectively, and The and conversions will convert the string (case insensitive) or the string (case insensitive) to the
appropriate floating point infinity value (single, double, or quadruple precision, as specified by the conversion preci-
sion modifier). The and conversions will convert the string (case insensitive) to the appropriate floating point value
(single, double, or quadruple precision, as specified by the conversion precision modifier).
A character is expected;
the corresponding argument should be a character pointer. The normal skip-over-white-space is suppressed in this case;
to read the next non-space character, use If a field width is given, the corresponding argument refers to a character
array; the indicated number of characters is read.
If an (ell) qualifier is present, the input is a sequence of characters that begins in the initial shift state. Each
character in the sequence is converted to a wide-character as if by a call to the function, with the conversion state
described by an object initialized to zero before the first character is converted. The corresponding argument must be
a pointer to an array of large enough to accept the resulting sequence of wide-characters. No null wide-character is
added. The normal skip-over-white-space is suppressed in this case; to read the next non-space character, use If a
field width is given, the corresponding argument refers to a wide character array; the indicated number of characters is
read and converted.
Same as
A character string is expected; the corresponding argument should be
a character pointer pointing to an array of characters large enough to accept the string and a terminating which is
added automatically. The input field is terminated by a white-space character. cannot read a null string.
If an (ell) qualifier is present, the input is a sequence of characters that begins in the initial shift state. Each
character is converted to a wide-character as if by a call to the function, with the conversion state described by an
object initialized to zero before the first character is converted. The corresponding argument must be a pointer to an
array of large enough to accept the sequence and the terminating null wide-character, which will be added automatically.
The input field is terminated by a white-space character. cannot read a null string.
Same as
Indicates string data and the normal skip-over-leading-white-space
is suppressed. The left bracket is followed by a set of characters, called the scanset, and a right bracket; the input
field is the maximal sequence of input characters consisting entirely of characters in the scanset. The circumflex when
it appears as the first character in the scanset, serves as a complement operator and redefines the scanset as the set
of all characters contained in the remainder of the scanset string. Construction of the scanset follows certain conven-
tions. A range of characters may be represented by the construct first-last, enabling [0123456789] to be expressed
[0-9]. Using this convention, first must be lexically less than or equal to last; otherwise, the dash stands for
itself. The dash also stands for itself when it is the first or the last character in the scanset. To include the
right square bracket as an element of the scanset, it must appear as the first character (possibly preceded by a circum-
flex) of the scanset, in which case it will not be interpreted syntactically as the closing bracket. The corresponding
argument must point to a character array large enough to hold the data field and the terminating which are added auto-
matically. At least one character must match for this conversion to succeed.
If an (ell) qualifier is present, the input is a sequence of characters that begins in the initial shift state. Each
character in the sequence is converted to a wide-character as if by a call to the function, with the conversion state
described by an object initialized to zero before the first character is converted. The corresponding argument must be
a pointer to an array of large enough to accept the sequence and the terminating null wide-character, which will be
added automatically.
A sequence of unsigned hexadecimal numbers is expected.
This sequence may be produced by the conversion character of The corresponding argument shall be a pointer to a pointer
to into which the value represented by the hexadecimal sequence is stored. The behavior of this conversion is undefined
for any input item other than a value converted earlier during the same program execution.
The conversion characters and can be preceded by or to indicate that a pointer to a or rather than to an is in the argument list. Simi-
larly, the conversion characters and can be preceded by or to indicate that a pointer to a or rather than to an is in the argument list.
Finally, the conversion characters and can be preceded by or to indicate that a pointer to a or rather than to a is in the argument list.
The or modifier is ignored for other conversion characters.
The functions terminate their conversions at EOF, at the end of the control string, or when an input character conflicts with the control
string. In the latter case, the offending character is left unread in the input stream.
EXTERNAL INFLUENCES
Locale
The category determines the interpretation of ordinary characters within format strings as single and/or multi-byte characters. Field
width is given in terms of bytes. Characters received from the input stream are interpreted as single- or multi-byte characters as deter-
mined by the category and the field width is decremented by the length of the character.
The category determines the radix character expected within floating-point numbers.
International Code Set Support
Single- and multi-byte character code sets are supported.
RETURN VALUE
If the input ends before the first conflict or conversion, EOF is returned. Otherwise, these functions return the number of successfully
assigned input items. This number is a short count, or even zero if a conflict ensues between an input character and the control string.
ERRORS
and fail if data needs to be read into the stream's buffer, and:
The O_NONBLOCK flag is set for the file descriptor underlying stream and the process would be delayed in the read operation.
The file descriptor underlying
stream is not a valid file descriptor open for reading.
The read operation was terminated due to the receipt of a signal,
and either no data was transferred or the implementation does not report partial transfer for this file.
The process is a member of a background process
and is attempting to read from its controlling terminal, and either the process is ignoring or blocking the signal or the
process group of the process is orphaned.
[EILSEQ]
The data obtained from the input stream does not form a valid wide character.
Additional values can be set by the underlying function (see read(2)).
EXAMPLES
The call:
with the input line:
assigns to n the value to i the value to x the value and name contains Or:
with input:
assigns to i, to x, skips and places the string in name. The next call to (see getc(3S)) returns
For another example, to create a language-independent date scanning routine, use:
For American usage, format would point to a string:
The input:
would assign to month, to day and to year.
For German usage, format would point to a string:
The input:
3 Juli 1986
would assign to month, to day and to year.
The success of literal matches and suppressed assignments can be determined with the conversion specification. Here is an example that
checks the success of literal matches:
Here is an example that checks the success of suppressed assignments:
APPLICATION USAGE
After or is applied to a stream, the stream becomes byte-oriented (see orientation(5)).
WARNINGS
Trailing white space (including a newline) is left unread unless matched in the control string.
Truncation of multi-byte characters may occur if a field width is used with the conversion character.
AUTHOR
was developed by AT&T and HP.
SEE ALSO
getc(3S), printf(3S), setlocale(3C), strtod(3C), strtol(3C), orientation(5), thread_safety(5), glossary(9).
STANDARDS CONFORMANCE
scanf(3S)