From 9a6ff5bc53dedbaa601a1a76cbaf8a76afd60c9f Mon Sep 17 00:00:00 2001 From: Daniel Baumann Date: Mon, 15 Apr 2024 21:41:06 +0200 Subject: Adding upstream version 6.7. Signed-off-by: Daniel Baumann --- man3/sscanf.3 | 70 +++++++++++++++++++++++++---------------------------------- 1 file changed, 29 insertions(+), 41 deletions(-) (limited to 'man3/sscanf.3') 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 -.PP +.P .BI "int sscanf(const char *restrict " str , .BI " const char *restrict " format ", ...);" -.PP +.P .B #include -.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 -- cgit v1.2.3