SCANF(3s,L) AIX Technical Reference SCANF(3s,L)
-------------------------------------------------------------------------------
scanf, fscanf, sscanf, NLscanf, NLfscanf, NLsscanf, wsscanf
PURPOSE
Converts formatted input.
LIBRARY
Standard I/O Library (libc.a)
SYNTAX
#include <stdio.h>
int scanf (fmt [, ptr, ... ]int NLscanf (fmt [, ptr, ... ])
char *fmt; char *fmt;
int fscanf (stream, fmt [, pint NLfscanf (stream, fmt [, ptr, ... ])
FILE *stream; FILE *stream;
char *fmt; char *fmt;
int sscanf (s, fmt [, ptr, .int]NLsscanf (s, fmt [, ptr, ... ])
char *s, *fmt; char *s, *fmt;
int wsscanf (wcs, fmt [, ptr, ...])
wchar_t *wcs;
char *fmt;
DESCRIPTION
The scanf, fscanf, and sscanf subroutines read character data, interpret it
according to a format, and store the converted results into specified memory
locations. The NLscanf, NLfscanf, and NLsscanf subroutines parallel their
corresponding functions, providing conversion types to handle NLchars as well
as chars. The wsscanf subroutine is equivalent to sscanf, except that the
argument wcs specifies a wide character string from which the input is
obtained, rather than a string. Reaching the end of the wide character string
is equivalent to reaching the end of string for sscanf. If copying takes place
between objects that overlap, the behavior is undefined. These subroutines
read their input from the following sources:
scanf, NLscanf Reads from standard input (stdin).
fscanf, NLfscanf Reads from stream.
sscanf, NLsscanf Reads from the character string s.
Processed November 7, 1990 SCANF(3s,L) 1
SCANF(3s,L) AIX Technical Reference SCANF(3s,L)
wsscanf Reads from the wide character string s.
The fmt parameter contains conversion specifications used to interpret the
input. The ptr parameters specify where to store the interpreted data.
The fmt parameter can contain the following:
o White space characters (blanks, tabs, new-lines, or form-feeds) which,
except in two cases described following, reads the input up to the next
nonwhite space character. Unless there is a match in the control string,
trailing white space (including a new-line character) is not read.
o Any character except "%" (percent), which must match the next one or more
characters of the input stream.
o A conversion specification that directs the conversion of the next input
field. It consists of the following:
- The character "%" (percent)
- An optional assignment suppression character, * (asterisk)
- An optional numeric maximum field width
- An optional character that sets the size of the receiving variable as
for some flags, as follows:
l Signed long integer rather than an int when preceding the d, u, o
or x conversion codes. A double rather than a float, when
preceding the e, f or g conversion codes.
h Signed short integer (half int) rather than an int when preceding
the d, u, o or x conversion codes.
- A conversion code.
Each conversion specification in the fmt parameter has a "%" (percent sign) or
the character sequence "%digit$", which introduces the conversion
specification.
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 replaced by the sequence "%digit$", where digit is a decimal integer n in
the range of [1, {NL_ARGMAX}], giving the position of the argument inthe
argument list. With this feature, format strings can be defined to assure that
arguments are selected in an order appropriate for the specified language.
%[*][width][size]convcode
The results from the conversion are placed in *ptr unless you specify
assignment suppression with *. Assignment suppression provides a way to
describe an input field that is to be skipped. The input field is a string of
nonwhite-space characters. It extends to the next inappropriate character or
until the field width, if specified, is exhausted.
The conversion code indicates how to interpret the input field. The
corresponding ptr must usually be of a restricted type. You should not specify
ptr for a suppressed field. You can use the following conversion codes:
Processed November 7, 1990 SCANF(3s,L) 2
SCANF(3s,L) AIX Technical Reference SCANF(3s,L)
% Accepts a single "%" input at this point; no assignment is done.
d Accepts a decimal integer; ptr should be an integer pointer.
u Accepts an unsigned decimal integer; ptr should be an unsigned
integer pointer.
o Accepts an octal integer; ptr should be an integer pointer.
x Accepts a hexadecimal integer; ptr should be an integer pointer.
e, f, g Accepts a floating-point number. The next field is converted
accordingly and stored through the corresponding parameter, which
should be a pointer to a float. The input format for floating-point
numbers is a string of digits, with some optional characteristics:
o It can be a signed value.
o It can be an exponential value, containing a decimal point
followed by an exponent field, which consists of an E or an e
followed by an (optionally signed) integer.
o It can be one of the special values INF, QNaN, or SNaN, which is
translated into the ANSI/IEEE value for infinity, quiet NaN, or
signalling NaN, respectively.
s Accepts a string of chars. The ptr parameter should be a character
pointer that points to an array of characters large enough to accept
the string and ending with "'\0'". The "'\0'" is added
automatically. The input field ends with a white space character.
A string of chars is output.
S (Used by the NLscanf, NLfscanf, and NLsscanf subroutines only.)
Accepts an NLchar string. The ptr parameter should point to an
array of characters large enough to accept the string and end with
"'\0'". The "'\0'" is added automatically. The input field ends
with a white space character. A string of NLchars is output.
N (Used by the NLscanf, NLfscanf, and NLsscanf subroutines only.)
Accepts an ASCII string, possibly containing extended character
information in the form of escape sequences used by the NLescstr and
NLunescstr subroutines. (See "display symbols" for a list of these
escape sequences.) The output is in the form of NLchars.
c A character is expected. The ptr parameter should be a character
pointer. The normal skip over white space is suppressed. Use "%"1s
to read the next nonwhite-space character. If a field width is
given, ptr should refer to a character array; the indicated number
of characters is read.
wc Matches a sequence of multibyte characters of the number specified
by the field width (1 if no field width is present in the
directive). The corresponding argument is a pointer to the initial
Processed November 7, 1990 SCANF(3s,L) 3
SCANF(3s,L) AIX Technical Reference SCANF(3s,L)
wide character of an array large enough to accept the sequence
resulting from the conversion. This conversion is the same as that
performed by the mbstowcs routine.
ws Matches a sequence of non-white space multibyte characters. The
corresponding argument is a pointer to the initial wide character of
an array large enough to accept the sequence resulting from the
conversion and a terminating NULL wide character, which is added
automatically. This conversion is the same as that performed by the
mbstowcs subroutine.
[scanset] Accepts as input the characters included in the scanset. The
scanset explicitly defines the characters that are accepted in the
string data as those enclosed within square brackets. The normal
skip over leading white space is suppressed. A scanset in the form
of [^scanset] is an exclusive scanset: the ^ (circumflex) serves as
a complement operator and the following characters in the scanset
are not accepted as input. Conventions used in the construction of
the scanset follow:
o You can represent a range of characters by the construct
first-last. Thus you can express [0123456789] as [0-9]. The
first parameter must be lexically less than or equal to last, or
else the - (dash) stands for itself. The - also stands for
itself whenever it is the first or the last character in the
scanset.
o The range of characters, which is locale dependent, is
determined by the current locale's collation table.
o You can include the ] (right bracket), as an element of the
scanset, if it is the first character of the scanset. In this
case it is not interpreted as the bracket that closes the
scanset. If the scanset is an exclusive scanset, the ] is
preceded by the ^ (circumflex) to make the ] an element of the
scanset. The corresponding ptr must point to a character array
large enough to hold the data field and that ends with "'\0'".
The "'\0'" is added automatically.
A scanf or NLscanf conversion ends at the end-of-file, the end of the control
string, or when an input character conflicts with the control string. If it
ends with an input character conflict, the character that conflicts is not read
from the input stream.
Note: Unless there is a match in the control string, trailing blanks
(including a new-line character) are not read.
The success of literal matches and suppressed assignments is not directly
determinable.
RETURN VALUE
Processed November 7, 1990 SCANF(3s,L) 4
SCANF(3s,L) AIX Technical Reference SCANF(3s,L)
The scanf and NLscanf subroutines return the number of successfully matched and
assigned input items. This number can be 0 if there was an early conflict
between an input character and the control string. If the input ends before
the first conflict or conversion, only EOF is returned.
The wsscanf subroutine returns the value of the macro EOF if an input failure
occurs before any conversion. Otherwise, wsscanf returns the number of input
items assigned, which can be fewer than provided for, or even zero in the event
of an early matching failure.
EXAMPLES
1. To read several values and assign them to variables:
int i;
float x;
char name[50];
scanf ("%d%f%s", &i, &x, name);
with the input line:
25 54.32E-1 thompson
This assigns to "i" the value "25", to "x" the value "5.432", and to "name"
the value "thompson\0".
2. To perform simple pattern-matching while scanning the input:
int i;
float x;
char name[50];
scanf ("%2d%f%*d %[0-9]", &i, &x, name);
with the input:
56789 0123 56a72
This assigns "56" to "i", "789.0" to "x", skips "0123", and places the
string "56\0" in "name". The next call to getchar returns "a". (See
"getc, fgetc, getchar, getw, getwc, fgetwc, getwchar.")
RELATED INFORMATION
In this book: "getc, fgetc, getchar, getw, getwc, fgetwc, getwchar," "printf,
fprintf, sprintf, NLprintf, NLfprintf, NLsprintf, wsprintf," "stdio," "strtod,
atof," "strtol, atol, atoi," "limits.h," and "display symbols."
"Introduction to International Character Support" in Managing the AIX Operating
System.
Processed November 7, 1990 SCANF(3s,L) 5
SCANF(2,L) AIX Technical Reference SCANF(2,L)
AIX Guide to Multibyte Character Set (MBCS) Support.
Processed November 7, 1990 SCANF(2,L) 6