scanf, fscanf, sscanf - Convert formatted input
#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 systems that
conform to current versions of ANSI, ISO, or X/Open standards.
Standard C Library (libc)
Interfaces documented on this reference page conform to
industry standards 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.
Specifies the format conversion. Specifies the input
stream. Specifies input to be read. Points to the location
to store the interpreted data.
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.
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. 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 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 [Toc] [Back]
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, 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 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 an e, f, or g indicates
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] indicates 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 integer 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
parameter should be an integer pointer. Accepts a
hexadecimal integer; 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 completion 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 interpreting
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 initialized 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-characters, plus the terminating null widecharacter
that is automatically 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 automatically
added by the function. The function treats a whitespace
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 character
to this sequence.
[ISO C] If the l qualifier is present, the corresponding
argument is 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 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 corresponding 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 follows: 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 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.
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 conflicting 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.
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.
The scanf(), fscanf(), and sscanf() functions return 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, the
functions return EOF (End-of-File).
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 signal 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 following errors: The result would exceed the systemdefined
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.
Functions: atof(3), atoi(3), getc(3), getwc(3),
mbstowcs(3), mbtowc(3), printf(3), wprintf(3), wscanf(3)
Standards: standards(5)
scanf(3)
[ Back ] |
