scanf(3S) scanf(3S)
NAME
scanf, fscanf, sscanf - formatted input
SYNOPSIS
#include <stdio.h>
int scanf(const char *format, ...);
int fscanf(FILE *stream, const char *format, ...);
int sscanf(const char *s, const char *format, ...);
DESCRIPTION
scanf() reads from the standard input stream, stdin.
fscanf() reads from the specified input stream, stream.
sscanf() reads from the character string s.
Each of these functions reads bytes, interprets them according to a
specified format, and stores the results in its arguments. Each
expects, as arguments, a control string format and a set of pointer
arguments indicating where the converted input should be stored. If
there are insufficient arguments for the format, the behavior is unde-
fined. If the format is exhausted while arguments remain, the excess
arguments are simply ignored.
A conversion specification in format directs the conversion to the
next input field; the result is placed in the variable pointed to by
the corresponding argument. The assignment can be suppressed with * in
order to skip a field. An input field is defined as a string of non-
spaced characters; it extends to the next inappropriate character or
until the maximum field width, if one is specified.
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 % is replaced by the sequence %n$ where n is a decimal
integer giving the position of the argument in the argument list. The
first such argument, %1$, immediately follows format.
The control string can contain either form of a conversion specifica-
tion, i.e., % or %n$, although the two forms cannot be mixed within a
single control string. Only the forms %% and %* can be mixed with the
form %n$.
The control string format usually contains conversion specifications,
which are used to direct interpretation of input sequences. format
comprises the following characters:
Page 1 Reliant UNIX 5.44 Printed 11/98
scanf(3S) scanf(3S)
- White-space characters (blanks, tabs, new-lines or form-feeds).
- Normal characters (not % and not white-space characters) cause the
next character of the input to be read and compared with the byte
from format. If they do not match, this and the subsequent bytes
remain unread.
- Conversion specifications
These begin with the character % or with the string %n$. Then the
following are specified in the given order:
1. * to suppress assignment (optional)
2. a nonzero decimal number, specifying the maximum field size
(optional)
3. h, l or L to indicate the size of the expected object (optional)
4. conversion codes to specify the conversion to be performed (see
explanation below)
A conversion specification is performed in the following steps:
white-space characters (as specified by the isspace() function) are
ignored, unless the conversion specification contains the conversion
code [, c, C or n. If the specification does not contain n, an input
item is read. An input item is defined as the longest sequence of
input bytes (up to a maximum item size, calculated in characters or
bytes depending on the conversion code) that is the initial subse-
quence of a matching sequence. The first byte, if any, after the input
item remains unread. If the length of the input item is zero, the exe-
cution of the conversion specification fails. The input item is con-
verted to a type appropriate to the conversion code. If the input item
is not a matching sequence, the execution of the specification fails.
Unless assignment suppression was indicated by *, the result of the
conversion is placed in the variable pointed to by the first argument
following format. 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.
Conversion characters
The conversion characters are evaluated one after the other. If a
character cannot be evaluated, the function returns with an error. The
following characters are valid:
Page 2 Reliant UNIX 5.44 Printed 11/98
scanf(3S) scanf(3S)
c, lc
Reads a sequence of characters of the number specified by the
field width (1 if no field width is present in the directive).
The corresponding argument must be a pointer to the initial byte
of an array of type char, signed char or unsigned char large
enough to accept the sequence. No null byte is added. The normal
skip over white space is suppressed.
If an l qualifier is present, the input shall be a sequence of
multibyte character conversions in the initial shift state. Each
multibyte character is converted to a wide-character as if by a
call to the mbrtowc() function, with the conversion state
described by an mbsstatet object initialized to zero before the
first multibyte character is converted. The corresponding argu-
ment shall be a pointer to an array of wchart large enough to
accept the sequence and the terminating null wide-character,
which will be added automatically.
C Reads a sequence of characters of the number specified by the
field width (1 if no field width is present in the specifica-
tion). The sequence is converted to a sequence of wide-character
codes in the same manner as the mbstowcs() function. The corres-
ponding argument must be a pointer to the initial byte of an
array of type wchart large enough to accept the sequence which
is the result of the conversion. No null byte is added.
If the sequence begins with the initial shift state, the conver-
sion is the same as expected for the mbwstowcs()function; other-
wise the behavior of the conversion is undefined. The normal skip
over white-space characters is suppressed in this case.
This conversion code is supported from XPG4 mode onwards.
d Reads an optionally signed decimal integer, which has the same
format as the subject sequence of the strtol() function with the
value 10 for the base argument. The corresponding argument should
be a pointer to int.
e, f, g
Reads an optionally signed floating point number, which has the
same format as the subject string of the strstr() function. The
corresponding argument should be a pointer to float.
E In ANSI mode (cc -kansi), E behaves the same as e. In K&R mode
(cc -kcc), E behaves the same as le.
G In ANSI mode (cc -kansi), G behaves the same as g. In K&R mode
(cc -kcc), G behaves the same as lg.
hd, hi, hn
The corresponding argument is a pointer to short int rather than
a pointer to int.
Page 3 Reliant UNIX 5.44 Printed 11/98
scanf(3S) scanf(3S)
ho, hu, hx
The corresponding argument is a pointer to unsigned short int
rather than a pointer to unsigned int.
i Reads an optionally signed integer, which has the same format as
the subject sequence of the strtol() function with the value 0
for the base argument. The corresponding argument should be a
pointer to int.
ld, li, ln
The corresponding argument is a pointer to long int rather than a
pointer to int.
lld, llx
Reads an optionally signed integer, which has the same format as
the subject sequence of the strtoll() function with the value 0
for the base argument. The corresponding argument should be a
pointer to long long int rather than a pointer to int.
le, lf, lg
The corresponding argument should be a pointer to double rather
than a pointer to float.
lo, lu, lx
The corresponding argument should be a pointer to unsigned long
int rather than a pointer to unsigned int.
Le, Lf, Lg
The corresponding argument should be a pointer to long double.
n No input is processed. The corresponding argument should be a
pointer to int into which is to be written the number of charac-
ters read from the input stream so far by the call to the func-
tion. Execution of a %n directive does not increment the assign-
ment count returned at the completion of execution of the func-
tion.
o Reads an optionally signed octal integer, which has the same for-
mat as the subject sequence of the strtol() function with the
value 8 for the base argument. The corresponding argument should
be a pointer to unsigned int.
p Reads a hexadecimal number with the value 16 for the argument
base that has the same format as the set of sequences that may be
produced by the %p conversion of the fprintf() function. The cor-
responding argument should be a pointer to void. The interpreta-
tion of the input item is implementation-defined. If the input
item is a value converted earlier during the same program execu-
tion, the pointer that results will compare equal to that value;
otherwise, the behavior of the %p conversion is undefined.
Page 4 Reliant UNIX 5.44 Printed 11/98
scanf(3S) scanf(3S)
s Reads a sequence without white-space characters. The correspond-
ing argument must be a pointer to the initial byte of an array of
type char, signed char or unsigned char large enough to accept
the sequence and a terminating null byte, which will be added
automatically.
If an l qualifier is present, the input shall be a sequence of
multibyte character conversions in the initial shift state. Each
multibyte character is converted to a wide-character as if by a
call to the mbrtowc() function, with the conversion state
described by an mbsstatet object initialized to zero before the
first multibyte character is converted. The corresponding argu-
ment shall be a pointer to an array of wchart large enough to
accept the sequence and the terminating null wide-character,
which will be added automatically.
S Reads a sequence without white-space characters. This sequence is
converted to a sequence of wide-character codes in the same
manner as the mbstowcs() function. The corresponding argument
must be a pointer to the initial byte of an array of type wchart
large enough to accept the result of the conversion and a ter-
minating null byte which will be added automatically. If the
field width is specified, it denotes the maximum number of char-
acters to accept.
This conversion code is supported from XPG4 mode onwards.
u Reads an optionally signed decimal integer, which has the same
format as the subject sequence of the strtol() function with the
value 10 for the base argument. The corresponding argument should
be a pointer to unsigned int.
x Reads an optionally signed hexadecimal integer, which has the
same format as the subject sequence of the strtol() function with
the value 16 for the base argument. The corresponding argument
should be a pointer to unsigned int.
X In ANSI mode (cc -kansi), X behaves the same as x. In K&R mode
(cc -kcc), X behaves the same as lx.
[, l[
Reads a nonempty sequence of characters from a set of expected
bytes. The corresponding argument should be a pointer to the ini-
tial byte of an array large enough to accept the sequence,
including a terminating null byte, which will be added automati-
cally. The conversion specification includes all subsequent bytes
in the format string, up to and including the matching right
bracket ]. The bytes between the brackets comprise the scanset,
unless the byte after the left bracket is ^, in which case the
scanset contains all bytes that do not appear in the scanlist
between the circumflex and the right bracket. If the conversion
specifier begins with [] or [^], the right bracket character is
Page 5 Reliant UNIX 5.44 Printed 11/98
scanf(3S) scanf(3S)
in the scanlist and the closing bracket character is the matching
right bracket that ends the specification; otherwise the first
right bracket character is always the one that ends the specifi-
cation. A range of bytes in the scanset 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 - will stand for itself. The character - will
also stand for itself whenever it is the first or the last char-
acter in the scanlist. To include the right bracket as an element
of the scanset, it must appear as the first character (possibly
preceded by ^) of the scanlist and in this case it will not be
syntactically interpreted as the closing bracket. At least one
character must match for this conversion to be considered suc-
cessful.
If an l qualifier is present, the input shall be a sequence of
multibyte character conversions in the initial shift state. Each
multibyte character is converted to a wide-character as if by a
call to the mbrtowc() function, with the conversion state
described by an mbsstatet object initialized to zero before the
first multibyte character is converted. The corresponding argu-
ment shall be a pointer to an array of wchart large enough to
accept the resulting sequence of wide-characters. No null wide-
character is added.
% A single % is expected in the input at this point; no assignment
or conversion is done. The complete conversion specification must
be %%.
The h, l, or L modifier is ignored for all conversion specifiers other
than those listed.
If an invalid conversion character follows the %, the results of the
operation may not be predictable.
Each function allows for detection of a language-dependent decimal
point character in the input string. The decimal point character is
defined by the program's locale (LCNUMERIC). In the C locale, or in a
locale where the decimal point character is not defined, the decimal
point character defaults to a period.
The scanf() conversion terminates at end of file, at the end of the
control string, or when an input character conflicts with the control
string.
If end-of-file is reached before any characters matching the current
directive have been read (other than leading white space, where per-
mitted), execution of the current directive terminates with an input
failure. If the end-of-file is reached during execution of one of the
subsequent directives, conversion is terminated with an input failure.
Page 6 Reliant UNIX 5.44 Printed 11/98
scanf(3S) scanf(3S)
Trailing white space (including new-line characters) is left unread
unless matched by a conversion specification. The success of literal
matches and suppressed assignments is not directly determinable other
than via the %n directive.
EXAMPLES
The call to the function scanf():
int i, 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 the string thompson\0.
The call to the function scanf():
int i; float x; char name[50];
(void) scanf("%2d%f%*d %[0-9]", &i, &x, name);
with the input line:
56789 0123 56a72
will assign 56 to i, 789.0 to x, skip 0123, and place the characters
56\0 in name. The next character read from stdin will be a.
ERRORS
The following error code descriptions are function-specific. You will
find a general description in introprm2(2) or in errno(5).
The function will fail if data needs to be read and:
EAGAIN The ONONBLOCK flag is set for the file descriptor under-
lying stream and the process would be delayed in the
operation.
EBADF The file descriptor underlying stream is not a valid file
descriptor open for reading.
EINTR The read operation was terminated due to the receipt of a
signal, and no data was transferred.
EIO A physical I/O error has occurred, or the process is in a
background process group attempting to read from its con-
trolling terminal, and either the process is ignoring or
blocking the SIGTTIN signal or the process group is
orphaned. This error may also be generated for implemen-
tation-dependent reasons.
Page 7 Reliant UNIX 5.44 Printed 11/98
scanf(3S) scanf(3S)
EOVERFLOW The file is a regular file and an attempt was made to read
at or beyond the offset maximum associated with the corre-
sponding stream.
The function may fail if:
EILSEQ Input byte sequence does not form a valid character.
EINVAL There are insufficient arguments.
ENOMEM Insufficient storage space is available.
ENXIO A request was made of a non-existent device, or the
request was outside the capabilities of the device.
RETURN VALUES
These routines return the number of successfully matched and assigned
input items; this number can be zero in the event of an early matching
failure between an input character and the control string. If the
input ends before the first matching failure or conversion, EOF is
returned.
NOTES
If the application that calls fprintf() contains objects of type
wchart, the files sys/types.h and stddef.h must be linked.
In format strings containing the % form of conversion specifications,
each argument in the argument list is used exactly once.
The conversion codes C and S are supported from XPG4 mode onwards.
SEE ALSO
cc(1), strtod(3C), strtol(3C), printf(3S), lfs(5), stdio(5).
Page 8 Reliant UNIX 5.44 Printed 11/98