Content-type: text/html
Man page of scanf
scanf
Section: C Library Functions (3)
Index
Return to Main Contents
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]...);
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.
STANDARDS
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.
PARAMETERS
Specifies the format conversion.
Specifies the input stream.
Specifies 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 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:
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.
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
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.
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 will 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 wide-character 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 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 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 rather than %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 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 large enough to accept 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 - 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, 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.
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 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).
ERRORS
The fscanf() function fails if either the stream
is unbuffered, or 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:
[Digital] The O_NONBLOCK flag is set for the underlying
stream and the process would be delayed by the read operation.
[Digital] 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.
[Digital] The read operation was interrupted by a signal that was
caught and no data was transferred.
[Digital] 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.
[Digital] Insufficient memory is available for the operation.
RELATED INFORMATION
Functions:
atof(3),
atoi(3),
getc(3),
getwc(3),
mbstowcs(3),
mbtowc(3),
printf(3),
wprintf(3),
wscanf(3)
Standards:
standards(5)
delim off
Index
- NAME
-
- LIBRARY
-
- SYNOPSIS
-
- STANDARDS
-
- PARAMETERS
-
- DESCRIPTION
-
- Conversion Specifications
-
- RESTRICTIONS
-
- RETURN VALUES
-
- ERRORS
-
- RELATED INFORMATION
-
This document was created by
man2html,
using the manual pages.
Time: 02:41:00 GMT, October 02, 2010