 |
Index for
Section 3 |
|
 |
Alphabetical
listing for S |
|
 |
Bottom of
page |
|
scanf(3)
NAME
scanf, fscanf, sscanf - Convert formatted input
SYNOPSIS
#include <stdio.h>
int scanf(
const char *format,
[,pointer]... );
int fscanf(
FILE *stream,
const char *format,
[,pointer]... );
int sscanf(
const char *string,
const char *format,
[,pointer]... );
If the pointer parameter identifies an object of type wchar_t (see the
Description section), source files should include either <sys/types.h> or
<stddef.h> before <stdio.h> to maintain portability across all systems that
conform to current versions of ANSI, ISO, or X/Open standards.
LIBRARY
Standard C Library (libc)
STANDARDS
Interfaces documented on this reference page conform to industry standards
as follows:
fscanf(), scanf(), sscanf(): ISO C, XPG4, XPG4-UNIX
Refer to the standards(5) reference page for more information about
industry standards and associated tags.
PARAMETERS
format
Specifies the format conversion.
stream
Specifies the input stream.
string
Specifies input to be read.
pointer
Points to the location to store the interpreted data.
DESCRIPTION
The scanf(), fscanf(), and sscanf() functions read character data,
interpret it according to a format, and store the converted results into
specified memory locations. The format parameter contains conversion
specifications used to interpret the input. The pointer parameters specify
where to store the interpreted data.
The functions read their input from the following sources:
scanf()
Reads from standard input (stdin).
fscanf()
Reads from the stream parameter.
sscanf()
Reads from the character string specified by the string parameter.
If the length of an input item is zero, these functions return an error.
This error indicates a matching failure unless end-of-file, an encoding
error, or a read error prevented input from a stream, in which case the
error indicates input failure.
If there are insufficient arguments for format, the function's behavior is
undefined. If format is exhausted while arguments remain, the excess
arguments are evaluated as always but are otherwise ignored.
These functions truncate leading zeroes (before a decimal point, if any).
If a string value exceeds its formatted type destination limit (as defined
by the machine architecture), the return value will be the corresponding
MIN or MAX value for the type, as appropriate, and an errno ERANGE value
will be set.
The format parameter can contain the following items:
- A conversion specification that directs the conversion of the next
input field. Conversion specifications start with a % (percent sign).
- Any white-space character (as determined by the isspace() function)
that matches 0 (zero) or more white-space characters in the input
stream.
- Any character except % (percent sign) or a white-space character that
must match the next character in the input stream.
The input stream is broken into fields based on the following:
- White space
All conversion specifications except %c, %C, and %[ ignore leading
white space and consider the first trailing white-space character as a
field delimiter.
- Invalid character
If the input stream contains a character that is not allowed, this
invalid character delimits the field and is considered to be the first
character of the next field.
- Maximum width
If the conversion specification includes a maximum width and the field
is not terminated by white space or an invalid character, the field is
terminated when that character position is reached in the input stream.
Conversion Specifications
Each conversion specification in the format parameter has the following
syntax:
- The character % (percent sign).
The scanf() functions can handle a format string that enables the
system to process elements of the pointer list in variable order. In
such a case, the normal conversion character % (percent sign) is
replaced by %digit$, where digit is a decimal number in the range from
1 to NL_ARGMAX. Conversion is then applied to the specified pointer,
not to the next unused pointer. This feature provides for the
definition of format strings in an order appropriate to specific
languages. If the variable ordering feature is used, it must be
specified for all conversions except for conversion specifications that
do not have corresponding pointers (conversion specifications with the
* (asterisk) assignment suppression and %% conversion specifications).
If more than one conversion specification specifies the same digit, the
results of the function are undefined.
- The optional assignment suppression character * (asterisk).
- An optional decimal digit string that specifies the maximum field
width.
- An optional h or l indicating the size of the receiving variable for
some conversion specifiers, as follows:
- An h followed by a d, i, o, u, or x conversion specifier indicates that
the receiving variable will be treated as a short int or unsigned short
int.
- An l followed by a d, i, o, u, or x conversion specifier indicates that
the receiving variable will be treated as a long int or unsigned long
int.
- An l followed by an e, f, or g indicates that the receiving variable
will be treated as a double instead of a float.
- An L followed by an e, f, or g indicates that the receiving variable
will be treated as a long double instead of a float.
- An l followed by a c, s, or [scanset] indicates that the receiving
variable will be treated as wchar_t instead of char.
- A conversion code character that specifies the type of conversion to be
applied:
% Accepts a single % (percent sign) input at this point; no assignment is
done.
d Accepts an optionally signed decimal integer, whose format is the same
as expected for the subject sequence of strtol() with the value 10 for
the base argument. The pointer parameter should be an integer pointer.
i Accepts an optionally signed decimal integer, whose format is the same
as expected for the subject sequence of strtol() with the value 0 for
the base argument. The pointer parameter should be an integer pointer.
u Accepts an unsigned decimal integer; the pointer parameter should be an
unsigned integer pointer.
o Accepts an octal integer; the pointer parameter should be an integer
pointer.
x Accepts a hexadecimal integer; the pointer parameter 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 the following optional
characteristics:
- It can be a signed value.
- 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.
- It can be one of the special values INF, NaNQ, or NaNS. This value is
translated into the ANSI/IEEE value for infinity, quiet NaN, or
signaling NaN, respectively.
p Matches an unsigned hexadecimal long integer, the same as the %p
conversion of the printf() function. The corresponding argument should
be a pointer to a pointer to void.
n No input is consumed. The corresponding argument is a pointer to an
integer into which is written the number of characters read from the
input stream by this function. The assignment count returned at the
completion of this function is not incremented.
s Accepts a string of bytes that are not white-space characters.
[ISO C] (When the current locale supports shift-state encoding,
skipping white-space characters may result in redundant shift
sequences.)
If no l qualifier is present, the pointer parameter should point to an
array of characters that is large enough to accept the converted
sequence of characters, along with the terminating null byte
automatically appended by the function. When interpreting the input
string, the function considers a white-space character as the delimiter
of each input field and generates a string of char values as output. If
a field width is given, the function assumes that pointer refers to a
single-byte character array, and only the specified number of char
values is read from the input string.
[ISO C] If an l qualifier is present, the input is treated as a
sequence of multibyte characters that begins in the initial shift
state. The function converts each multibyte character to a wide-
character as if by a call to the mbrtowc() function, with the
conversion state described by an mbstate_t object initialized to zero
before the first multibyte character is converted. The corresponding
pointer should point to a wchar_t array that is large enough to accept
the converted sequence of wide-characters, plus the terminating null
wide-character that is automatically added by the function.
S Accepts a string of multibyte characters and converts them as if by a
call to the mbstowcs() function. The pointer parameter should be a
pointer to an array of wchar_t. The array must be large enough to
accept the string, along with the terminating null wide-character that
is automatically added by the function. The function treats a white-
space character as the delimiter of each field in the input string and
generates a string of wchar_t as output. If the S conversion specifier
includes a field width, the behavior of the conversion is undefined.
c Accepts a sequence of characters, the number of which is specified by
the field width (1 if no field width is specified).
If the l qualifier is not present, the corresponding argument should be
a character array large enough to accept the converted sequence. The
function does not append a terminating null character to this sequence.
[ISO C] If the l qualifier is present, the corresponding argument is a
sequence of multibyte characters that begins in the initial shift
state. The function converts each multibyte character as if by a call
to the mbrtowc() function, with the conversion state described by an
mbstate_t object initialized to zero before conversion of the first
multibyte character. The corresponding argument should be a pointer to
the first element of a wchar_t array that is large enough to accept the
resulting sequence of wide-characters. The function does not append a
terminating null wide-character to this sequence.
The c directive suppresses the normal skip over white space; therefore,
use %1s instead of %1c to read the next nonwhite-space character.
C Accepts a single character or a series of characters and converts to
wchar_t type. If there is no field width or a field width of 1 in the
conversion specification, one character is accepted and the pointer
parameter should be a wchar_t pointer. If there is a field width
greater than 1, the indicated number of characters are accepted and the
pointer parameter should be an array of wchar_t. The normal skip over
white space is suppressed. Use %1S rather than %1C to read the next
nonwhite-space character.
[scanset]
Accepts as input the characters included in the scanset. The scanset
parameter explicitly defines the characters that are accepted in the
string data as those enclosed within [ ] (square brackets).
If the l qualifier is not present, the corresponding pointer parameter
should point to an array of char that is large enough to contain both
the converted sequence and the terminating null character that is
automatically added by the function.
[ISO C] If the l qualifier is present, the input is handled as a
sequence of multibyte characters that begins in the initial shift
state. The function converts each multibyte character as if by a call
to the mbrtowc() function, with the conversion state described by an
mbstate_t object initialized to zero before conversion of the first
multibyte character. The corresponding pointer parameter should be a
pointer to a wchar_t array that is large enough to accept both the
converted sequence and the terminating null wide-character that is
automatically added by the function.
The [scanset] directive suppresses the normal skip over leading white
space.
A scanset in the form of [^scanset] is an exclusive scanset; that is,
the ^ (circumflex) serves as a complement operator and the characters
in scanset are not accepted as input.
Conventions used in the construction of the scanset are as follows:
- 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; otherwise, the - (dash) stands
for itself. The dash also stands for itself whenever it is the first or
the last character in the scanset.
- You can include the ] (right bracket) as an element of the scanset if
it is the first character of the scanset. In this case, the right
bracket is not interpreted as the bracket that closes the scanset. If
the scanset is an exclusive scanset, the ] character is preceded by the
^ (circumflex) character to make the ] an element of the scanset.
The conversion specification syntax is summarized by the following
synopsis:
%[digit$][*][width][sizecode]convcode
The results from the conversion are placed in *pointer unless you specify
assignment suppression with an * (asterisk). 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 pointer must usually be of a restricted type. You should not
specify the pointer parameter for a suppressed field.
All *scanf() functions end at the end of the file, at the end of the
control string, or when an input character conflicts with the control
string. If the function ends with an input character conflict, the
conflicting character is not read from the input stream.
Unless there is a match in the control string, these functions do not read
trailing white space (including a newline character).
The success of literal matches and suppressed assignments cannot be
directly determined. The *scanf() functions return only the number of
successfully matched and assigned input items.
RESTRICTIONS
Currently, the Tru64 UNIX product does not include locales that use shift-
state encoding. Some sections of this reference page refer to the mb_state
object or describe behavior that is dependent on shift-state encoding. This
information is included only for your convenience in developing portable
applications that run on multiple platforms, some of which may supply
locales that do use shift-state encoding.
RETURN VALUES
The scanf(), fscanf(), and sscanf() functions return the number of
successfully matched and assigned input items. This number can be 0 (zero)
if there was an early conflict between an input character and the control
string. If the input ends before the first conflict or conversion, the
functions return EOF (End-of-File).
ERRORS
The fscanf() function fails if the stream is unbuffered or if the stream's
buffer needs to be flushed and the function call causes an underlying
read() or lseek() to be invoked and that operation fails. In addition, the
scanf(), fscanf(), and sscanf() functions set errno to the corresponding
value for the following conditions:
[EAGAIN]
[Tru64 UNIX] The O_NONBLOCK option is set for the underlying stream
and the process would be delayed by the read operation.
[EBADF]
[Tru64 UNIX] The file descriptor underlying the stream is not a valid
file descriptor or is not open for reading.
[EILSEQ]
The input byte sequence does not form a valid character.
[EINTR]
[Tru64 UNIX] The read operation was interrupted by a signal that was
caught and no data was transferred.
[EIO]
[Tru64 UNIX] The call is attempting to read from the process's
controlling terminal and either the process group is orphaned or the
process is ignoring or blocking the SIGTTIN signal.
[ENOMEM]
[Tru64 UNIX] Insufficient memory is available for the operation.
[ERANGE]
[Tru64 UNIX] One or more of the following errors: The result would
exceed the system-defined limits or cause an overflow (value too large)
or an underflow (value too small). The magnitude of x is such that
total or partial loss of significance resulted.
SEE ALSO
Functions: atof(3), atoi(3), getc(3), getwc(3), mbstowcs(3), mbtowc(3),
printf(3), wprintf(3), wscanf(3)
Standards: standards(5)
|
Index for
Section 3 |
|
|
Alphabetical
listing for S |
|
 |
Top of
page |
|