diff mbox series

manual: Document the standardized scanf flag, "m". [BZ #16376]

Message ID 7c42f58d-d076-aeb3-a229-2581aa03af94@pacific.net
State New
Headers show
Series manual: Document the standardized scanf flag, "m". [BZ #16376] | expand

Commit Message

Rical Jasan Feb. 7, 2018, 5:56 a.m. UTC 
Looking in stdio-common/vfscanf.c, "a" uses GNU_MALLOC, and "m" uses
POSIX_MALLOC, and there is a MALLOC which is defined to either, and
throughout the code there are several conditionals where POSIX_MALLOC is
nested beneath MALLOC (GNU_MALLOC is always MALLOC), but I'm not sure we
want to document any internal implementation differences (if they're
even significant).  The existing documentation wasn't very detailed
itself, but I still wanted to mention it.

I confirmed "m" was introduced in POSIX.1-2008 (mentioned in the Issue 7
section of CHANGE HISTORY on the s/f/scanf page).

The NEWS file says entries for bugs will be generated automatically, and
once ACK'd, I'll refactor the paragraphs before committing (tried to
make it easier to see what changed here) and provide a ChangeLog entry.

Rical

Comments

Andreas Schwab Feb. 7, 2018, 8:46 a.m. UTC | #1 
On Feb 06 2018, Rical Jasan <ricaljasan@pacific.net> wrote:

> Looking in stdio-common/vfscanf.c, "a" uses GNU_MALLOC, and "m" uses
> POSIX_MALLOC, and there is a MALLOC which is defined to either, and
> throughout the code there are several conditionals where POSIX_MALLOC is
> nested beneath MALLOC (GNU_MALLOC is always MALLOC), but I'm not sure we
> want to document any internal implementation differences (if they're
> even significant).  The existing documentation wasn't very detailed
> itself, but I still wanted to mention it.

IMHO the "a" modifier should be marked as deprecated, since it conflicts
with the %a format.  I think it would be enough to mention it in a
paragraph, but nowhere else.

Andreas.
Paul Eggert Feb. 8, 2018, 6:42 p.m. UTC | #2 
On 02/07/2018 12:46 AM, Andreas Schwab wrote:
> IMHO the "a" modifier should be marked as deprecated, since it conflicts
> with the %a format.  I think it would be enough to mention it in a
> paragraph, but nowhere else.

Agreed. Also, I suggest modifying the NEWS entry for glibc 1.06 that 
talks about the newly-introduced "a" modifier, so that it briefly 
mentions that the modifier is deprecated after glibc 2.28.
Rical Jasan Feb. 16, 2018, 6:54 a.m. UTC | #3 
On 02/08/2018 10:42 AM, Paul Eggert wrote:
> On 02/07/2018 12:46 AM, Andreas Schwab wrote:
>> IMHO the "a" modifier should be marked as deprecated, since it conflicts
>> with the %a format.  I think it would be enough to mention it in a
>> paragraph, but nowhere else.
> 
> Agreed. Also, I suggest modifying the NEWS entry for glibc 1.06 that
> talks about the newly-introduced "a" modifier, so that it briefly
> mentions that the modifier is deprecated after glibc 2.28.

I've submitted a v3 that doesn't update NEWS yet because Zack started
addressing actual deprecation of the "a" modifier, but it isn't entirely
clear yet (at least to me) what that will look like when it's done.  I
think it may be more appropriate to update the deprecation section of
NEWS for 2.28 when/if that goes in, though I could put a stub in to the
effect of, "The GNU extension scanf modifier "a" has been [documented
as] deprecated."  I'm not sure if it's appropriate to say it /has been/
deprecated just because of the manual, though perhaps that is enough;
putting a NEWS entry there is essentially the formal announcement, I
suppose.  I don't think retroactively editing the 1.06 announcement is
the way to go (I would rather just announce it in 2.28), but if others
agree that's fine/desirable, I can change my mind about that.  :)

Thanks,
Rical
diff mbox series

Patch

From cc32f967605178358d7b0d3e6fc1d36d036e6a8f Mon Sep 17 00:00:00 2001
From: Rical Jasan <ricaljasan@pacific.net>
Date: Tue, 6 Feb 2018 21:22:27 -0800
Subject: [PATCH] manual: Document the standardized scanf flag, "m".  [BZ
 #16376]

POSIX.1-2008 introduced the optional assignment-allocation modifier,
"m", whose functionality was previously provided by the GNU extension
"a" (and still is).

	[BZ #16376]
	* manual/stdio.texi (Input Conversion Syntax)
	(String Input Conversions, Dynamic String Input): Document the
	"m" flag.
---
 manual/stdio.texi | 34 +++++++++++++++++++++-------------
 1 file changed, 21 insertions(+), 13 deletions(-)

diff --git a/manual/stdio.texi b/manual/stdio.texi
index 5d7b50c442..4db65f4e18 100644
--- a/manual/stdio.texi
+++ b/manual/stdio.texi
@@ -3440,10 +3440,9 @@  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}.
+(There is also a GNU extension, @samp{a}.)  @xref{Dynamic String Input}.
 
 @item
 An optional decimal integer that specifies the @dfn{maximum field
@@ -3720,8 +3719,9 @@  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
+Ask @code{scanf} to allocate a big-enough buffer, by specifying the
+@samp{m} flag character (or the GNU extension, @samp{a}).
+You should provide
 an argument of type @code{char **} for the buffer address to be stored
 in.  @xref{Dynamic String Input}.
 @end itemize
@@ -3825,7 +3825,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} or @samp{a} flags, 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 +3833,26 @@  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.
+
+As a GNU extension, @samp{a} is available in place of @samp{m}.
 
-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 +3860,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 ();
-- 
2.14.3