'\"macro stdmacro
.if n .pH g3s.scanf @(#)scanf	40.19 of 10/10/89
.\" Copyright 1989 AT&T
'\" ident	"@(#)svid_ba:ba_lib/scanf	1.18"
.nr X
.if \nX=0 .ds x} scanf 3S "" "\&"
.if \nX=1 .ds x} scanf 3S ""
.if \nX=2 .ds x} scanf 3S "" "\&"
.if \nX=3 .ds x} scanf "" "" "\&"
.TH \*(x}
.SH NAME
\f4scanf\f1, \f4fscanf\f1, \f4sscanf\f1 \- convert formatted input
.SH SYNOPSIS
.nf
.ft 4
#include <stdio.h>
.sp .5
int scanf(const char \(**format, ...);
.sp .5
int fscanf(FILE \(**strm, const char \(**format, ...);
.sp .5
int sscanf(const char \(**s, const char \(**format, ...);
.ft 1
.fi
.SH DESCRIPTION
\f4scanf\f1 reads from the standard input stream,
\f4stdin\f1.
.P
\f4fscanf\f1 reads from the stream \f2strm\f1.
.P
\f4sscanf\f1 reads from the character string \f2s\f1.
.P
Each function reads characters, interprets them according to a format,
and stores the results in its arguments.
Each expects, as arguments, a control string, \f2format\f1, 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.
.P
The control string usually contains conversion specifications, which are used to direct interpretation of input sequences.
The control string may contain:
.P
.RS 5
.TP 4
1.
White-space characters (blanks, tabs, new-lines, or form-feeds) that,
except in two cases described below, cause input to be read up to the next
non-white-space character.
.TP 4
2.
An ordinary character (not \f4%\f1) that must match the next character
of the input stream.
.TP 4
3.
Conversion specifications consisting of the character \f4%\f1
or the character sequence \f4%\f2digits\f4$\f1,
an optional assignment suppression character \f4\(**\f1, a decimal digit
string that specifies an optional numerical maximum field width,
an optional letter \f4l\f1 (ell), \f4L\f1, or \f4h\f1
indicating the size of the
receiving object, and a conversion code.
The conversion specifiers \f4d\f1, \f4i\f1, and \f4n\f1
should be preceded by \f4h\f1 if the corresponding
argument is a pointer to \f4short int\f1
rather than a pointer to \f4int\f1, or by \f4l\f1
if it is a pointer to \f4long int\f1.
Similarly, the conversion specifiers
\f4o\f1, \f4u\f1, and \f4x\f1 should be preceded
by \f4h\f1 if the corresponding argument is a pointer
to \f4unsigned short int\f1 rather than a pointer to
\f4unsigned int\f1, or by \f4l\f1 if it is a pointer
to \f4unsigned long int\f1.
Finally, the conversion specifiers \f4e\f1, \f4f\f1, and \f4g\f1
should be preceded by \f4l\f1 if the corresponding argument
is a pointer to \f4double\f1 rather than a pointer to \f4float\f1,
or by \f4L\f1 if it is a pointer to \f4long double\f1.
The \f4h\f1, \f4l\f1, or \f4L\f1 modifier is ignored
with any other conversion specifier.
.RE
.P
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 \f4\(**\f1.
The suppression of assignment provides a way of describing an input field that is 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 maximum  field width, if one is specified, is exhausted.
For all descriptors except the character \f4[\f1 and the character \f4c\f1, white space leading an input field is ignored.
.P
Conversions can be applied to the \f2nth\f1 argument in the argument list,
rather than to the next unused argument.
In this case, the conversion character
\f4%\f1 (see above) is replaced by the sequence \f4%\f2digits\f4$\f1
where \f2digits\f1 is a decimal integer \f2n\f1,
giving the position of the argument in the argument
list.
The first such argument, \f4%1$\f1, immediately follows \f2format\f1.
The control string can contain either form of a conversion
specification, i.e., \f4%\f1 or \f4%\f2digits\f4$\f1, although the two forms cannot be
mixed within a single control string.
.P
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:
.TP
\f4%\f1
A single \f4%\f1 is expected in the input at this point; no assignment is done.
.TP
\f4d\f1
Matches an optionally signed decimal integer,
whose format is the same as expected for the
subject sequence of the \f4strtol\f1 function
with the value 10 for the \f2base\f1 argument.
The corresponding argument should be a pointer to integer.
.TP
\f4u\f1
Matches an optionally signed decimal integer, whose format is the
same as expected for the subject sequence of the \f4strtoul\f1 function
with the value 10 for the \f2base\f1 argument.
The corresponding argument should be a pointer
to unsigned integer.
.TP
\f4o\f1
Matches an optionally signed octal integer, whose format
is the same as expected for the subject sequence of the
\f4strtoul\f1 function with the value 8 for the \f2base\f1 argument.
The corresponding argument should be a pointer to unsigned integer.
.TP
\f4x\f1
Matches an optionally signed hexadecimal integer,
whose format is the same as expected for the subject sequence
of the \f4strtoul\f1 function with the value 16 for
the \f2base\f1 argument.
The corresponding argument should be a pointer to unsigned integer.
.TP
\f4i\f1
Matches an optionally signed integer, whose format is the same as
expected for the subject sequence of the \f4strtol\f1 function
with the value 0 for the \f2base\f1 argument.
The corresponding argument should be a pointer to integer.
.TP
\f4n\f1
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 \f4%n\f1 directive
does not increment the assignment count
returned at the completion of execution of the function.
.TP
\f4e\f1,\f4f\f1,\f4g\f1
Matches an optionally signed floating point number,
whose format is the same as expected for the
subject string of the \f4strtod\f1 function.
The corresponding argument should be a pointer to floating.
.TP
\f4s\f1
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 \f4\e0\f1, which will be added automatically.
The input field is terminated by a white-space character.
.TP
\f4c\f1
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.
.TP
\f4[\f1
Matches a nonempty sequence of characters
from a set of expected characters (the \f2scanset\f1).
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 \f2format\f1
string, up to and including the matching right bracket (\f4]\f1).
The characters between the brackets (the \f2scanlist\f1)
comprise the scanset, unless the character after the left bracket
is a circumflex (\f4^\f1), 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 \f4[]\f1 or
\f4[^]\f1, 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.
.IP
A range of characters in the scanset
may be represented by the construct 
\f2first\f1 \f4\-\f1 \f2last\f1;
thus \f4[0123456789]\f1 may be expressed \f4[0\-9]\f1. 
Using this convention, \f2first\f1 must be lexically less than or equal to \f2last\f1, or else the dash will stand for itself. 
The character \f4\-\f1 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.
.TP
\f4p\f1
Matches an implementation-defined set of sequences,
which should be the same as the set of sequences that
may be produced by the \f4%p\f1 conversion of the
\f4printf\f1 function. The corresponding argument
should be a pointer to \f4void\f1. 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 \f4%p\f1 conversion is undefined. 
.P
If an invalid conversion character follows the \f4%\f1, the results of the operation may not be predictable.
.P
The conversion specifiers \f4E\f1, \f4G\f1, and \f4X\f1 are also 
valid and, under the \f4-Xa\fP and \f4-Xc\fP compilation modes [see \f4cc\fP(1)],
behave the same as \f4e\f1, \f4g\f1, and \f4x\f1, respectively.
Under the \f4-Xt\fP compilation mode, \f4E\f1, \f4G\f1, and \f4X\f1
behave the same as \f4le\f1, \f4lg\f1, and \f4lx\f1, respectively.
.P
Each function allows for detection of a language-dependent decimal point
character in the input string. The decimal point character is defined by
the program's locale (category \f4LC_NUMERIC\f1). In the
\f4"C"\f1 locale, or in a locale where the decimal point character is not
defined, the decimal point character defaults to a period (\f4.\f1).
.P
The \f4scanf\f1 conversion terminates at end of file, at the end of the control string, or when an input character conflicts with the control string.
.P
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 (if any) is terminated with an input failure.
.P
If conversion terminates on a conflicting input character, the
offending input character is left unread in the input stream.
Trailing white space (including new-line 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 \f4%n\f1 directive.
.SH EXAMPLES
The call to the function \f4scanf\f1:
.P
.RS
.nf
.ft 4
int\ i,\ n;\ float\ x;\ char\ name[50];
n\ =\ scanf ("%d%f%s",\ &i,\ &x,\ name);
.ft 1
.fi
.RE
.P
with the input line:
.P
.RS
.nf
.ft 4
25\ 54.32E\-1\ thompson
.ft 1
.fi
.RE
.P
will assign to \f4n\f1 the value \f43\f1,
to \f4i\f1 the value \f425\f1,
to \f4x\f1 the value \f45.432\f1,
and \f4name\f1 will contain \f4thompson\e0\f1.
.P
The call to the function \f4scanf\f1:
.P
.RS
.nf
.ft 4
int\ i;\ float\ x;\ char\ name[50];
(void)\ scanf ("%2d%f%\(**d\ %[0\-9]",\ &i,\ &x,\ name);
.ft 1
.fi
.RE
.P
with the input line:
.P
.RS
.nf
.ft 4
56789\ 0123\ 56a72
.ft 1
.fi
.RE
.P
will assign \f456\f1 to \f4i\f1,
\f4789.0\f1 to \f4x\f1, skip \f40123\f1,
and place the characters \f456\e0\f1 in \f4name\f1.
The next character read from \f4stdin\f1 will be \f4a\f1.
.SH "SEE ALSO"
\f4cc\fP(1),
\f4printf\fP(3S),
\f4strtod\fP(3C),
\f4strtol\fP(3C),
\f4strtoul\fP(3C).
.SH DIAGNOSTICS
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,
\f4EOF\f1 is returned.
