From patchwork Fri Feb 9 13:07:54 2018 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Rical Jasan X-Patchwork-Id: 871388 Return-Path: X-Original-To: incoming@patchwork.ozlabs.org Delivered-To: patchwork-incoming@bilbo.ozlabs.org Authentication-Results: ozlabs.org; spf=pass (mailfrom) smtp.mailfrom=sourceware.org (client-ip=209.132.180.131; helo=sourceware.org; envelope-from=libc-alpha-return-90179-incoming=patchwork.ozlabs.org@sourceware.org; receiver=) Authentication-Results: ozlabs.org; dkim=pass (1024-bit key; secure) header.d=sourceware.org header.i=@sourceware.org header.b="gRuqzYr+"; dkim-atps=neutral Received: from sourceware.org (server1.sourceware.org [209.132.180.131]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by ozlabs.org (Postfix) with ESMTPS id 3zdFjb6gDKz9s82 for ; Sat, 10 Feb 2018 00:08:03 +1100 (AEDT) DomainKey-Signature: a=rsa-sha1; c=nofws; d=sourceware.org; h=list-id :list-unsubscribe:list-subscribe:list-archive:list-post :list-help:sender:from:to:cc:subject:date:message-id:in-reply-to :references; q=dns; s=default; b=D8G0DcSUlyRfHbezfca0TRC3wDg5+Vz oNuApMc7YU3rW4WZiiQTY4uqdtAJrXlyxFlgtcNBuAVkviDw6XyQMAIeNJYRbEdn 6Mwx2yVp9Fcxrjb6IOimjqSSroux9b/qP5y/Z9Bgfj+sOr9N/slStmh1agWoOToo PIlRwIEApWwo= DKIM-Signature: v=1; a=rsa-sha1; c=relaxed; d=sourceware.org; h=list-id :list-unsubscribe:list-subscribe:list-archive:list-post :list-help:sender:from:to:cc:subject:date:message-id:in-reply-to :references; s=default; bh=igX3KM9RxUEpcS6HCERxKadM7/8=; b=gRuqz Yr+IIrHAtvGmw49CVW1ZnrJDuv6ASUKAnSsrQ8lWR69iX/wrCmv7zWEMFIBre25q 9Fuc1SpdGx4F0JzKXTN0B/RvVG+pY19BDir+E0+u4RN0/iLdYNUpzSRIkOCpJbMg Rv4UwVXICuU0dAPgf48fk1XiJwWDRXONlXE8oE= Received: (qmail 83945 invoked by alias); 9 Feb 2018 13:07:58 -0000 Mailing-List: contact libc-alpha-help@sourceware.org; run by ezmlm Precedence: bulk List-Id: List-Unsubscribe: List-Subscribe: List-Archive: List-Post: List-Help: , Sender: libc-alpha-owner@sourceware.org Delivered-To: mailing list libc-alpha@sourceware.org Received: (qmail 83934 invoked by uid 89); 9 Feb 2018 13:07:57 -0000 Authentication-Results: sourceware.org; auth=none X-Virus-Found: No X-Spam-SWARE-Status: No, score=-25.2 required=5.0 tests=AWL, BAYES_00, GIT_PATCH_0, GIT_PATCH_1, GIT_PATCH_2, GIT_PATCH_3, SPF_PASS, T_RP_MATCHES_RCVD autolearn=ham version=3.3.2 spammy= X-HELO: smtp.pacific.net From: Rical Jasan To: libc-alpha Cc: Andreas Schwab , Paul Eggert Subject: [PATCH] manual: Document the standardized scanf flag, "m". [BZ #16376] Date: Fri, 9 Feb 2018 05:07:54 -0800 Message-Id: <20180209130754.16006-1-ricaljasan@pacific.net> In-Reply-To: <7c42f58d-d076-aeb3-a229-2581aa03af94@pacific.net> References: <7c42f58d-d076-aeb3-a229-2581aa03af94@pacific.net> POSIX.1-2008 introduced the optional assignment-allocation modifier, "m", whose functionality was previously provided by the GNU extension "a". [BZ #16376] * manual/stdio.texi (Input Conversion Syntax) (String Input Conversions, Dynamic String Input): Document the "m" flag. --- manual/stdio.texi | 32 ++++++++++++++++++++------------ 1 file changed, 20 insertions(+), 12 deletions(-) diff --git a/manual/stdio.texi b/manual/stdio.texi index 38be236991..22c338f8ea 100644 --- a/manual/stdio.texi +++ b/manual/stdio.texi @@ -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 @@ -3720,8 +3719,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 +Ask @code{scanf} to allocate a big-enough buffer, by specifying the +@samp{m} flag character. 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 +3824,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 +3832,27 @@ 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 predating @samp{m}, @samp{a} is also available, but +its use is considered deprecated. -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 ();