SCANF(3S) SysV SCANF(3S)
NAME
scanf, fscanf, sscanf - convert formatted input
SYNOPSIS
#include <stdio.h>
int scanf(format [, pointer ] ... )
const char *format;
int fscanf(stream, format [, pointer ] ... )
FILE *stream;
const char *format;
int sscanf(s, format [, pointer ] ... )
const char *s, *format;
DESCRIPTION
scanf reads from the standard input stream stdin. fscanf reads from the
named input stream. sscanf reads from the character string s. Each
function reads characters, interprets them according to a format, and
stores the results in its arguments. Each expects, as arguments, a
control string format described below, and a set of pointer arguments
indicating where the converted input should be stored. The results are
undefined in there are insufficient args for the format. If the format
is exhausted while args remain, the excess args are simply ignored.
Conversions can be applied to the nth argument in the argument list,
rather than to the next unused argument. In this case, the conversion
character % (see below) is replaced by the sequence %digit$, where digit
is a decimal integer n in the range [1,{NL_ARGMAX}], giving the position
of the argument in the argument list. This feature provides for the
definition of format strings that select arguments in an order
appropriate to specific languages.
The format can contain either form of a conversion specification, that is
%, or %digit$, although the two forms cannot be mixed within a single
format string.
The scanf function in all its forms allows for detection of a language
dependent radix character in the input string. The radix character is
defined by langinfo data in the program's locale (category LC_NUMERIC).
In the "C" locale, or in a locale where the radix character is not
defined, the radix character defaults to a full stop (.).
The format must be a multibyte character string beginning and ending in
the initial shift state, that is composed of zero or more directives: one
or more whitespace characters (as specified by the isspace(3C) function);
an ordinary multibyte character (not %); or a conversion specification.
Each conversion specification is introduced by the character % or the
character sequence %digit$.
Conversion Specifications
Each conversion specification in the format parameter contains the
following elements:
1. The character % (percent sign)
2. The optional assignment suppression character * (asterisk)
3. An optional numeric maximum field width
4. An optional character (h, l(ell), or L) that sets the size of the
receiving variable.
The conversion specifiers d, i, and n must be preceded by h if the
corresponding argument is a pointer to short int rather than a
pointer to int, or by l if it is a pointer to long int. Similarly,
the conversion specifiers o, u, and x must be preceded by h if the
corresponding argument is a pointer to unsigned short int rather
than a pointer to unsigned int , or by l if it is a pointer to
unsigned long int. Finally, the conversion specifiers e, f, and g
must be preceded by l if the corresponding argument is a pointer to
double rather than a pointer to float, or by L if it is a pointer to
long double. If an h, l, or L appears with any other conversion
specifier, the behavior is undefined.
5. A conversion code
The scanf functions execute each directive of the format in turn. If a
directive fails, as detailed below, the function returns. Failures are
described as input failures (due to the unavailability of input
characters), or matching failures (due to inappropriate input).
A directive composed of whitespace characters is executed by reading
input up to the first nonwhitespace character (which remains unread), or
until no more characters can be read.
A directive that is an ordinary multibyte character is executed by
reading the next characters of the stream. If one of the characters
differs from one comprising the directive, the directive fails, and the
differing and subsequent characters remain unread.
A directive that is a conversion specification defines a set of matching
input sequences, as described below for each specifier. A conversion
specification is executed in the following steps:
Input whitespace characters (as specified by isspace(3C)) are
skipped, unless the specification includes a [, c, or n specifier.
An input item is read from the stream, unless the specification
includes an n specifier. An input item is defined as the longest
sequence of input characters (up to any specified maximum field
width) that is an initial subsequence of a matching sequence. The
first character, if any, after the input item remains unread. If the
length of the input item is zero, the execution of the directive
fails; this condition is a matching failure, unless an error
prevented input from the stream, in which case it is an input
failure.
Except in the case of a % specifier, the input item (or in the case
of a %n directive, the count of input characters) is converted to a
type appropriate to the conversion specifier. If the input item is
not a matching sequence, the execution of the directive fails; this
condition is a matching failure. Unless assignment suppression was
indicated by a *, the result of the conversion is placed in the
object pointed to by the first argument following the format
argument that has not already received a conversion result. If this
object does not have an appropriate type, or if the result of the
conversion cannot be represented in the space provided, the behavior
is undefined.
The following conversion codes are legal:
% a single % is expected in the input at this point; no assignment
or conversion is done. The complete conversion specification is
%%.
d an optionally signed decimal integer is expected; the
corresponding argument should be an integer pointer.
u an optionally signed decimal integer is expected; the
corresponding argument should be an unsigned integer pointer.
o an optionally signed octal integer is expected; the corresponding
argument should be an unsigned integer pointer.
x an optionally signed hexadecimal integer is expected; the
corresponding argument should be an unsigned integer pointer.
i an optionally signed integer is expected; the corresponding
argument should be an integer pointer. It will store the value of
the next input item interpreted according to C conventions: a
leading "0" implies octal; a leading "0x" implies hexadecimal;
otherwise, decimal.
n stores in an integer argument the total number of characters
(including white space) that have been scanned so far by this
call to one of the scanf functions. The corresponding argument
must be a pointer to int. No input is consumed. Execution of a
%n directive does not increment the assignment count returned as
the completion of execution of the function.
e,f,g an optionally signed 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 decimal point,
followed by an optional exponent field consisting of an E or an
e, followed by an optional +, -, or space, followed by an
integer.
s 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 \0, which will be
added automatically. The input field is terminated by a white-
space character.
c a character is expected; the corresponding argument should be a
pointer to the initial character of an array large enough to
accept the sequence. No null character is added. The normal
skip over white space is suppressed in this case; to read the
next non-space character, use %1s. If a field width is given,
the corresponding argument should refer to a character array; the
indicated number of characters is read.
XPG3: The normal skip over whitespace is suppressed in this case;
to read the next nonwhitespace character, use %1s.
[ indicates string data and the normal skip over leading white
space is suppressed. The left bracket is followed by a set of
characters, which we will call 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 not contained in the remainder of the
scanset string. There are some conventions used in the
construction of the scanset. A range of characters may be
represented by the construct first-last, thus [0123456789] may be
expressed [0-9]. Using this convention, first must be lexically
less than or equal to last, or else the dash will stand for
itself. The dash will also stand for itself whenever 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, and in this case it will not be syntactically
interpreted as the closing bracket. The corresponding argument
must point to a character array large enough to hold the data
field and the terminating \0, which will be added automatically.
At least one character must match for this conversion to be
considered successful.
p matches an eight-digit hexadecimal number resulting from the %p
conversion of a pointer-to-void by one of the printf family of
functions; the corresponding argument should be a pointer to a
pointer-to-void.
The conversion specifiers E, G, and X are also valid and behave the same
as, respectively, e, g, and x.
If a conversion specification is invalid, the behavior is undefined.
If EOF is encountered during input, conversion is terminated. If EOF
occurs before any characters matching the current directive have been
read (other than leading whitespace, where permitted), execution of the
current directive terminates with an input failure; otherwise, unless
execution of the cruuent directive is terminated with a matching failure,
execution of the following directive (if any) is terminated with an input
failure. For the sscanf function, reaching the end of the string is
equivalent to encountering EOF.
If conversion terminates on a conflicting input character, the offending
input character is left unread in the input stream. Trailing whitespace
(including newline characters) is left unread unless matched by a
directive. The success of literal matches and suppressed assignments is
not directly determinable other than vial the %n directive. The scanf
and fscanf functions may mark the st_atime field of the file associated
with stream for update. The st_atime field will be marked for update by
the first successful execution of scanf or fscanf using stream that
returns data not supplied by a prior call to ungetc(3S).
EXAMPLES
The call:
int n ; float x; char name[50];
n = scanf("%d%f%s", &i, &x, name);
with the input line:
25 54.32E-1 thompson
will assign to n the value 3, to i the value 25, to x the value 5.432,
and name will contain thompson\0 . Or:
int i, j; float x; char name[50];
(void) scanf("%i%2d%f%*d %[0-9] ", &j, &i, &x, name);
with input:
011 56789 0123 56a72
will assign 9 to j, 56 to i, 789.0 to x, skip 0123, and place the string
56\0 in name. The next call to getchar [see getc(3S)] will return a.
Or:
int i, j, s, e; char name[50];
(void) scanf("%i %i %n%s%n", &i, &j, &s, name, &e);
with input:
0x11 0xy johnson
will assign 17 to i, 0 to j, 6 to s, will place the string xy\0 in name,
and will assign 8 to e. Thus, the length of name is e - s = 2 . The
next call to getchar (see getc(3S)) will return a blank.
DIAGNOSTICS
These functions return the value of the macro EOF if an input failure
occurs before any conversion and errno is set to indicate the error.
Otherwise, they return the number of input items assigned, which can be
fewer than provided for, or even zero, in the event of an early matching
failure.
ERRORS
The fscanf(3S) function fails if either the stream is unbuffered, or the
stream's buffer needed to be flushed and the function call caused an
underlying write(2) or lseek(2) to be invoked. In addition, if the
scanf, fscanf, sscanf, function fails, errno is set to one of the
following values:
[EAGAIN] The O_NONBLOCK flag is set for the file descriptor
underlying stream and the process would be delayed in the
write operation.
[EBADF] The file descriptor underlying stream is not a valid file
descriptor open for writing.
[EFBIG] An attempt was made to write to a file that exceeds the
process' file size limit or the maximum file size.
[EINTR] The read operation was interrupted by a signal which was
caught, and no data was transferred.
[EIO] The implementation supports job control, the process is a
member of a background process group attempting to write
to its controlling terminal, TOSTOP is set, the process is
neither ignoring nor blocking SIGTTOU and the process
group of the process is orphaned. This error may also be
returned under implementation-defined conditions.
[ENOSPC] There was no free space remaining on the device containing
the file.
[EPIPE] An attempt was made to write to a pipe or FIFO that is not
open for reading by any process. A SIGPIPE signal will
also be sent to the process.
CAVEATS
Trailing white space (including a newline) is left unread unless matched
in the control string.
SEE ALSO
getc(3S), printf(3S), stdio(3S), strtod(3C), setlocale(3C), strtod(3C),
strtol(3C), <stdio.h> <langinfo.h>.