This commit documents the optional assignment-allocation modifier,
"m", introduced in POSIX.1-2008, whose functionality was previously
provided by the GNU extension "a". Use of the GNU extension is
discouraged due to ambiguity when operating in any conformance mode
equivalent to C99/POSIX.1-2001, which introduced the "a", "A", and "F"
conversion specifiers. (Consider a format string containing "%as".)
The additional conversion specifiers are also documented.
[BZ #16376]
* manual/stdio.texi (Input Conversion Syntax)
(String Input Conversions, Dynamic String Input): Document the
"m" flag.
(Table of Input Conversions, Numeric Input Conversions):
Document the "a", "A", and "F" conversion specifiers.
---
Changes in v3:
* Discourage use of the "a" GNU extension.
* Document the "a", "A", and "F" conversion specifiers.
---
manual/stdio.texi | 41 +++++++++++++++++++++++++----------------
1 file changed, 25 insertions(+), 16 deletions(-)
@@ -3440,9 +3440,8 @@ successful assignments.
@cindex flag character (@code{scanf})
@item
-An optional flag character @samp{a} (valid with string conversions only)
+An optional flag character @samp{m} (valid with string conversions only)
which requests allocation of a buffer long enough to store the string in.
-(This is a GNU extension.)
@xref{Dynamic String Input}.
@item
@@ -3508,7 +3507,7 @@ Matches an unsigned integer written in decimal radix.
Matches an unsigned integer written in hexadecimal radix.
@xref{Numeric Input Conversions}.
-@item @samp{%e}, @samp{%f}, @samp{%g}, @samp{%E}, @samp{%G}
+@item @samp{%a}, @samp{%e}, @samp{%f}, @samp{%g}, @samp{%A}, @samp{%E}, @samp{%F}, @samp{%G}
Matches an optionally signed floating-point number. @xref{Numeric Input
Conversions}.
@@ -3664,7 +3663,8 @@ Specifies that the argument is a @code{size_t *}.
This modifier was introduced in @w{ISO C99}.
@end table
-All of the @samp{%e}, @samp{%f}, @samp{%g}, @samp{%E}, and @samp{%G}
+All of the @samp{%a}, @samp{%e}, @samp{%f}, @samp{%g}, @samp{%A},
+@samp{%E}, @samp{%F}, and @samp{%G}
input conversions are interchangeable. They all match an optionally
signed floating point number, in the same syntax as for the
@code{strtod} function (@pxref{Parsing of Floats}).
@@ -3720,10 +3720,8 @@ provide the buffer, always specify a maximum field width to prevent
overflow.}
@item
-Ask @code{scanf} to allocate a big enough buffer, by specifying the
-@samp{a} flag character. This is a GNU extension. You should provide
-an argument of type @code{char **} for the buffer address to be stored
-in. @xref{Dynamic String Input}.
+Ask @code{scanf} to allocate a large-enough buffer, by specifying the
+@samp{m} flag character. @xref{Dynamic String Input}.
@end itemize
The @samp{%c} conversion is the simplest: it matches a fixed number of
@@ -3825,7 +3823,7 @@ is said about @samp{%ls} above is true for @samp{%l[}.
One more reminder: the @samp{%s} and @samp{%[} conversions are
@strong{dangerous} if you don't specify a maximum width or use the
-@samp{a} flag, because input too long would overflow whatever buffer you
+@samp{m} flag, because too-long input would overflow whatever buffer you
have provided for it. No matter how long your buffer is, a user could
supply input that is longer. A well-written program reports invalid
input with a comprehensible error message, not with a crash.
@@ -3833,18 +3831,29 @@ input with a comprehensible error message, not with a crash.
@node Dynamic String Input
@subsection Dynamically Allocating String Conversions
-A GNU extension to formatted input lets you safely read a string with no
+POSIX.1-2008 specifies an @dfn{assignment-allocation character}
+@samp{m}, valid for use with the string conversion specifiers
+@samp{s}, @samp{S}, @samp{[}, @samp{c}, and @samp{C}, which
+lets you safely read a string with no
maximum size. Using this feature, you don't supply a buffer; instead,
@code{scanf} allocates a buffer big enough to hold the data and gives
-you its address. To use this feature, write @samp{a} as a flag
-character, as in @samp{%as} or @samp{%a[0-9a-z]}.
+you its address. To use this feature, write @samp{m} as a flag
+character; e.g., @samp{%ms} or @samp{%m[0-9a-z]}.
The pointer argument you supply for where to store the input should have
type @code{char **}. The @code{scanf} function allocates a buffer and
-stores its address in the word that the argument points to. You should
-free the buffer with @code{free} when you no longer need it.
+stores its address in the word that the argument points to. When
+using the @samp{l} modifier (or equivalently, @samp{S} or @samp{C}),
+the pointer argument should have the type @code{wchar_t **}.
+
+You should free the buffer with @code{free} when you no longer need it.
+
+@strong{Warning:} There was a GNU extension, @samp{a}, that predated
+@samp{m}, but its use conflicts with the @samp{a} conversion specifier
+introduced in C99 (and adopted in POSIX.1-2001), so its use is highly
+discouraged.
-Here is an example of using the @samp{a} flag with the @samp{%[@dots{}]}
+Here is an example of using the @samp{m} flag with the @samp{%[@dots{}]}
conversion specification to read a ``variable assignment'' of the form
@samp{@var{variable} = @var{value}}.
@@ -3852,7 +3861,7 @@ conversion specification to read a ``variable assignment'' of the form
@{
char *variable, *value;
- if (2 > scanf ("%a[a-zA-Z0-9] = %a[^\n]\n",
+ if (2 > scanf ("%m[a-zA-Z0-9] = %m[^\n]\n",
&variable, &value))
@{
invalid_input_error ();