scanf(3S)scanf(3S)NAMEscanf(), fscanf(), sscanf() - formatted input conversion, read from
stream file
SYNOPSISDESCRIPTION
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 con‐
trol 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 interpre‐
tation of input sequences. The control string contains:
· White-space characters (blanks, tabs, newlines, or formfeeds)
that cause input to be read up to the next non-white-space
character (except in two cases described below).
· An ordinary character (not that must match the next character
of the input stream.
· Conversion specifications, consisting of the character an
optional assignment suppressing character an optional numeri‐
cal maximum-field width, an optional or indicating the size
of the receiving variable and a conversion code.
· 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 speci‐
fier applies to an argument with type pointer to
An optional specifying that a following or conversion speci‐
fier applies to an argument with type pointer to
An optional specifying that a following or conversion speci‐
fier 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 hexa‐
decimal floating-point input is not accepted.
· The conversion specification can alternatively be prefixed by
the character sequence instead of the character where n is a
decimal 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 specifica‐
tion, 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 indicates
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 conver‐
sion codes are legal:
A single is expected in the input at this point; no assign‐
ment 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, inter‐
preted according to C conventions, will be stored; a
leading implies octal, a leading implies hexadeci‐
mal; 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 consumed. The function return value
does not include assignments in the count of suc‐
cessfully 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 float‐
ing-point numbers is an optionally signed string of
digits, possibly containing a radix character, fol‐
lowed by an optional exponent field consisting of an
or an followed by an optional or space, followed by
an integer. For Itanium(R)-based systems only,
hexadecimal floating-point input also is accepted:
the format is an optionally signed string of hexa‐
decimal digits, possibly containing a radix charac‐
ter, followed by an optional binary exponent field
(indicating the power of two by which the signifi‐
cant part is to be scaled) consisting of a or a fol‐
lowed 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 preci‐
sion, as specified by the conversion precision modi‐
fier). 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 sup‐
pressed in this case; to read the next non-space
character, use If a field width is given, the corre‐
sponding 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 con‐
verted 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 charac‐
ter 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 charac‐
ters large enough to accept the string and a termi‐
nating 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 com‐
plement 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 conventions. 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 circumflex) of the scanset,
in which case it will not be interpreted syntacti‐
cally 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 automatically. At least one charac‐
ter 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 con‐
verted 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 charac‐
ter is converted. The corresponding argument must
be a pointer to an array of large enough to accept
the sequence and the terminating null wide-charac‐
ter, 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 repre‐
sented by the hexadecimal sequence is stored. The
behavior of this conversion is undefined for any
input item other than a value converted earlier dur‐
ing 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. Similarly,
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 modi‐
fier 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 sig‐
nal,
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 deter‐
mined 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 ALSOgetc(3S), printf(3S), setlocale(3C), strtod(3C), strtol(3C), orienta‐
tion(5), thread_safety(5), glossary(9).
STANDARDS CONFORMANCEscanf(3S)