summaryrefslogtreecommitdiffstats
path: root/man3/sscanf.3
diff options
context:
space:
mode:
Diffstat (limited to '')
-rw-r--r--man3/sscanf.370
1 files changed, 29 insertions, 41 deletions
diff --git a/man3/sscanf.3 b/man3/sscanf.3
index 223f4f5..7e0198c 100644
--- a/man3/sscanf.3
+++ b/man3/sscanf.3
@@ -22,7 +22,7 @@
.\" Add ERRORS section.
.\" Document the 'a' and 'm' modifiers for dynamic string allocation.
.\"
-.TH sscanf 3 2023-07-20 "Linux man-pages 6.05.01"
+.TH sscanf 3 2023-12-09 "Linux man-pages 6.7"
.SH NAME
sscanf, vsscanf \- input string format conversion
.SH LIBRARY
@@ -31,21 +31,21 @@ Standard C library
.SH SYNOPSIS
.nf
.B #include <stdio.h>
-.PP
+.P
.BI "int sscanf(const char *restrict " str ,
.BI " const char *restrict " format ", ...);"
-.PP
+.P
.B #include <stdarg.h>
-.PP
+.P
.BI "int vsscanf(const char *restrict " str ,
.BI " const char *restrict " format ", va_list " ap );
.fi
-.PP
+.P
.RS -4
Feature Test Macro Requirements for glibc (see
.BR feature_test_macros (7)):
.RE
-.PP
+.P
.BR vsscanf ():
.nf
_ISOC99_SOURCE || _POSIX_C_SOURCE >= 200112L
@@ -53,7 +53,7 @@ Feature Test Macro Requirements for glibc (see
.SH DESCRIPTION
The
.BR sscanf ()
-family of functions scans input according to
+family of functions scans formatted input according to
.I format
as described below.
This format may contain
@@ -67,7 +67,7 @@ Each
.I pointer
argument must be of a type that is appropriate for the value returned
by the corresponding conversion specification.
-.PP
+.P
If the number of conversion specifications in
.I format
exceeds the number of
@@ -78,17 +78,17 @@ If the number of
arguments exceeds the number of conversion specifications, then the excess
.I pointer
arguments are evaluated, but are otherwise ignored.
-.PP
+.P
.BR sscanf ()
These functions
read their input from the string pointed to by
.IR str .
-.PP
+.P
The
.BR vsscanf ()
function is analogous to
.BR vsprintf (3).
-.PP
+.P
The
.I format
string consists of a sequence of
@@ -102,7 +102,7 @@ A "failure" can be either of the following:
meaning that input characters were unavailable, or
.IR "matching failure" ,
meaning that the input was inappropriate (see below).
-.PP
+.P
A directive is one of the following:
.TP
\[bu]
@@ -125,7 +125,7 @@ argument.
If the next item of input does not match the conversion specification,
the conversion fails\[em]this is a
.IR "matching failure" .
-.PP
+.P
Each
.I conversion specification
in
@@ -205,7 +205,7 @@ rather than a pointer to an
A
.I "conversion specifier"
that specifies the type of input conversion to be performed.
-.PP
+.P
The conversion specifications in
.I format
are of two forms, either beginning with \[aq]%\[aq] or beginning with
@@ -344,7 +344,7 @@ As for
but the next pointer is a pointer to a
.IR size_t .
This modifier was introduced in C99.
-.PP
+.P
The following
.I "conversion specifiers"
are available:
@@ -359,7 +359,6 @@ No conversion is done (but initial white space characters are discarded),
and assignment does not occur.
.TP
.B d
-.IR Deprecated .
Matches an optionally signed decimal integer;
the next pointer must be a pointer to
.IR int .
@@ -374,7 +373,6 @@ the next pointer must be a pointer to
.\" is silently ignored, causing old programs to fail mysteriously.)
.TP
.B i
-.IR Deprecated .
Matches an optionally signed integer; the next pointer must be a pointer to
.IR int .
The integer is read in base 16 if it begins with
@@ -387,18 +385,15 @@ and in base 10 otherwise.
Only characters that correspond to the base are used.
.TP
.B o
-.IR Deprecated .
Matches an unsigned octal integer; the next pointer must be a pointer to
.IR "unsigned int" .
.TP
.B u
-.IR Deprecated .
Matches an unsigned decimal integer; the next pointer must be a
pointer to
.IR "unsigned int" .
.TP
.B x
-.IR Deprecated .
Matches an unsigned hexadecimal integer
(that may optionally begin with a prefix of
.I 0x
@@ -409,33 +404,27 @@ be a pointer to
.IR "unsigned int" .
.TP
.B X
-.IR Deprecated .
Equivalent to
.BR x .
.TP
.B f
-.IR Deprecated .
Matches an optionally signed floating-point number; the next pointer must
be a pointer to
.IR float .
.TP
.B e
-.IR Deprecated .
Equivalent to
.BR f .
.TP
.B g
-.IR Deprecated .
Equivalent to
.BR f .
.TP
.B E
-.IR Deprecated .
Equivalent to
.BR f .
.TP
.B a
-.IR Deprecated .
(C99) Equivalent to
.BR f .
.TP
@@ -522,7 +511,7 @@ 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
+.P
The value
.B EOF
is returned if the end of input is reached before either the first
@@ -554,12 +543,11 @@ T{
.BR vsscanf ()
T} Thread safety MT-Safe locale
.TE
-.sp 1
.SH STANDARDS
C11, POSIX.1-2008.
.SH HISTORY
C89, POSIX.1-2001.
-.PP
+.P
The
.B q
specifier is the 4.4BSD notation for
@@ -569,7 +557,7 @@ while
or the usage of
.B L
in integer conversions is the GNU notation.
-.PP
+.P
The Linux version of these functions is based on the
.I GNU
.I libio
@@ -592,14 +580,14 @@ Thus, one could write the following to have
allocate a buffer for a string,
with a pointer to that buffer being returned in
.IR *buf :
-.PP
+.P
.in +4n
.EX
char *buf;
sscanf(str, "%as", &buf);
.EE
.in
-.PP
+.P
The use of the letter
.B a
for this purpose was problematic, since
@@ -610,7 +598,7 @@ is also specified by the ISO C standard as a synonym for
POSIX.1-2008 instead specifies the
.B m
modifier for assignment allocation (as documented in DESCRIPTION, above).
-.PP
+.P
Note that the
.B a
modifier is not available if the program is compiled with
@@ -622,13 +610,13 @@ or
is also specified), in which case the
.B a
is interpreted as a specifier for floating-point numbers (see above).
-.PP
+.P
Support for the
.B m
modifier was added to glibc 2.7,
and new programs should use that modifier instead of
.BR a .
-.PP
+.P
As well as being standardized by POSIX, the
.B m
modifier has the following further advantages over
@@ -662,8 +650,8 @@ Instead,
programs should use functions such as
.BR strtol (3)
to parse numeric input.
-This manual page deprecates use of the numeric conversion specifiers
-until they are fixed by ISO C.
+Alternatively,
+mitigate it by specifying a maximum field width.
.SS Nonstandard modifiers
These functions are fully C99 conformant, but provide the
additional modifiers
@@ -677,7 +665,7 @@ and
modifiers.
The latter may be considered to be a bug, as it changes the
behavior of modifiers defined in C99.
-.PP
+.P
Some combinations of the type modifiers and conversion
specifiers defined by C99 do not make sense
(e.g.,
@@ -693,7 +681,7 @@ in combination with
\fBd\fP, \fBi\fP, \fBo\fP, \fBu\fP, \fBx\fP, and \fBX\fP
conversions or
.BR ll .
-.PP
+.P
The usage of
.B q
is not the same as on 4.4BSD,
@@ -709,7 +697,7 @@ or
The caller must
.BR free (3)
the returned string, as in the following example:
-.PP
+.P
.in +4n
.EX
char *p;
@@ -727,7 +715,7 @@ if (n == 1) {
}
.EE
.in
-.PP
+.P
As shown in the above example, it is necessary to call
.BR free (3)
only if the