scanf(3)scanf(3)NAME
scanf, fscanf, sscanf - Convert formatted input
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]... );
If the pointer parameter identifies an object of type wchar_t (see the
Description section), source files should include either <sys/types.h>
or <stddef.h> before <stdio.h> to maintain portability across all sys‐
tems that conform to current versions of ANSI, ISO, or X/Open stan‐
dards.
LIBRARY
Standard C Library (libc)
STANDARDS
Interfaces documented on this reference page conform to industry stan‐
dards as follows:
fscanf(), scanf(), sscanf(): ISO C, XPG4, XPG4-UNIX
Refer to the standards(5) reference page for more information about
industry standards and associated tags.
PARAMETERS
Specifies the format conversion. Specifies the input stream. Speci‐
fies input to be read. Points 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 conver‐
sion specifications used to interpret the input. The pointer parameters
specify where to store the interpreted data.
The functions read their input from the following sources: Reads from
standard input (stdin). Reads from the stream parameter. Reads from
the character string specified by the string parameter.
If the length of an input item is zero, these functions return an
error. This error indicates a matching failure unless end-of-file, an
encoding error, or a read error prevented input from a stream, in which
case the error indicates input failure.
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.
These functions truncate leading zeroes (before a decimal point, if
any). If a string value exceeds its formatted type destination limit
(as defined by the machine architecture), the return value will be the
corresponding MIN or MAX value for the type, as appropriate, and an
errno ERANGE value will be set.
The format parameter can contain the following items: A conversion
specification that directs the conversion of the next input field. Con‐
version 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 charac‐
ter 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 lead‐
ing white space and consider the first trailing white-space
character as a field delimiter. Invalid character
If the input stream contains a character that is not allowed,
this invalid character delimits the field and is considered to
be 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,
the field is terminated when that character position is reached
in the input stream.
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 % (per‐
cent sign) is replaced by %digit$, where digit is a decimal num‐
ber in the range from 1 to NL_ARGMAX. Conversion is then applied
to the specified pointer, not to the next unused pointer. This
feature provides for the definition of format strings in an
order appropriate to specific languages. If the variable order‐
ing feature is used, it must be specified for all conversions
except for conversion specifications that do not have corre‐
sponding pointers (conversion specifications with the * (aster‐
isk) 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 dec‐
imal 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 receiv‐
ing 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 an e, f, or g indi‐
cates that the receiving variable will be treated as a double
instead of a float. An L followed by an e, f, or g indicates
that the receiving variable will be treated as a long double
instead of a float. An l followed by a c, s, or [scanset] indi‐
cates that the receiving variable will be treated as wchar_t
instead of char. 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. Accepts an
optionally signed decimal integer, whose format is the same as
expected for the subject sequence of strtol() with the value 10
for the base argument. The pointer parameter should be an inte‐
ger pointer. Accepts an optionally signed decimal integer,
whose format is the same as expected for the subject sequence of
strtol() with the value 0 for the base argument. The pointer
parameter should be an integer pointer. Accepts an unsigned
decimal integer; the pointer parameter should be an unsigned
integer pointer. Accepts an octal integer; the pointer parame‐
ter should be an integer pointer. Accepts a hexadecimal inte‐
ger; the pointer parameter should be an integer pointer.
Accepts 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.
Matches an unsigned hexadecimal long integer, the same as the %p
conversion of the printf() function. The corresponding argument
should be a pointer to a pointer to void. No 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
by this function. The assignment count returned at the comple‐
tion of this function is not incremented. Accepts a string of
bytes that are not white-space characters. [ISO C] (When the
current locale supports shift-state encoding, skipping white-
space characters may result in redundant shift sequences.)
If no l qualifier is present, the pointer parameter should point
to an array of characters that is large enough to accept the
converted sequence of characters, along with the terminating
null byte automatically appended by the function. When inter‐
preting the input string, the function considers a white-space
character as the delimiter of each input field and generates a
string of char values as output. If a field width is given, the
function assumes that pointer refers to a single-byte character
array, and only the specified number of char values is read from
the input string.
[ISO C] If an l qualifier is present, the input is treated as a
sequence of multibyte characters that begins in the initial
shift state. The function converts each multibyte character to a
wide-character as if by a call to the mbrtowc() function, with
the conversion state described by an mbstate_t object initial‐
ized to zero before the first multibyte character is converted.
The corresponding pointer should point to a wchar_t array that
is large enough to accept the converted sequence of wide-charac‐
ters, plus the terminating null wide-character that is automati‐
cally added by the function. Accepts a string of multibyte
characters and converts them as if by a call to the mbstowcs()
function. The pointer parameter should be a pointer to an array
of wchar_t. The array must be large enough to accept the string,
along with the terminating null wide-character that is automati‐
cally added by the function. The function treats a white-space
character as the delimiter of each field in the input string and
generates a string of wchar_t as output. If the S conversion
specifier includes a field width, the behavior of the conversion
is undefined. Accepts a sequence of characters, the number of
which is specified by the field width (1 if no field width is
specified).
If the l qualifier is not present, the corresponding argument
should be a character array large enough to accept the converted
sequence. The function does not append a terminating null char‐
acter to this sequence.
[ISO C] If the l qualifier is present, the corresponding argu‐
ment is a sequence of multibyte characters that begins in the
initial shift state. The function converts each multibyte char‐
acter as if by a call to the mbrtowc() function, with the con‐
version state described by an mbstate_t object initialized to
zero before conversion of the first multibyte character. The
corresponding argument should be a pointer to the first element
of a wchar_t array that is large enough to accept the resulting
sequence of wide-characters. The function does not append a
terminating null wide-character to this sequence.
The c directive suppresses the normal skip over white space;
therefore, use %1s instead of %1c to read the next nonwhite-
space character. Accepts 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. 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).
If the l qualifier is not present, the corresponding pointer
parameter should point to an array of char that is large enough
to contain both the converted sequence and the terminating null
character that is automatically added by the function.
[ISO C] If the l qualifier is present, the input is handled as
a sequence of multibyte characters that begins in the initial
shift state. The function converts each multibyte character as
if by a call to the mbrtowc() function, with the conversion
state described by an mbstate_t object initialized to zero
before conversion of the first multibyte character. The corre‐
sponding pointer parameter should be a pointer to a wchar_t
array that is large enough to accept both the converted sequence
and the terminating null wide-character that is automatically
added by the function.
The [scanset] directive suppresses the normal skip over leading
white space.
A scanset in the form of [^scanset] is an exclusive scanset;
that is, the ^ (circumflex) serves as a complement operator and
the characters in scanset are not accepted as input.
Conventions used in the construction of the scanset are as fol‐
lows: 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;
otherwise, the - (dash) stands for itself. The dash 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, the right bracket is not interpreted as the bracket that
closes the scanset. If the scanset is an exclusive scanset, the
] character is preceded by the ^ (circumflex) character to make
the ] an element of the scanset.
The conversion specification syntax is summarized by the following syn‐
opsis:
%[digit$][*][width][sizecode]convcode
The results from the conversion are placed in *pointer unless you spec‐
ify 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.
All *scanf() functions end at the end of the file, at the end of the
control string, or when an input character conflicts with the control
string. If the function ends with an input character conflict, the con‐
flicting character is not read from the input stream.
Unless there is a match in the control string, these functions do not
read trailing white space (including a newline character).
The success of literal matches and suppressed assignments cannot be
directly determined. The *scanf() functions return only the number of
successfully matched and assigned input items.
RESTRICTIONS
Currently, the Tru64 UNIX product does not include locales that use
shift-state encoding. Some sections of this reference page refer to the
mb_state object or describe behavior that is dependent on shift-state
encoding. This information is included only for your convenience in
developing portable applications that run on multiple platforms, some
of which may supply locales that do use shift-state encoding.
RETURN VALUES
The scanf(), fscanf(), and sscanf() functions return the number of suc‐
cessfully matched and assigned input items. This number can be 0 (zero)
if there was an early conflict between an input character and the con‐
trol string. If the input ends before the first conflict or conversion,
the functions return EOF (End-of-File).
ERRORS
The fscanf() function fails if the stream is unbuffered or if the
stream's buffer needs to be flushed and the function call causes an
underlying read() or lseek() to be invoked and that operation fails. In
addition, the scanf(), fscanf(), and sscanf() functions set errno to
the corresponding value for the following conditions: [Tru64 UNIX] The
O_NONBLOCK option is set for the underlying stream and the process
would be delayed by the read operation. [Tru64 UNIX] The file
descriptor underlying the stream is not a valid file descriptor or is
not open for reading. The input byte sequence does not form a valid
character. [Tru64 UNIX] The read operation was interrupted by a sig‐
nal that was caught and no data was transferred. [Tru64 UNIX] The
call is attempting to read from the process's controlling terminal and
either the process group is orphaned or the process is ignoring or
blocking the SIGTTIN signal. [Tru64 UNIX] Insufficient memory is
available for the operation. [Tru64 UNIX] One or more of the follow‐
ing errors: The result would exceed the system-defined limits or cause
an overflow (value too large) or an underflow (value too small). The
magnitude of x is such that total or partial loss of significance
resulted.
SEE ALSO
Functions: atof(3), atoi(3), getc(3), getwc(3), mbstowcs(3), mbtowc(3),
printf(3), wprintf(3), wscanf(3)
Standards: standards(5)scanf(3)