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 argu-
ments, a control string, format, and a set of pointer arguments that indicate where to store the converted input. The function reads from
the standard 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:
o 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.
o 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.
o The white-space characters in a format string that appear outside of a conversion specification normally have no effect on how formats
data. The exception is when the white space character precedes 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 conversion of the next input field. The function stores the result of each
conversion in the pointer that corresponds to the conversion specification. 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 inappropri-
ate 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 variable. If you
specify l, pointer must point to a double-precision 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 ( ). 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 ( ). 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 charac-
ters. 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 specify 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
collating sequence is undefined, the function uses the C locale definitions.
International Environment
LC_NUMERIC If this environment is set and valid, uses the international 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.
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 . 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
missing 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 Also
atof(3), nl_scanf(3int), getc(3s), printf(3s), environ(5int)
Guide to Developing International Software
scanf(3s)