scanf(3s)scanf(3s)Name
scanf, fscanf, sscanf - convert formatted input
Syntax
#include < stdio.h >
int scanf ( format [, pointer ] ... )
char *format;
int fscanf ( stream, format [, pointer ] ... )
FILE *stream;
char *format;
int sscanf ( s, format [, pointer ] ... )
char *s, *format;
Description
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, and a set of pointer arguments that indicate
where to store the converted input. The function reads from the stan‐
dard input stream stdin. The function reads from the named input
stream. The function reads from the character string s.
In the format string you specify how to convert the input stream. You
may use one or more conversion specifications in a single format
string, depending on the number of pointer arguments you specify.
Conversion specifications are introduced by a percent sign and specify
the format of one input field. You may also use spaces, tabs, form
feeds, new-line characters, alphabetic characters, and numbers in the
format string. The following list describes conversion specifications
and the other components of a format string:
· Conversion specifications have the following format:
%[*][w][l][h][code]
Each conversion specification must be introduced by a percent
sign. The rest of the conversion specification is optional and
has the following purpose:
* Specifies that an input field in the input string is not read by
that is, the function skips the field.
w Specifies the maximum field width.
l Specifies that the variable where the input value is stored is a
longword integer or a double-precision variable. The function
ignores the l if the input field is a character string or a
pointer.
h Specifies that the variable where the input value is stored is a
short integer or floating-point variable. The function ignores
the h if the input field is a character string or a pointer.
type Specifies the conversion code. Possible values for the conversion
code are described in the paragraphs that follow.
· Alphabetic characters and numbers that appear inside the format
string, but not in a conversion specification, specify that ignore
those characters in the input string.
· The white-space characters in a format string that appear outside
of a conversion specification normally have no effect on how for‐
mats data. The exception is when the white space character pre‐
cedes the c conversion code in the format string. In this case,
the white space causes to ignore leading white space in the input
field. Normally, treats leading white space as part of the input
character string for the c conversion code.
Each conversion specification in the format string directs the conver‐
sion of the next input field. The function stores the result of each
conversion in the pointer that corresponds to the conversion specifica‐
tion. Thus, the conversion specification controls how converts the
first unread input field, and stores the result in the first pointer.
The second conversion specification controls how converts the next
input field. The function stores the result of the second conversion
in the second pointer, and so on.
You do not include pointers for conversion specifications that contain
the asterisk character. These specifications cause to ignore an input
field, so no pointer storage is needed.
An input field is defined as a string of non-space characters; it
begins at the first unread character and extends to the first inappro‐
priate character or EOF. An inappropriate character is one that is not
valid for the value is reading. For example, the letter ``z'' is
invalid for an integer value. If the function does not reach EOF and
encounters no inappropriate characters, the field width is the number
of characters specified by w. For all conversion codes except left-
bracket ( [) and c, ignores leading white space in an input field.
The conversion code controls how converts an input field. The data
type of a pointer that corresponds to a conversion specification must
match the conversion code. For example, the pointer that corresponds
to a c conversion code must point to a character variable. The pointer
that corresponds to a d conversion code must point to an integer, and
so on. The following list describes the valid conversion codes:
% The input field is a percent sign. The function does not move
any value to pointer.
d D The input field is a decimal integer; the corresponding pointer
must point to an integer. If you specify h , pointer can point
to a short integer.
u U The input field is a decimal integer; pointer must point to an
unsigned integer.
o 0 The input field is octal integer is expected; the corresponding
pointer must point to an integer. If you specify h , pointer
can be a short integer.
x X The input field is a hexadecimal integer; the corresponding
pointer must point to an integer pointer. If you specify h,
pointer can be a short integer.
e,f,g The input field is an optionally signed string of digits. The
field may contain a radix character and an exponent field begins
with a letter E or e, followed by an optional sign or space and
an integer. The pointer must point to a floating-point vari‐
able. If you specify l, pointer must point to a double-preci‐
sion variable.
s The input field is a character string. The pointer must point
to an array of characters large enough to contain the string and
a termination character (\0). The function adds the termination
character automatically. A white-space character terminates the
input field, so the input field cannot contain spaces.
c The input field is a character or character string. The pointer
must point to either a character variable or a character array.
The function reads white space in the input field, including
leading white space. To cause to ignore white space, you can
include a space in front of the conversion specification that
includes the c.
[ The input field is a character string. The pointer must point
to an array of characters large enough to contain the string and
a termination character (\0). The function adds the termination
character automatically.
Following the left bracket, you specify a list of characters and
a right bracket ( ] ). The function reads the input field until
it encounters a character other than those listed between the
brackets. The function ignores white-space characters.
You can change the meaning of the characters within the brackets
by including a circumflex (^) character before the list of char‐
acters. The circumflex causes to read the input field until it
encounters one of the characters in the list.
You can represent a range of characters by specifying the first
character, a hyphen (-), and the last character. For example,
you can express [0123456789] using [0-9]. When you use a hyphen
to represent a range of characters, the first character you
specify must precede or be equal to the last character you spec‐
ify in the current collating sequence. If the last character
sorts before the first character, the hyphen stands for itself.
The hyphen also stands for itself when it is the first or the
last character that appears within the brackets.
To include the right square bracket as a character within the
list, put the right bracket first in the list. If the right
bracket is preceded by any character other than the circumflex,
interprets it as a closing bracket.
At least one input character must be valid for this conversion
to be considered successful.
i The input field is an integer. If the field begins with a zero,
interprets it as an octal value. If the field begins with
``0X'' or ``0x, interprets it as a hexadecimal value. The
pointer must point to an integer. If you specify h, pointer can
point to a short integer.
n The function maintains a running total of the number of input
fields it has read so far. This conversion code causes to store
that total in the integer that corresponds to pointer.
p The input field is a pointer. The pointer must point to an
integer variable.
In all cases, uses the radix character and collating sequence that is
defined by the last successful call to category or If the radix or col‐
lating sequence is undefined, the function uses the C locale defini‐
tions.
International Environment
LC_NUMERIC If this environment is set and valid, uses the interna‐
tional language database named in the definition to
determine radix character rules.
LANG If this environment variable is set and valid uses the
international language database named in the definition
to determine collation and character classification
rules. If is defined, its definition supersedes the
definition of LANG.
Restrictions
You cannot directly determine whether conversion codes that cause to
ignore data (for example, brackets and asterisks) succeeded.
The function ignores any trailing white-space characters, including a
newline character. If you want to read a trailing white-space charac‐
ter, include the character in the conversion code for the data item
that contains it.
The (libc) has been updated. The %n code now processes even if no fur‐
ther input remains to be scanned.
Examples
The following shows an example of calling the function:
int i, n; float x; char name[50];
n = scanf("%d%f%s", &i, &x, name);
Suppose the input to the function appear as follows:
25 54.32E-1 thompson
In this case, assigns the value 25 to the i variable and the value
5.432 to the x variable. The character variable name receives the
value thompson\0. The function returns the value 3 to the n variable
because it read and assigned three input fields.
The following example demonstrates using the d conversion code to cause
to ignore characters:
int i; float x; char name[5];
scanf("%2d%f %*d %[0-9]", &i, &x, name);
Suppose the following shows the input to the function:
56789 0123 56a72
In this case, the function assigns the value 56 to the i variable and
the value 789.0 to the x variable. The function ignores the 0123 input
field, because the %*d conversion specification causes to skip one
input field. The function assigns 56 to name; it reads the first two
characters in the last input field and stops at the third character.
The letter 'a' is not in the set of characters from 0 to 9.
Return Values
The function returns the number of successfully matched and assigned
input fields. This number can be zero if the function encounters
invalid input characters, as specified by the conversion specification,
before it can assign input characters.
If the input ends before the first conflict or conversion, returns EOF.
These functions return EOF on end of input and a short count for miss‐
ing or invalid data items.
Environment
In POSIX mode, the E, F, and X formats are treated the same as the e,
f, and x formats, respectively; otherwise, the upper-case formats
expect double, double, and long arguments, respectively.
See Alsoatof(3), nl_scanf(3int), getc(3s), printf(3s), environ(5int)
Guide to Developing International Software
scanf(3s)
