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 scanf function reads from the standard input stream stdin. The fscanf function reads from the named input stream. The sscanf 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 scanf; that is, the function skips the field.

wSpecifies the maximum field width.

lSpecifies that the variable where the input value is stored is a longword integer or a double-precision variable. The scanf function ignores the l if the input field is a character string or a pointer.

hSpecifies that the variable where the input value is stored is a short integer or floating-point variable. The scanf function ignores the h if the input field is a character string or a pointer.

typeSpecifies 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 scanf 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 scanf 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 scanf to ignore leading white space in the input field. Normally, scanf 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 scanf function stores the result of each conversion in the pointer that corresponds to the conversion specification. Thus, the conversion specification controls how scanf converts the first unread input field, and scanf stores the result in the first pointer. The second conversion specification controls how scanf converts the next input field. The scanf 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 scanf 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 inappropriate character or EOF. An inappropriate character is one that is not valid for the value scanf is reading. For example, the letter “z” is invalid for an integer value. If the scanf 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, scanf ignores leading white space in an input field.

The conversion code controls how scanf 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 scanf 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 an unsigned 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 (\0). The scanf 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 scanf function reads white space in the input field, including leading white space. To cause scanf 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 scanf function adds the termination character automatically.

Following the left bracket, you specify a list of characters and a right bracket ( ] ). The scanf function reads the input field until it encounters a character other than those listed between the brackets. The scanf 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 characters. The circumflex causes scanf 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, scanf 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, scanf interprets it as an octal value. If the field begins with “0X” or “0x, scanf 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 scanf function maintains a running total of the number of input fields it has read so far. This conversion code causes scanf 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, scanf uses the radix character and collating sequence that is defined by the last successful call to setlocale category LC_NUMERIC or LC_COLLATE. If the radix or collating sequence is undefined, the scanf function uses the C locale definitions.

International Environment

LC_NUMERICIf this environment is set and valid, scanf uses the international language database named in the definition to determine radix character rules.

LANGIf this environment variable is set and valid scanf uses the international language database named in the definition to determine collation and character classification rules. If LC_NUMERIC is defined, its definition supersedes the definition of LANG.

Restrictions

You cannot directly determine whether conversion codes that cause scanf to ignore data (for example, brackets and asterisks) succeeded.

The scanf function ignores any trailing white-space characters, including a newline character. If you want scanf to read a trailing white-space character, include the character in the conversion code for the data item that contains it.

Examples

The following shows an example of calling the scanf function:

int i, n; float x; char name[50];
n = scanf("%d%f%s", &i, &x, name);

Suppose the input to the scanf function appear as follows:

25 54.32E−1 thompson

In this case, scanf 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 scanf 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 scanf 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 scanf 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 scanf function returns the number of successfully matched and assigned input fields. This number can be zero if the scanf 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, scanf 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.

Museum

Related Articles