.\" Add ERRORS section.
.\" Document the 'a' and 'm' modifiers for dynamic string allocation.
.\"
-.TH SCANF 3 2013-01-30 "GNU" "Linux Programmer's Manual"
+.TH SCANF 3 2020-04-11 "GNU" "Linux Programmer's Manual"
.SH NAME
scanf, fscanf, sscanf, vscanf, vsscanf, vfscanf \- input format conversion
.SH SYNOPSIS
.nf
.B #include <stdio.h>
-
+.PP
.BI "int scanf(const char *" format ", ...);"
.BI "int fscanf(FILE *" stream ", const char *" format ", ...);"
.BI "int sscanf(const char *" str ", const char *" format ", ...);"
-.sp
-.B #include <stdarg.h>
+.B #include <stdarg.h>
+.PP
.BI "int vscanf(const char *" format ", va_list " ap );
.BI "int vsscanf(const char *" str ", const char *" format ", va_list " ap );
.BI "int vfscanf(FILE *" stream ", const char *" format ", va_list " ap );
.fi
-.sp
+.PP
.in -4n
Feature Test Macro Requirements for glibc (see
.BR feature_test_macros (7)):
.in
.ad l
-.sp
+.PP
.BR vscanf (),
.BR vsscanf (),
.BR vfscanf ():
.RS 4
-_XOPEN_SOURCE\ >=\ 600 || _ISOC99_SOURCE ||
-_POSIX_C_SOURCE\ >=\ 200112L;
-.br
-or
-.I "cc -std=c99"
+_ISOC99_SOURCE || _POSIX_C_SOURCE\ >=\ 200112L
.ad
.RE
.SH DESCRIPTION
.I pointer
argument must be of a type that is appropriate for the value returned
by the corresponding conversion specification.
-
+.PP
If the number of conversion specifications in
.I format
exceeds the number of
arguments exceeds the number of conversion specifications, then the excess
.I pointer
arguments are evaluated, but are otherwise ignored.
-
+.PP
The
.BR scanf ()
function reads input from the standard input stream
meaning that input characters were unavailable, or
.IR "matching failure" ,
meaning that the input was inappropriate (see below).
-
+.PP
A directive is one of the following:
.TP
\(bu
.BR scanf ().
.TP
\(bu
+For decimal conversions, an optional quote character (\(aq).
+This specifies that the input number may include thousands'
+separators as defined by the
+.BR LC_NUMERIC
+category of the current locale.
+(See
+.BR setlocale (3).)
+The quote character may precede or follow the \(aq*\(aq
+assignment-suppression character.
+.TP
+\(bu
An optional \(aqm\(aq character.
This is used with string conversions
.RI ( %s ,
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)
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 (\(aq\\0\(aq)
+String input conversions store a terminating null byte (\(aq\e0\(aq)
to mark the end of the input;
the maximum field width does not include this terminator.
.TP
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.
Matches an optionally signed decimal integer;
the next pointer must be a pointer to
.IR int .
-.TP
-.B D
-Equivalent to
-.IR ld ;
-this exists only for backward compatibility.
-(Note: thus only in libc4.
-In libc5 and glibc the
-.B %D
-is silently ignored, causing old programs to fail mysteriously.)
+.\" .TP
+.\" .B D
+.\" Equivalent to
+.\" .IR ld ;
+.\" this exists only for backward compatibility.
+.\" (Note: thus only in libc4
+.\" In libc5 and glibc the
+.\" .B %D
+.\" is silently ignored, causing old programs to fail mysteriously.)
.TP
.B i
Matches an optionally signed integer; the next pointer must be a pointer to
.IR "unsigned int" .
.TP
.B x
-Matches an unsigned hexadecimal integer; the next pointer must
+Matches an unsigned hexadecimal integer
+(that may optionally begin with a prefix of
+.I 0x
+or
+.IR 0X ,
+which is discarded); the next pointer must
be a pointer to
.IR "unsigned int" .
.TP
.TP
.B s
Matches a sequence of non-white-space characters;
-the next pointer must be a pointer to character array that is
-long enough to hold the input sequence and
-the terminating null byte (\(aq\\0\(aq), which is added automatically.
+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 (\(aq\e0\(aq), which is added automatically.
The input string stops at white space or at the maximum field
width, whichever occurs first.
.TP
.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
Matches a pointer value (as printed by
.B %p
in
-.BR printf (3);
+.BR printf (3));
the next pointer must be a pointer to a pointer to
.IR void .
.TP
.IR int .
This is
.I not
-a conversion, although it can be suppressed with the
+a conversion and does
+.I not
+increase the count returned by the function.
+The assignment can be suppressed with the
.B *
-assignment-suppression character.
-The C standard says: "Execution of a
-.B %n
-directive does not increment
-the assignment count returned at the completion of execution"
-but the Corrigendum seems to contradict this.
-Probably it is wise
-not to make any assumptions on the effect of
-.B %n
-conversions on the return value.
+assignment-suppression character, but the effect on the
+return value is undefined.
+Therefore
+.B %*n
+conversions should not be used.
.SH RETURN VALUE
-These functions return the number of input items
-successfully matched and assigned,
-which can be fewer than provided for,
-or even zero in the event of an early matching failure.
-
+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.
+.PP
The value
.B EOF
is returned if the end of input is reached before either the first
.BR ferror (3))
is set, and
.I errno
-is set indicate the error.
+is set to indicate the error.
.SH ERRORS
.TP
.B EAGAIN
.B ERANGE
The result of an integer conversion would exceed the size
that can be stored in the corresponding integer type.
+.SH ATTRIBUTES
+For an explanation of the terms used in this section, see
+.BR attributes (7).
+.TS
+allbox;
+lbw20 lb lb
+l l l.
+Interface Attribute Value
+T{
+.BR scanf (),
+.BR fscanf (),
+.br
+.BR sscanf (),
+.BR vscanf (),
+.br
+.BR vsscanf (),
+.BR vfscanf ()
+T} Thread safety MT-Safe locale
+.TE
+.sp 1
.SH CONFORMING TO
The functions
.BR fscanf (),
.I libc (glibc-1.08)
for a more concise description.
.SH NOTES
-The GNU C library supported the dynamic allocation conversion specifier
+.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
-character. This feature
-seems to be present at least as far back as glibc 2.0.
+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 :
+.PP
+ char *buf;
+ scanf("%as", &buf);
+.PP
+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
-It is not available if the program is compiled with
-.I "gcc -std=c99"
+Note that the
+.B a
+modifier is not available if the program is compiled with
+.I "gcc \-std=c99"
or
-.IR "gcc -D_ISOC99_SOURCE"
+.IR "gcc \-D_ISOC99_SOURCE"
(unless
.B _GNU_SOURCE
is also specified), in which case the
.B a
is interpreted as a specifier for floating-point numbers (see above).
-
-Since version 2.7, glibc also provides the
+.PP
+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 .
+.PP
+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
It avoids ambiguity with respect to the
.B %a
floating-point conversion specifier (and is unaffected by
-.IR "gcc -std=c99"
-etc.)
-.IP *
-It is specified in the POSIX.1-2008 standard.
+.IR "gcc \-std=c99"
+etc.).
.SH BUGS
All functions are fully C89 conformant, but provide the
additional specifiers
is not the same as on 4.4BSD,
as it may be used in float conversions equivalently to
.BR L .
-.SH EXAMPLE
+.SH EXAMPLES
To use the dynamic allocation conversion specifier, specify
.B m
as a length modifier (thus
The caller must
.BR free (3)
the returned string, as in the following example:
+.PP
.in +4n
-.nf
-
+.EX
char *p;
int n;
errno = 0;
-n = scanf("%m[a-z]", &p);
+n = scanf("%m[a\-z]", &p);
if (n == 1) {
- printf("read: %s\\n", p);
+ printf("read: %s\en", p);
free(p);
} else if (errno != 0) {
perror("scanf");
} else {
- fprintf(stderr, "No matching characters\\n");
+ fprintf(stderr, "No matching characters\en");
}
-.fi
+.EE
.in
.PP
-As shown in the above example, it is only necessary to call
+As shown in the above example, it is necessary to call
.BR free (3)
-if the
+only if the
.BR scanf ()
call successfully read a string.
.SH SEE ALSO
projects / thirdparty / man-pages.git / blobdiff