NAME

scanf, fscanf, sscanf, nl_scanf, nl_fscanf, nl_sscanf − formatted input conversion, read from stream file

SYNOPSIS

#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;

int nl_scanf (format [ , pointer ] ... )
char ∗format;

int nl_fscanf (stream, format [ , pointer ] ... )
FILE ∗stream;
char ∗format;

int nl_sscanf (s, format [ , pointer ] ... )
char ∗s, ∗format;

DESCRIPTION

Scanf and nl_scanf read from the standard input stream stdin.

Fscanf and nl_fscanf read from the named input stream.

Sscanf and nl_sscanf read from the character string s.

Each function reads characters, interprets them according to the control string format argument, and stores the results in its pointer arguments.  The control string contains conversion specifications and other characters used to direct interpretation of input sequences.  The control string contains:

• White-space characters (blanks, tabs, newlines, or formfeeds) that cause input to be read up to the next non-white-space character (except in two cases described below). 

• An ordinary character (not %) that must match the next character of the input stream. 

• Conversion specifications, consisting of the character %, an optional assignment suppressing character ∗, an optional numerical maximum-field width, an optional l (ell) or h indicating the size of the receiving variable, and a conversion code. 

• For nl_scanf, nl_fscanf and nl_sscanf only, the conversion specification may alternatively be prefixed by the character sequence %n$ instead of the character %, where n is a decimal integer in the range (1-{NL_ARGMAX}) (NL_ARGMAX is defined in <limits.h>).  The %n$ construction indicates that the value of the next input field should be placed in the nth argument, rather than to the next unused one.  The user is responsible for ensuring that each argument is used exactly once.  The results are undefined otherwise.  The two forms of introducing a conversion specification, % and %n$, may not be mixed within a single format string with the following exception: Skip fields (see below) can be designated as %∗ or %n$∗.  In the latter case, n is ignored. 

A conversion specification directs the conversion of the next input field; the result is placed in the variable that the corresponding argument points to, unless ∗ indicates assignment suppression.  Assignment suppression provides a way to describe an input field to be skipped.  An input field is defined as a string of non-space characters; it extends to the next inappropriate character or until the field width, if specified, is exhausted.  For all descriptors except “[” and “c”, white space leading an input field is ignored. 

The conversion code indicates the interpretation of the input field; the corresponding pointer argument must be of a restricted type.  For a suppressed field, no pointer argument is given.  The following conversion codes are legal:

% A single % is expected in the input at this point; no assignment is done. 

d A decimal integer is expected; the corresponding argument should be an integer pointer. 

u An unsigned decimal integer is expected; the corresponding argument should be an unsigned integer pointer. 

o An octal integer is expected; the corresponding argument should be an integer pointer. 

x A hexadecimal integer is expected; the corresponding argument should be an integer pointer. 

e,f,g A 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 radix character, followed by an optional exponent field consisting of an E or an e, followed by an optional +, −, or space, followed by an integer.  The radix character is specified by the currently loaded NLS environment (see nl_init(3C)). If nl_init has not been called successfully, the default NLS environment "n-computer" is used which specifies a period (.) as the radix character. 

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 is added automatically.  The input field is terminated by a white-space character.  Scanf will not read a null string. 

c A character is expected; the corresponding argument should be a character pointer.  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 refers to a character array; the indicated number of characters is read. 

[ Indicates string data and the normal skip over leading white space is suppressed.  The left bracket is followed by a set of characters, called 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.  Construction of the scanset follows certain conventions.  A range of characters may be represented by the construct first−last, enabling [0123456789] to be expressed [0−9].  Using this convention, first must be lexically less than or equal to last; otherwise, the dash stands for itself.  The dash also stands for itself when 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, in which case it will not be interpreted syntactically 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 are added automatically.  At least one character must match for this conversion to succeed. 

The conversion characters d, u, o, and x can be preceded by l or h to indicate that a pointer to long or short rather than to int is in the argument list.  Similarly, the conversion characters e, f, and g can be preceded by l to indicate that a pointer to double rather than to float is in the argument list.  The l or h modifier is ignored for other conversion characters. 

The scanf functions terminate their conversions at EOF, at the end of the control string, or when an input character conflicts with the control string.  In the latter case, the offending character is left unread in the input stream. 

The scanf functions return the number of successfully matched and assigned input items; this number can be zero if an early conflict ensues between an input character and the control string.  If the input ends before the first conflict or conversion, EOF is returned. 

RETURN VALUES

These functions return EOF on end of input and a short count for missing or illegal data items.  Error handling for the nl_scanf routines differ depending on what kind of format string is used.  When a non-numbered argument format string is used, the routines behave just like scanf and return the number of successful assignments before the error.  When a numbered argument format string is used and an error occurs, the routines return 0 (zero) for no matches and no assignments are done. 

EXAMPLES

The call:

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 thompson\0.  Or:

int i; float x; char name[50];
(void) scanf("%2d%f%∗d %[0−9]", &i, &x, name);

with input:

56789 0123 56a72

will assign 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. 

For another example, to create a language-independent date scanning routine, write:

char month[20]; int day, year;
(void) nl_scanf(format, month, &day, &year);

For American usage, format would point to a string:

"%1$s %2$d %3$d"

The input:

July 3 1986

would assign July to month, 3 to day and 1986 to year.

For German usage, format would point to a string:

"%2$d %1$s %3$d"

The input:

3 Juli 1986

would assign Juli to month, 3 to day and 1986 to year.

WARNINGS

Trailing white space (including a newline) is left unread unless matched in the control string. 

The success of literal matches and suppressed assignments is not directly determinable. 

Asian characters are not allowed within format strings. 

HARDWARE DEPENDENCIES

Series 200, 300, 500
Nl_scanf, nl_fscanf, and nl_sscanf are currently not supported. 

NLS radix support is currently not available. 

AUTHOR

Scanf was developed by AT&T and HP. 

SEE ALSO

getc(3S), nl_init(3C), printf(3S), strtod(3C), strtol(3C). 

INTERNATIONAL SUPPORT

8-bit data. 

Hewlett-Packard Company  —  Version B.1,  May 11, 2021