.\" Chris Torek and the American National Standards Committee X3,
.\" on Information Processing Systems.
.\"
+.\" %%%LICENSE_START(BSD_4_CLAUSE_UCB)
.\" Redistribution and use in source and binary forms, with or without
.\" modification, are permitted provided that the following conditions
.\" are met:
.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
.\" SUCH DAMAGE.
+.\" %%%LICENSE_END
.\"
.\" @(#)scanf.3 6.14 (Berkeley) 1/8/93
.\"
.\" Add ERRORS section.
.\" Document the 'a' and 'm' modifiers for dynamic string allocation.
.\"
-.TH SCANF 3 2011-09-28 "GNU" "Linux Programmer's Manual"
+.TH SCANF 3 2014-01-11 "GNU" "Linux Programmer's Manual"
.SH NAME
scanf, fscanf, sscanf, vscanf, vsscanf, vfscanf \- input format conversion
.SH SYNOPSIS
.BR scanf ().
.TP
\(bu
-An optional \(aqa\(aq character.
-This is used with string conversions, and relieves the caller of the
+An optional \(aqm\(aq character.
+This is used with string conversions
+.RI ( %s ,
+.IR %c ,
+.IR %[ ),
+and relieves the caller of the
need to allocate a corresponding buffer to hold the input: instead,
.BR scanf ()
allocates a buffer of sufficient size,
and assigns the address of this buffer to the corresponding
.I pointer
argument, which should be a pointer to a
-.I "char *"
+.I "char\ *"
variable (this variable does not need to be initialized before the call).
The caller should subsequently
.BR free (3)
this buffer when it is no longer required.
-This is a GNU extension;
-C99 employs the \(aqa\(aq character as a conversion specifier (and
-it can also be used as such in the GNU implementation).
.TP
\(bu
An optional decimal integer which specifies the
If
.I format
contains \(aq%\(aq
-specifications then these correspond in order with successive
+specifications, then these correspond in order with successive
.I pointer
arguments.
In the
If used with
.B %c
or
-.B %s
+.BR %s ,
the corresponding parameter is considered
as a pointer to a wide character or wide-character string respectively.
.\" This use of l was introduced in Amendment 1 to ISO C90.
.I maximum field width
(default 1); the next pointer must be a pointer to
.IR char ,
-and there must be enough room for all the characters (no terminating
-null byte
-is added).
+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.
.TP
not to make any assumptions on the effect of
.B %n
conversions on the return value.
-.SH "RETURN VALUE"
+.SH RETURN VALUE
These functions return the number of input items
successfully matched and assigned,
which can be fewer than provided for,
.B ERANGE
The result of an integer conversion would exceed the size
that can be stored in the corresponding integer type.
-.SH "CONFORMING TO"
+.SH CONFORMING TO
The functions
.BR fscanf (),
.BR scanf (),
.I libc (glibc-1.08)
for a more concise description.
.SH NOTES
-The GNU C library supports a nonstandard extension that causes
-the library to dynamically allocate a string of sufficient size
-for input strings for the
-.B %s
-and
-\fB%a[\fP\fIrange\fP\fB]\fP
-conversion specifiers.
-.\" This feature seems to be present at least as far back as glibc 2.0.
-To make use of this feature, specify
+.SS The 'a' assignment-allocation modifier
+Originally, the GNU C library supported dynamic allocation for string inputs
+(as a nonstandard extension) via the
.B a
-as a length modifier (thus
-.B %as
-or
-\fB%a[\fP\fIrange\fP\fB]\fP).
-The caller must
-.BR free (3)
-the returned string, as in the following example:
-.in +4n
-.nf
-
-char *p;
-int n;
+character.
+(This feature is present at least as far back as glibc 2.0.)
+Thus, one could write the following to have
+.BR scanf ()
+allocate a buffer for an input string,
+with a pointer to that buffer being returned in
+.IR *buf :
-errno = 0;
-n = scanf("%a[a-z]", &p);
-if (n == 1) {
- printf("read: %s\\n", p);
- free(p);
-} else if (errno != 0) {
- perror("scanf");
-} else {
- fprintf(stderr, "No matching characters\\n");
-}
-.fi
-.in
+ char *buf;
+ scanf("%as", &buf);
.PP
-As shown in the above example, it is only necessary to call
-.BR free (3)
-if the
-.BR scanf ()
-call successfully read a string.
+The use of the letter
+.B a
+for this purpose was problematic, since
+.B a
+is also specified by the ISO C standard as a synonym for
+.B f
+(floating-point input).
+POSIX.1-2008 instead specifies the
+.B m
+modifier for assignment allocation (as documented in DESCRIPTION, above).
.PP
-The
+Note that the
.B a
modifier is not available if the program is compiled with
.I "gcc -std=c99"
.B a
is interpreted as a specifier for floating-point numbers (see above).
-Since version 2.7, glibc also provides the
+Support for the
.B m
-modifier for the same purpose as the
-.BR a
-modifier.
-The
+modifier was added to glibc starting with version 2.7,
+and new programs should use that modifier instead of
+.BR a .
+
+As well as being standardized by POSIX, the
.B m
-modifier has the following advantages:
+modifier has the following further advantages over
+the use of
+.BR a:
.IP * 2
It may also be applied to
.B %c
.B %a
floating-point conversion specifier (and is unaffected by
.IR "gcc -std=c99"
-etc.)
-.IP *
-It is specified in the upcoming revision of the POSIX.1 standard.
+etc.).
.SH BUGS
All functions are fully C89 conformant, but provide the
additional specifiers
.PP
Some combinations of the type modifiers and conversion
specifiers defined by ANSI C do not make sense
-(e.g.
+(e.g.,
.BR "%Ld" ).
While they may have a well-defined behavior on Linux, this need not
to be so on other architectures.
is not the same as on 4.4BSD,
as it may be used in float conversions equivalently to
.BR L .
-.SH "SEE ALSO"
+.SH EXAMPLE
+To use the dynamic allocation conversion specifier, specify
+.B m
+as a length modifier (thus
+.B %ms
+or
+\fB%m[\fP\fIrange\fP\fB]\fP).
+The caller must
+.BR free (3)
+the returned string, as in the following example:
+.in +4n
+.nf
+
+char *p;
+int n;
+
+errno = 0;
+n = scanf("%m[a-z]", &p);
+if (n == 1) {
+ printf("read: %s\\n", p);
+ free(p);
+} else if (errno != 0) {
+ perror("scanf");
+} else {
+ fprintf(stderr, "No matching characters\\n");
+}
+.fi
+.in
+.PP
+As shown in the above example, it is necessary to call
+.BR free (3)
+only if the
+.BR scanf ()
+call successfully read a string.
+.SH SEE ALSO
.BR getc (3),
.BR printf (3),
.BR setlocale (3),
.BR strtod (3),
.BR strtol (3),
.BR strtoul (3)
+.SH COLOPHON
+This page is part of release 3.79 of the Linux
+.I man-pages
+project.
+A description of the project,
+information about reporting bugs,
+and the latest version of this page,
+can be found at
+\%http://www.kernel.org/doc/man\-pages/.
OSDN Git Service
