[doc PATCH] using multiple format-arg attributes on a single function (PR 87593)

[doc PATCH] using multiple format-arg attributes on a single function (PR 87593)

[Martin Sebor]

[-- Attachment #1: Type: text/plain, Size: 662 bytes --]

Attached is a documentation-only patch to clarify the use case
of multiple distinct format_arg attributes on a single function.
It's far from obvious that the use case makes sense so explicitly
mentioning it should help avoid the mistake of assuming that
accepting it is due to the lack of better checking in the area
(it could also prompt Clang to support the use case -- likely
an omission due to its obscurity).

However, since it makes less sense to declare the same function
multiple times with distinct format_arg attributes, a follow-on
improvement would be to issue a warning on such instances.  I'll
leave the bug open until that's implemented.

Martin

[-- Attachment #2: gcc-attr-format-arg.diff --]
[-- Type: text/x-patch, Size: 1924 bytes --]

gcc/ChangeLog:

	* doc/extend.texi (attribute format_arg): Discuss using multiple
	attributes on a single function.

diff --git a/gcc/doc/extend.texi b/gcc/doc/extend.texi
index 0d9b99f..6355453 100644
--- a/gcc/doc/extend.texi
+++ b/gcc/doc/extend.texi
@@ -2698,13 +2699,15 @@ Target Machines}.
 @item format_arg (@var{string-index})
 @cindex @code{format_arg} function attribute
 @opindex Wformat-nonliteral
-The @code{format_arg} attribute specifies that a function takes a format
-string for a @code{printf}, @code{scanf}, @code{strftime} or
+The @code{format_arg} attribute specifies that a function takes one or
+more format strings for a @code{printf}, @code{scanf}, @code{strftime} or
 @code{strfmon} style function and modifies it (for example, to translate
 it into another language), so the result can be passed to a
 @code{printf}, @code{scanf}, @code{strftime} or @code{strfmon} style
 function (with the remaining arguments to the format function the same
-as they would have been for the unmodified string).  For example, the
+as they would have been for the unmodified string).  Multiple
+@code{format_arg} attributes may be applied to the same function, each
+designating a distinct parameter as a format string.  For example, the
 declaration:
 
 @smallexample
@@ -2724,6 +2727,11 @@ string argument is not constant; this would generate a warning when
 @option{-Wformat-nonliteral} is used, but the calls could not be checked
 without the attribute.
 
+In calls to a function declared with more than one @code{format_arg}
+attribute, each with a distinct argument value, the corresponding
+actual function arguments are checked against all format strings
+designated by the attributes.
+
 The parameter @var{string-index} specifies which argument is the format
 string argument (starting from one).  Since non-static C++ methods have
 an implicit @code{this} argument, the arguments of such methods should

Re: [doc PATCH] using multiple format-arg attributes on a single function (PR 87593)

[Joseph Myers]

On Thu, 11 Oct 2018, Martin Sebor wrote:

> Attached is a documentation-only patch to clarify the use case
> of multiple distinct format_arg attributes on a single function.
> It's far from obvious that the use case makes sense so explicitly
> mentioning it should help avoid the mistake of assuming that
> accepting it is due to the lack of better checking in the area
> (it could also prompt Clang to support the use case -- likely
> an omission due to its obscurity).

This doc patch is OK (though I wonder if it should mention ngettext 
explicitly as an example of a use case for multiple format_arg 
attributes).

-- 
Joseph S. Myers
joseph@codesourcery.com

Re: [doc PATCH] using multiple format-arg attributes on a single function (PR 87593)

[Martin Sebor]

On 10/11/2018 04:38 PM, Joseph Myers wrote:
> On Thu, 11 Oct 2018, Martin Sebor wrote:
>
>> Attached is a documentation-only patch to clarify the use case
>> of multiple distinct format_arg attributes on a single function.
>> It's far from obvious that the use case makes sense so explicitly
>> mentioning it should help avoid the mistake of assuming that
>> accepting it is due to the lack of better checking in the area
>> (it could also prompt Clang to support the use case -- likely
>> an omission due to its obscurity).
>
> This doc patch is OK (though I wonder if it should mention ngettext
> explicitly as an example of a use case for multiple format_arg
> attributes).

I've committed r265073 with a sentence mentioning it.

Martin