1053 lines
21 KiB
HTML
1053 lines
21 KiB
HTML
|
|
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
|
|
<HTML><HEAD><TITLE>Man page of SCANF</TITLE>
|
|
</HEAD><BODY>
|
|
<H1>SCANF</H1>
|
|
Section: Linux Programmer's Manual (3)<BR>Updated: 2019-03-06<BR><A HREF="#index">Index</A>
|
|
<A HREF="/cgi-bin/man/man2html">Return to Main Contents</A><HR>
|
|
|
|
<A NAME="lbAB"> </A>
|
|
<H2>NAME</H2>
|
|
|
|
scanf, fscanf, sscanf, vscanf, vsscanf, vfscanf - input format conversion
|
|
<A NAME="lbAC"> </A>
|
|
<H2>SYNOPSIS</H2>
|
|
|
|
<PRE>
|
|
<B>#include <<A HREF="file:///usr/include/stdio.h">stdio.h</A>></B>
|
|
|
|
<B>int scanf(const char *</B><I>format</I><B>, ...);</B>
|
|
<B>int fscanf(FILE *</B><I>stream</I><B>, const char *</B><I>format</I><B>, ...);</B>
|
|
<B>int sscanf(const char *</B><I>str</I><B>, const char *</B><I>format</I><B>, ...);</B>
|
|
|
|
<B>#include <<A HREF="file:///usr/include/stdarg.h">stdarg.h</A>></B>
|
|
|
|
<B>int vscanf(const char *</B><I>format</I><B>, va_list </B><I>ap</I><B>);</B>
|
|
<B>int vsscanf(const char *</B><I>str</I><B>, const char *</B><I>format</I><B>, va_list </B><I>ap</I><B>);</B>
|
|
<B>int vfscanf(FILE *</B><I>stream</I><B>, const char *</B><I>format</I><B>, va_list </B><I>ap</I><B>);</B>
|
|
</PRE>
|
|
|
|
<P>
|
|
|
|
|
|
Feature Test Macro Requirements for glibc (see
|
|
<B><A HREF="/cgi-bin/man/man2html?7+feature_test_macros">feature_test_macros</A></B>(7)):
|
|
|
|
|
|
|
|
<P>
|
|
|
|
<B>vscanf</B>(),
|
|
|
|
<B>vsscanf</B>(),
|
|
|
|
<B>vfscanf</B>():
|
|
|
|
<DL COMPACT><DT id="1"><DD>
|
|
_ISOC99_SOURCE || _POSIX_C_SOURCE >= 200112L
|
|
|
|
</DL>
|
|
|
|
<A NAME="lbAD"> </A>
|
|
<H2>DESCRIPTION</H2>
|
|
|
|
The
|
|
<B>scanf</B>()
|
|
|
|
family of functions scans input according to
|
|
<I>format</I>
|
|
|
|
as described below.
|
|
This format may contain
|
|
<I>conversion specifications</I>;
|
|
|
|
the results from such conversions, if any,
|
|
are stored in the locations pointed to by the
|
|
<I>pointer</I>
|
|
|
|
arguments that follow
|
|
<I>format</I>.
|
|
|
|
Each
|
|
<I>pointer</I>
|
|
|
|
argument must be of a type that is appropriate for the value returned
|
|
by the corresponding conversion specification.
|
|
<P>
|
|
|
|
If the number of conversion specifications in
|
|
<I>format</I>
|
|
|
|
exceeds the number of
|
|
<I>pointer</I>
|
|
|
|
arguments, the results are undefined.
|
|
If the number of
|
|
<I>pointer</I>
|
|
|
|
arguments exceeds the number of conversion specifications, then the excess
|
|
<I>pointer</I>
|
|
|
|
arguments are evaluated, but are otherwise ignored.
|
|
<P>
|
|
|
|
The
|
|
<B>scanf</B>()
|
|
|
|
function reads input from the standard input stream
|
|
<I>stdin</I>,
|
|
|
|
<B>fscanf</B>()
|
|
|
|
reads input from the stream pointer
|
|
<I>stream</I>,
|
|
|
|
and
|
|
<B>sscanf</B>()
|
|
|
|
reads its input from the character string pointed to by
|
|
<I>str</I>.
|
|
|
|
<P>
|
|
|
|
The
|
|
<B>vfscanf</B>()
|
|
|
|
function is analogous to
|
|
<B><A HREF="/cgi-bin/man/man2html?3+vfprintf">vfprintf</A></B>(3)
|
|
|
|
and reads input from the stream pointer
|
|
<I>stream</I>
|
|
|
|
using a variable argument list of pointers (see
|
|
<B><A HREF="/cgi-bin/man/man2html?3+stdarg">stdarg</A></B>(3).
|
|
|
|
The
|
|
<B>vscanf</B>()
|
|
|
|
function scans a variable argument list from the standard input and the
|
|
<B>vsscanf</B>()
|
|
|
|
function scans it from a string; these are analogous to the
|
|
<B><A HREF="/cgi-bin/man/man2html?3+vprintf">vprintf</A></B>(3)
|
|
|
|
and
|
|
<B><A HREF="/cgi-bin/man/man2html?3+vsprintf">vsprintf</A></B>(3)
|
|
|
|
functions respectively.
|
|
<P>
|
|
|
|
The
|
|
<I>format</I>
|
|
|
|
string consists of a sequence of
|
|
<I>directives</I>
|
|
|
|
which describe how to process the sequence of input characters.
|
|
If processing of a directive fails, no further input is read, and
|
|
<B>scanf</B>()
|
|
|
|
returns.
|
|
A "failure" can be either of the following:
|
|
<I>input failure</I>,
|
|
|
|
meaning that input characters were unavailable, or
|
|
<I>matching failure</I>,
|
|
|
|
meaning that the input was inappropriate (see below).
|
|
<P>
|
|
|
|
A directive is one of the following:
|
|
<DL COMPACT>
|
|
<DT id="2">•<DD>
|
|
A sequence of white-space characters (space, tab, newline, etc.; see
|
|
<B><A HREF="/cgi-bin/man/man2html?3+isspace">isspace</A></B>(3)).
|
|
|
|
This directive matches any amount of white space,
|
|
including none, in the input.
|
|
<DT id="3">•<DD>
|
|
An ordinary character (i.e., one other than white space or '%').
|
|
This character must exactly match the next character of input.
|
|
<DT id="4">•<DD>
|
|
A conversion specification,
|
|
which commences with a '%' (percent) character.
|
|
A sequence of characters from the input is converted according to
|
|
this specification, and the result is placed in the corresponding
|
|
<I>pointer</I>
|
|
|
|
argument.
|
|
If the next item of input does not match the conversion specification,
|
|
the conversion fails---this is a
|
|
<I>matching failure</I>.
|
|
|
|
</DL>
|
|
<P>
|
|
|
|
Each
|
|
<I>conversion specification</I>
|
|
|
|
in
|
|
<I>format</I>
|
|
|
|
begins with either the character '%' or the character sequence
|
|
"<B>%</B><I>n</I><B>$</B>"
|
|
(see below for the distinction) followed by:
|
|
<DL COMPACT>
|
|
<DT id="5">•<DD>
|
|
An optional '*' assignment-suppression character:
|
|
<B>scanf</B>()
|
|
|
|
reads input as directed by the conversion specification,
|
|
but discards the input.
|
|
No corresponding
|
|
<I>pointer</I>
|
|
|
|
argument is required, and this specification is not
|
|
included in the count of successful assignments returned by
|
|
<B>scanf</B>().
|
|
|
|
<DT id="6">•<DD>
|
|
For decimal conversions, an optional quote character (').
|
|
This specifies that the input number may include thousands'
|
|
separators as defined by the
|
|
<B>LC_NUMERIC</B>
|
|
|
|
category of the current locale.
|
|
(See
|
|
<B><A HREF="/cgi-bin/man/man2html?3+setlocale">setlocale</A></B>(3).)
|
|
|
|
The quote character may precede or follow the '*'
|
|
assignment-suppression character.
|
|
<DT id="7">•<DD>
|
|
An optional 'm' character.
|
|
This is used with string conversions
|
|
(<I>%s</I>,
|
|
|
|
<I>%c</I>,
|
|
|
|
<I>%[</I>),
|
|
|
|
and relieves the caller of the
|
|
need to allocate a corresponding buffer to hold the input: instead,
|
|
<B>scanf</B>()
|
|
|
|
allocates a buffer of sufficient size,
|
|
and assigns the address of this buffer to the corresponding
|
|
<I>pointer</I>
|
|
|
|
argument, which should be a pointer to a
|
|
<I>char *</I>
|
|
|
|
variable (this variable does not need to be initialized before the call).
|
|
The caller should subsequently
|
|
<B><A HREF="/cgi-bin/man/man2html?3+free">free</A></B>(3)
|
|
|
|
this buffer when it is no longer required.
|
|
<DT id="8">•<DD>
|
|
An optional decimal integer which specifies the
|
|
<I>maximum field width</I>.
|
|
|
|
Reading of characters stops either when this maximum is reached or
|
|
when a nonmatching character is found, whichever happens first.
|
|
Most conversions discard initial white space characters (the exceptions
|
|
are noted below),
|
|
and these discarded characters don't count toward the maximum field width.
|
|
String input conversions store a terminating null byte ('\0')
|
|
to mark the end of the input;
|
|
the maximum field width does not include this terminator.
|
|
<DT id="9">•<DD>
|
|
An optional
|
|
<I>type modifier character</I>.
|
|
|
|
For example, the
|
|
<B>l</B>
|
|
|
|
type modifier is used with integer conversions such as
|
|
<B>%d</B>
|
|
|
|
to specify that the corresponding
|
|
<I>pointer</I>
|
|
|
|
argument refers to a
|
|
<I>long int</I>
|
|
|
|
rather than a pointer to an
|
|
<I>int</I>.
|
|
|
|
<DT id="10">•<DD>
|
|
A
|
|
<I>conversion specifier</I>
|
|
|
|
that specifies the type of input conversion to be performed.
|
|
</DL>
|
|
<P>
|
|
|
|
The conversion specifications in
|
|
<I>format</I>
|
|
|
|
are of two forms, either beginning with '%' or beginning with
|
|
"<B>%</B><I>n</I><B>$</B>".
|
|
The two forms should not be mixed in the same
|
|
<I>format</I>
|
|
|
|
string, except that a string containing
|
|
"<B>%</B><I>n</I><B>$</B>"
|
|
specifications can include
|
|
<B>%%</B>
|
|
|
|
and
|
|
<B>%*</B>.
|
|
|
|
If
|
|
<I>format</I>
|
|
|
|
contains '%'
|
|
specifications, then these correspond in order with successive
|
|
<I>pointer</I>
|
|
|
|
arguments.
|
|
In the
|
|
"<B>%</B><I>n</I><B>$</B>"
|
|
form (which is specified in POSIX.1-2001, but not C99),
|
|
<I>n</I>
|
|
|
|
is a decimal integer that specifies that the converted input should
|
|
be placed in the location referred to by the
|
|
<I>n</I>-th
|
|
|
|
<I>pointer</I>
|
|
|
|
argument following
|
|
<I>format</I>.
|
|
|
|
<A NAME="lbAE"> </A>
|
|
<H3>Conversions</H3>
|
|
|
|
The following
|
|
<I>type modifier characters</I>
|
|
|
|
can appear in a conversion specification:
|
|
<DL COMPACT>
|
|
<DT id="11"><B>h</B>
|
|
|
|
<DD>
|
|
Indicates that the conversion will be one of
|
|
<B>d</B>, <B>i</B>, <B>o</B>, <B>u</B>, <B>x</B>, <B>X</B>, or <B>n</B>
|
|
and the next pointer is a pointer to a
|
|
<I>short int</I>
|
|
|
|
or
|
|
<I>unsigned short int</I>
|
|
|
|
(rather than
|
|
<I>int</I>).
|
|
|
|
<DT id="12"><B>hh</B>
|
|
|
|
<DD>
|
|
As for
|
|
<B>h</B>,
|
|
|
|
but the next pointer is a pointer to a
|
|
<I>signed char</I>
|
|
|
|
or
|
|
<I>unsigned char</I>.
|
|
|
|
<DT id="13"><B>j</B>
|
|
|
|
<DD>
|
|
As for
|
|
<B>h</B>,
|
|
|
|
but the next pointer is a pointer to an
|
|
<I>intmax_t</I>
|
|
|
|
or a
|
|
<I>uintmax_t</I>.
|
|
|
|
This modifier was introduced in C99.
|
|
<DT id="14"><B>l</B>
|
|
|
|
<DD>
|
|
Indicates either that the conversion will be one of
|
|
<B>d</B>, <B>i</B>, <B>o</B>, <B>u</B>, <B>x</B>, <B>X</B>, or <B>n</B>
|
|
and the next pointer is a pointer to a
|
|
<I>long int</I>
|
|
|
|
or
|
|
<I>unsigned long int</I>
|
|
|
|
(rather than
|
|
<I>int</I>),
|
|
|
|
or that the conversion will be one of
|
|
<B>e</B>, <B>f</B>, or <B>g</B>
|
|
and the next pointer is a pointer to
|
|
<I>double</I>
|
|
|
|
(rather than
|
|
<I>float</I>).
|
|
|
|
Specifying two
|
|
<B>l</B>
|
|
|
|
characters is equivalent to
|
|
<B>L</B>.
|
|
|
|
If used with
|
|
<B>%c</B>
|
|
|
|
or
|
|
<B>%s</B>,
|
|
|
|
the corresponding parameter is considered
|
|
as a pointer to a wide character or wide-character string respectively.
|
|
|
|
<DT id="15"><B>L</B>
|
|
|
|
<DD>
|
|
Indicates that the conversion will be either
|
|
<B>e</B>, <B>f</B>, or <B>g</B>
|
|
and the next pointer is a pointer to
|
|
<I>long double</I>
|
|
|
|
or the conversion will be
|
|
<B>d</B>, <B>i</B>, <B>o</B>, <B>u</B>, or <B>x</B>
|
|
and the next pointer is a pointer to
|
|
<I>long long</I>.
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
<DT id="16"><B>q</B>
|
|
|
|
<DD>
|
|
equivalent to
|
|
<B>L</B>.
|
|
|
|
This specifier does not exist in ANSI C.
|
|
<DT id="17"><B>t</B>
|
|
|
|
<DD>
|
|
As for
|
|
<B>h</B>,
|
|
|
|
but the next pointer is a pointer to a
|
|
<I>ptrdiff_t</I>.
|
|
|
|
This modifier was introduced in C99.
|
|
<DT id="18"><B>z</B>
|
|
|
|
<DD>
|
|
As for
|
|
<B>h</B>,
|
|
|
|
but the next pointer is a pointer to a
|
|
<I>size_t</I>.
|
|
|
|
This modifier was introduced in C99.
|
|
</DL>
|
|
<P>
|
|
|
|
The following
|
|
<I>conversion specifiers</I>
|
|
|
|
are available:
|
|
<DL COMPACT>
|
|
<DT id="19"><B>%</B>
|
|
|
|
<DD>
|
|
Matches a literal '%'.
|
|
That is,
|
|
<B>%%</B>
|
|
|
|
in the format string matches a
|
|
single input '%' character.
|
|
No conversion is done (but initial white space characters are discarded),
|
|
and assignment does not occur.
|
|
<DT id="20"><B>d</B>
|
|
|
|
<DD>
|
|
Matches an optionally signed decimal integer;
|
|
the next pointer must be a pointer to
|
|
<I>int</I>.
|
|
|
|
<DT id="21"><B>D</B>
|
|
|
|
<DD>
|
|
Equivalent to
|
|
<I>ld</I>;
|
|
|
|
this exists only for backward compatibility.
|
|
(Note: thus only in libc4.
|
|
In libc5 and glibc the
|
|
<B>%D</B>
|
|
|
|
is silently ignored, causing old programs to fail mysteriously.)
|
|
<DT id="22"><B>i</B>
|
|
|
|
<DD>
|
|
Matches an optionally signed integer; the next pointer must be a pointer to
|
|
<I>int</I>.
|
|
|
|
The integer is read in base 16 if it begins with
|
|
<I>0x</I>
|
|
|
|
or
|
|
<I>0X</I>,
|
|
|
|
in base 8 if it begins with
|
|
<I>0</I>,
|
|
|
|
and in base 10 otherwise.
|
|
Only characters that correspond to the base are used.
|
|
<DT id="23"><B>o</B>
|
|
|
|
<DD>
|
|
Matches an unsigned octal integer; the next pointer must be a pointer to
|
|
<I>unsigned int</I>.
|
|
|
|
<DT id="24"><B>u</B>
|
|
|
|
<DD>
|
|
Matches an unsigned decimal integer; the next pointer must be a
|
|
pointer to
|
|
<I>unsigned int</I>.
|
|
|
|
<DT id="25"><B>x</B>
|
|
|
|
<DD>
|
|
Matches an unsigned hexadecimal integer; the next pointer must
|
|
be a pointer to
|
|
<I>unsigned int</I>.
|
|
|
|
<DT id="26"><B>X</B>
|
|
|
|
<DD>
|
|
Equivalent to
|
|
<B>x</B>.
|
|
|
|
<DT id="27"><B>f</B>
|
|
|
|
<DD>
|
|
Matches an optionally signed floating-point number; the next pointer must
|
|
be a pointer to
|
|
<I>float</I>.
|
|
|
|
<DT id="28"><B>e</B>
|
|
|
|
<DD>
|
|
Equivalent to
|
|
<B>f</B>.
|
|
|
|
<DT id="29"><B>g</B>
|
|
|
|
<DD>
|
|
Equivalent to
|
|
<B>f</B>.
|
|
|
|
<DT id="30"><B>E</B>
|
|
|
|
<DD>
|
|
Equivalent to
|
|
<B>f</B>.
|
|
|
|
<DT id="31"><B>a</B>
|
|
|
|
<DD>
|
|
(C99) Equivalent to
|
|
<B>f</B>.
|
|
|
|
<DT id="32"><B>s</B>
|
|
|
|
<DD>
|
|
Matches a sequence of non-white-space characters;
|
|
the next pointer must be a pointer to the initial element of a
|
|
character array that is long enough to hold the input sequence and
|
|
the terminating null byte ('\0'), which is added automatically.
|
|
The input string stops at white space or at the maximum field
|
|
width, whichever occurs first.
|
|
<DT id="33"><B>c</B>
|
|
|
|
<DD>
|
|
Matches a sequence of characters whose length is specified by the
|
|
<I>maximum field width</I>
|
|
|
|
(default 1); the next pointer must be a pointer to
|
|
<I>char</I>,
|
|
|
|
and there must be enough room for all the characters
|
|
(no terminating null byte is added).
|
|
The usual skip of leading white space is suppressed.
|
|
To skip white space first, use an explicit space in the format.
|
|
<DT id="34"><B>[</B>
|
|
|
|
<DD>
|
|
Matches a nonempty sequence of characters from the specified set of
|
|
accepted characters; the next pointer must be a pointer to
|
|
<I>char</I>,
|
|
|
|
and there must be enough room for all the characters in the string, plus a
|
|
terminating null byte.
|
|
The usual skip of leading white space is suppressed.
|
|
The string is to be made up of characters in (or not in) a particular set;
|
|
the set is defined by the characters between the open bracket
|
|
<B>[</B>
|
|
|
|
character and a close bracket
|
|
<B>]</B>
|
|
|
|
character.
|
|
The set
|
|
<I>excludes</I>
|
|
|
|
those characters if the first character after the open bracket is a
|
|
circumflex
|
|
(<B>^</B>).
|
|
|
|
To include a close bracket in the set, make it the first character after
|
|
the open bracket or the circumflex; any other position will end the set.
|
|
The hyphen character
|
|
<B>-</B>
|
|
|
|
is also special; when placed between two other characters, it adds all
|
|
intervening characters to the set.
|
|
To include a hyphen, make it the last
|
|
character before the final close bracket.
|
|
For instance,
|
|
<B>[^]0-9-]</B>
|
|
|
|
means
|
|
the set "everything except close bracket, zero through nine, and hyphen".
|
|
The string ends with the appearance of a character not in the (or, with a
|
|
circumflex, in) set or when the field width runs out.
|
|
<DT id="35"><B>p</B>
|
|
|
|
<DD>
|
|
Matches a pointer value (as printed by
|
|
<B>%p</B>
|
|
|
|
in
|
|
<B><A HREF="/cgi-bin/man/man2html?3+printf">printf</A></B>(3);
|
|
|
|
the next pointer must be a pointer to a pointer to
|
|
<I>void</I>.
|
|
|
|
<DT id="36"><B>n</B>
|
|
|
|
<DD>
|
|
Nothing is expected; instead, the number of characters consumed thus far
|
|
from the input is stored through the next pointer, which must be a pointer
|
|
to
|
|
<I>int</I>.
|
|
|
|
This is
|
|
<I>not</I>
|
|
|
|
a conversion and does
|
|
<I>not</I>
|
|
|
|
increase the count returned by the function.
|
|
The assignment can be suppressed with the
|
|
<B>*</B>
|
|
|
|
assignment-suppression character, but the effect on the
|
|
return value is undefined.
|
|
Therefore
|
|
<B>%*n</B>
|
|
|
|
conversions should not be used.
|
|
</DL>
|
|
<A NAME="lbAF"> </A>
|
|
<H2>RETURN VALUE</H2>
|
|
|
|
On success, these functions return the number of input items
|
|
successfully matched and assigned;
|
|
this can be fewer than provided for,
|
|
or even zero, in the event of an early matching failure.
|
|
<P>
|
|
|
|
The value
|
|
<B>EOF</B>
|
|
|
|
is returned if the end of input is reached before either the first
|
|
successful conversion or a matching failure occurs.
|
|
<B>EOF</B>
|
|
|
|
is also returned if a read error occurs,
|
|
in which case the error indicator for the stream (see
|
|
<B><A HREF="/cgi-bin/man/man2html?3+ferror">ferror</A></B>(3))
|
|
|
|
is set, and
|
|
<I>errno</I>
|
|
|
|
is set to indicate the error.
|
|
<A NAME="lbAG"> </A>
|
|
<H2>ERRORS</H2>
|
|
|
|
<DL COMPACT>
|
|
<DT id="37"><B>EAGAIN</B>
|
|
|
|
<DD>
|
|
The file descriptor underlying
|
|
<I>stream</I>
|
|
|
|
is marked nonblocking, and the read operation would block.
|
|
<DT id="38"><B>EBADF</B>
|
|
|
|
<DD>
|
|
The file descriptor underlying
|
|
<I>stream</I>
|
|
|
|
is invalid, or not open for reading.
|
|
<DT id="39"><B>EILSEQ</B>
|
|
|
|
<DD>
|
|
Input byte sequence does not form a valid character.
|
|
<DT id="40"><B>EINTR</B>
|
|
|
|
<DD>
|
|
The read operation was interrupted by a signal; see
|
|
<B><A HREF="/cgi-bin/man/man2html?7+signal">signal</A></B>(7).
|
|
|
|
<DT id="41"><B>EINVAL</B>
|
|
|
|
<DD>
|
|
Not enough arguments; or
|
|
<I>format</I>
|
|
|
|
is NULL.
|
|
<DT id="42"><B>ENOMEM</B>
|
|
|
|
<DD>
|
|
Out of memory.
|
|
<DT id="43"><B>ERANGE</B>
|
|
|
|
<DD>
|
|
The result of an integer conversion would exceed the size
|
|
that can be stored in the corresponding integer type.
|
|
</DL>
|
|
<A NAME="lbAH"> </A>
|
|
<H2>ATTRIBUTES</H2>
|
|
|
|
For an explanation of the terms used in this section, see
|
|
<B><A HREF="/cgi-bin/man/man2html?7+attributes">attributes</A></B>(7).
|
|
|
|
<TABLE BORDER>
|
|
<TR VALIGN=top><TD><B>Interface</B></TD><TD><B>Attribute</B></TD><TD><B>Value</B><BR></TD></TR>
|
|
<TR VALIGN=top><TD>
|
|
<B>scanf</B>(),
|
|
|
|
<B>fscanf</B>(),
|
|
|
|
<BR>
|
|
|
|
<B>sscanf</B>(),
|
|
|
|
<B>vscanf</B>(),
|
|
|
|
<BR>
|
|
|
|
<B>vsscanf</B>(),
|
|
|
|
<B>vfscanf</B>()
|
|
|
|
</TD><TD>Thread safety</TD><TD>MT-Safe locale<BR></TD></TR>
|
|
</TABLE>
|
|
|
|
<P>
|
|
<A NAME="lbAI"> </A>
|
|
<H2>CONFORMING TO</H2>
|
|
|
|
The functions
|
|
<B>fscanf</B>(),
|
|
|
|
<B>scanf</B>(),
|
|
|
|
and
|
|
<B>sscanf</B>()
|
|
|
|
conform to C89 and C99 and POSIX.1-2001.
|
|
These standards do not specify the
|
|
<B>ERANGE</B>
|
|
|
|
error.
|
|
<P>
|
|
|
|
The
|
|
<B>q</B>
|
|
|
|
specifier is the 4.4BSD notation for
|
|
<I>long long</I>,
|
|
|
|
while
|
|
<B>ll</B>
|
|
|
|
or the usage of
|
|
<B>L</B>
|
|
|
|
in integer conversions is the GNU notation.
|
|
<P>
|
|
|
|
The Linux version of these functions is based on the
|
|
<I>GNU</I>
|
|
|
|
<I>libio</I>
|
|
|
|
library.
|
|
Take a look at the
|
|
<I>info</I>
|
|
|
|
documentation of
|
|
<I>GNU</I>
|
|
|
|
<I>libc (glibc-1.08)</I>
|
|
|
|
for a more concise description.
|
|
<A NAME="lbAJ"> </A>
|
|
<H2>NOTES</H2>
|
|
|
|
<A NAME="lbAK"> </A>
|
|
<H3>The 'a' assignment-allocation modifier</H3>
|
|
|
|
Originally, the GNU C library supported dynamic allocation for string inputs
|
|
(as a nonstandard extension) via the
|
|
<B>a</B>
|
|
|
|
character.
|
|
(This feature is present at least as far back as glibc 2.0.)
|
|
Thus, one could write the following to have
|
|
<B>scanf</B>()
|
|
|
|
allocate a buffer for an input string,
|
|
with a pointer to that buffer being returned in
|
|
<I>*buf</I>:
|
|
|
|
<P>
|
|
|
|
<BR> char *buf;
|
|
<BR> scanf("%as", &buf);
|
|
<P>
|
|
|
|
The use of the letter
|
|
<B>a</B>
|
|
|
|
for this purpose was problematic, since
|
|
<B>a</B>
|
|
|
|
is also specified by the ISO C standard as a synonym for
|
|
<B>f</B>
|
|
|
|
(floating-point input).
|
|
POSIX.1-2008 instead specifies the
|
|
<B>m</B>
|
|
|
|
modifier for assignment allocation (as documented in DESCRIPTION, above).
|
|
<P>
|
|
|
|
Note that the
|
|
<B>a</B>
|
|
|
|
modifier is not available if the program is compiled with
|
|
<I>gcc -std=c99</I>
|
|
|
|
or
|
|
<I>gcc -D_ISOC99_SOURCE</I>
|
|
|
|
(unless
|
|
<B>_GNU_SOURCE</B>
|
|
|
|
is also specified), in which case the
|
|
<B>a</B>
|
|
|
|
is interpreted as a specifier for floating-point numbers (see above).
|
|
<P>
|
|
|
|
Support for the
|
|
<B>m</B>
|
|
|
|
modifier was added to glibc starting with version 2.7,
|
|
and new programs should use that modifier instead of
|
|
<B>a</B>.
|
|
|
|
<P>
|
|
|
|
As well as being standardized by POSIX, the
|
|
<B>m</B>
|
|
|
|
modifier has the following further advantages over
|
|
the use of
|
|
<B>a:</B>
|
|
|
|
<DL COMPACT>
|
|
<DT id="44">*<DD>
|
|
It may also be applied to
|
|
<B>%c</B>
|
|
|
|
conversion specifiers (e.g.,
|
|
<B>%3mc</B>).
|
|
|
|
<DT id="45">*<DD>
|
|
It avoids ambiguity with respect to the
|
|
<B>%a</B>
|
|
|
|
floating-point conversion specifier (and is unaffected by
|
|
<I>gcc -std=c99</I>
|
|
|
|
etc.).
|
|
</DL>
|
|
<A NAME="lbAL"> </A>
|
|
<H2>BUGS</H2>
|
|
|
|
All functions are fully C89 conformant, but provide the
|
|
additional specifiers
|
|
<B>q</B>
|
|
|
|
and
|
|
<B>a</B>
|
|
|
|
as well as an additional behavior of the
|
|
<B>L</B>
|
|
|
|
and
|
|
<B>l</B>
|
|
|
|
specifiers.
|
|
The latter may be considered to be a bug, as it changes the
|
|
behavior of specifiers defined in C89.
|
|
<P>
|
|
|
|
Some combinations of the type modifiers and conversion
|
|
specifiers defined by ANSI C do not make sense
|
|
(e.g.,
|
|
<B>%Ld</B>).
|
|
|
|
While they may have a well-defined behavior on Linux, this need not
|
|
to be so on other architectures.
|
|
Therefore it usually is better to use
|
|
modifiers that are not defined by ANSI C at all, that is, use
|
|
<B>q</B>
|
|
|
|
instead of
|
|
<B>L</B>
|
|
|
|
in combination with
|
|
<B>d</B>, <B>i</B>, <B>o</B>, <B>u</B>, <B>x</B>, and <B>X</B>
|
|
conversions or
|
|
<B>ll</B>.
|
|
|
|
<P>
|
|
|
|
The usage of
|
|
<B>q</B>
|
|
|
|
is not the same as on 4.4BSD,
|
|
as it may be used in float conversions equivalently to
|
|
<B>L</B>.
|
|
|
|
<A NAME="lbAM"> </A>
|
|
<H2>EXAMPLE</H2>
|
|
|
|
To use the dynamic allocation conversion specifier, specify
|
|
<B>m</B>
|
|
|
|
as a length modifier (thus
|
|
<B>%ms</B>
|
|
|
|
or
|
|
<B>%m[</B><I>range</I><B>]</B>).
|
|
The caller must
|
|
<B><A HREF="/cgi-bin/man/man2html?3+free">free</A></B>(3)
|
|
|
|
the returned string, as in the following example:
|
|
<P>
|
|
|
|
|
|
|
|
char *p;
|
|
int n;
|
|
<P>
|
|
errno = 0;
|
|
n = scanf("%m[a-z]", &p);
|
|
if (n == 1) {
|
|
<BR> printf("read: %s\n", p);
|
|
<BR> free(p);
|
|
} else if (errno != 0) {
|
|
<BR> perror("scanf");
|
|
} else {
|
|
<BR> fprintf(stderr, "No matching characters\n");
|
|
}
|
|
|
|
|
|
<P>
|
|
|
|
As shown in the above example, it is necessary to call
|
|
<B><A HREF="/cgi-bin/man/man2html?3+free">free</A></B>(3)
|
|
|
|
only if the
|
|
<B>scanf</B>()
|
|
|
|
call successfully read a string.
|
|
<A NAME="lbAN"> </A>
|
|
<H2>SEE ALSO</H2>
|
|
|
|
<B><A HREF="/cgi-bin/man/man2html?3+getc">getc</A></B>(3),
|
|
|
|
<B><A HREF="/cgi-bin/man/man2html?3+printf">printf</A></B>(3),
|
|
|
|
<B><A HREF="/cgi-bin/man/man2html?3+setlocale">setlocale</A></B>(3),
|
|
|
|
<B><A HREF="/cgi-bin/man/man2html?3+strtod">strtod</A></B>(3),
|
|
|
|
<B><A HREF="/cgi-bin/man/man2html?3+strtol">strtol</A></B>(3),
|
|
|
|
<B><A HREF="/cgi-bin/man/man2html?3+strtoul">strtoul</A></B>(3)
|
|
|
|
<A NAME="lbAO"> </A>
|
|
<H2>COLOPHON</H2>
|
|
|
|
This page is part of release 5.05 of the Linux
|
|
<I>man-pages</I>
|
|
|
|
project.
|
|
A description of the project,
|
|
information about reporting bugs,
|
|
and the latest version of this page,
|
|
can be found at
|
|
<A HREF="https://www.kernel.org/doc/man-pages/.">https://www.kernel.org/doc/man-pages/.</A>
|
|
<P>
|
|
|
|
<HR>
|
|
<A NAME="index"> </A><H2>Index</H2>
|
|
<DL>
|
|
<DT id="46"><A HREF="#lbAB">NAME</A><DD>
|
|
<DT id="47"><A HREF="#lbAC">SYNOPSIS</A><DD>
|
|
<DT id="48"><A HREF="#lbAD">DESCRIPTION</A><DD>
|
|
<DL>
|
|
<DT id="49"><A HREF="#lbAE">Conversions</A><DD>
|
|
</DL>
|
|
<DT id="50"><A HREF="#lbAF">RETURN VALUE</A><DD>
|
|
<DT id="51"><A HREF="#lbAG">ERRORS</A><DD>
|
|
<DT id="52"><A HREF="#lbAH">ATTRIBUTES</A><DD>
|
|
<DT id="53"><A HREF="#lbAI">CONFORMING TO</A><DD>
|
|
<DT id="54"><A HREF="#lbAJ">NOTES</A><DD>
|
|
<DL>
|
|
<DT id="55"><A HREF="#lbAK">The 'a' assignment-allocation modifier</A><DD>
|
|
</DL>
|
|
<DT id="56"><A HREF="#lbAL">BUGS</A><DD>
|
|
<DT id="57"><A HREF="#lbAM">EXAMPLE</A><DD>
|
|
<DT id="58"><A HREF="#lbAN">SEE ALSO</A><DD>
|
|
<DT id="59"><A HREF="#lbAO">COLOPHON</A><DD>
|
|
</DL>
|
|
<HR>
|
|
This document was created by
|
|
<A HREF="/cgi-bin/man/man2html">man2html</A>,
|
|
using the manual pages.<BR>
|
|
Time: 00:05:54 GMT, March 31, 2021
|
|
</BODY>
|
|
</HTML>
|