scanf(3S) DG/UX R4.11MU05 scanf(3S)
NAME
scanf, fscanf, sscanf - convert formatted input
SYNOPSIS
#include <stdio.h>
int scanf(const char *format, ...);
int fscanf(FILE *strm, const char *format, ...);
int sscanf(const char *s, const char *format, ...);
DESCRIPTION
scanf reads from the standard input stream, stdin.
fscanf reads from the stream strm.
sscanf reads from the character string s.
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, described below, 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 undefined. If the format is exhausted while arguments
remain, the excess arguments are simply ignored.
The control string contains zero or more of the following directives:
1. White-space characters (blanks, tabs, newlines, or form-
feeds) that cause input to be read up to the next non-white-
space character.
2. An ordinary character (not %) that must match the next
character of the input stream.
3. Conversion specifications consisting of the character % or
the character sequence %digits$, an optional assignment
suppression character *, an optional decimal digit string
that specifies a maximum field width, an optional letter l
(ell), L, or h indicating the size of the receiving object,
and a conversion code. The conversion specifiers d, i, and
n should be preceded by h if the corresponding argument is a
pointer to short int rather than a pointer to int, or by l
if it is a pointer to long int. Similarly, the conversion
specifiers b, o, u, and x should be preceded by h if the
corresponding argument is a pointer to unsigned short int
rather than a pointer to unsigned int, or by l if it is a
pointer to unsigned long int. Finally, the conversion
specifiers a, e, f, and g should be preceded by l if the
corresponding argument is a pointer to double rather than a
pointer to float, or by L if it is a pointer to long double.
The h, l, or L modifier causes undefined behavior with any
other conversion specifier.
A conversion specification directs the conversion of the next input
field; the result is placed in the variable pointed to by the
corresponding argument unless assignment suppression was indicated by
the character *. The suppression of assignment provides a way of
describing an input field that is to be skipped. An input field is
usually defined as a string of non-space characters; it extends to
the next inappropriate character or until the maximum field width, if
one is specified, is exhausted. For all descriptors except [, c and
C, white space leading an input field is ignored.
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 followed by the sequence digits$ where
digits is a decimal integer n, giving the position of the argument in
the argument list. The argument that follows format is numbered 1.
The control string can contain either form of a conversion
specification, i.e., % or %digits$, although the two forms generally
should not be mixed within a single control string.
The conversion code indicates the interpretation of the input field;
the corresponding pointer argument must usually be of a restricted
type. For a suppressed field, no pointer argument is given. The
following conversion codes are valid:
% A single % is expected in the input at this point; no
assignment is done.
b Matches an optionally signed binary integer, whose format is
the same as expected for the subject sequence of the strtol
function with the value 2 for the base argument. The
corresponding argument should be a pointer to integer.
d Matches an optionally signed decimal integer, whose format is
the same as expected for the subject sequence of the strtol
function with the value 10 for the base argument. The
corresponding argument should be a pointer to integer.
i Matches an optionally signed integer, whose format is the same
as expected for the subject sequence of the strtol function
with the value 0 for the base argument. The corresponding
argument should be a pointer to integer.
n No input is consumed. The corresponding argument should be a
pointer to integer into which is to be written the number of
characters read from the input stream so far by the call to
the function. Execution of a %n directive does not increment
the assignment count returned at the completion of execution
of the function.
o Matches an optionally signed octal integer, whose format is
the same as expected for the subject sequence of the strtoul
function with the value 8 for the base argument. The
corresponding argument should be a pointer to unsigned
integer.
u Matches an optionally signed decimal integer, whose format is
the same as expected for the subject sequence of the strtoul
function with the value 10 for the base argument. The
corresponding argument should be a pointer to unsigned
integer.
x Matches an optionally signed hexadecimal integer, whose format
is the same as expected for the subject sequence of the
strtoul function with the value 16 for the base argument. The
corresponding argument should be a pointer to unsigned
integer.
a,e,f,g
Matches an optionally signed floating point number, whose
format is the same as expected for the subject string of the
strtod function. The corresponding argument should be a
pointer to floating.
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 will be added automatically. The input field is
terminated by a white-space character.
c Matches 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 should be a pointer to
the initial character of an array large enough to accept the
sequence. No null character is added. The normal skip over
white space is suppressed.
[ Matches a nonempty sequence of characters from a set of
expected characters (the scanset). The corresponding argument
should be a pointer to the initial character of an array large
enough to accept the sequence and a terminating null
character, which will be added automatically. The conversion
specifier includes all subsequent characters in the format
string, up to and including the matching right bracket (]).
The characters between the brackets (the scanlist) comprise
the scanset, unless the character after the left bracket is a
circumflex (^), in which case the scanset contains all
characters 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 in the
scanlist and the next right bracket character is the matching
right bracket that ends the specification; otherwise the first
right bracket character is the one that ends the
specification.
A range of characters 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 the dash will stand for itself.
The character - will also stand for itself whenever it is the
first or the last character in the scanlist. To include the
right bracket as an element of the scanset, it must appear as
the first character (possibly preceded by a circumflex) 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 successful.
p Matches an implementation-defined set of sequences, which
should be the same as the set of sequences that may be
produced by the %p conversion of the printf function. The
corresponding argument should be a pointer to void. The
interpretation of the input item is implementation-defined. If
the input item is a value converted earlier during the same
program execution, the pointer that results shall compare
equal to that value; otherwise, the behavior of the %p
conversion is undefined.
C Matches a sequence of multibyte characters that are converted
to a wide character. The number of wide characters matched is
specified by the field width or 1 if no field width is
specified in the directive. The corresponding argument is a
pointer to the initial element of an array of wchart large
enough to accept the resulting sequence of wide characters.
No null wide character is added.
S Matches a sequence of multibyte characters. None of the
multibyte characters in the sequence are also single-byte
white space characters as specified by the isspace function.
Each multibyte character is converted to a wide character.
The corresponding argument is a pointer to the initial element
of an array of wchart large enough to accept the sequence and
the terminating null wide character, which is added
automatically.
If an invalid conversion specification follows the %, the behavior is
undefined.
The conversion specifiers A, B, E, G, and X are also valid and, under
the -Xa and -Xc compilation modes [see cc(1)], behave the same as a,
b, e, g, and x, respectively. Under the -Xt compilation mode, A B,
E, G, and X behave the same as la, lb, le, lg, and lx, respectively.
Each function allows for acceptance of a language-dependent decimal-
point character in the input string. The decimal-point character is
defined by the program's locale (category LCNUMERIC). The default
decimal-point character is 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 encountered during input, conversion is terminated.
If end-of-file occurs before any characters matching the current
directive have been read (other than leading white space, where
permitted), execution of the current directive terminates with an
input failure; otherwise, unless execution of the current directive
is terminated with a matching failure, execution of the following
directive (other than %n, if any) is terminated with an input
failure.
If conversion terminates on a conflicting input character, the
offending input character is left unread in the input stream.
Trailing white space (including newline characters) is left unread
unless matched by a directive. The success of literal matches and
suppressed assignments is not directly determinable other than via
the %n directive.
Errors
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.
Considerations for Threads Programming
+---------+-----------------------------+
| | async- |
|function | reentrant cancel cancel |
| | point safe |
+---------+-----------------------------+
|fscanf | Y Y N |
|scanf | Y Y N |
|sscanf | Y N N |
+---------+-----------------------------+
USAGE
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 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.
REFERENCES
cc(1), reentrant(3), flockfile(3S), printf(3S), strtod(3C),
strtol(3C).
Licensed material--property of copyright holder(s)