[PATCH] man/man3attr/gnu::format.3attr: Add page

[Alejandro Colomar <alx@kernel.org>]

Cc: Aaron Ballman <aaron@aaronballman.com>
Signed-off-by: Alejandro Colomar <alx@kernel.org>
---

Hi Aaron,

I've written another attribute page.  Would you mind reviewing this
page?  I often find myself needing to check documentation for
[[gnu::format()]], so I found it useful to have it as one of the first
manual pages for attributes, regardless of it being well-documented in
both GCC and Clang.

Please let me know the minimum Clang versions for clang and clang++ for
this attribute.

Here's the formatted page:

	$ MANWIDTH=64 man ./man3attr/gnu::format.3attr | cat;
	gnu::format(3attr)                           gnu::format(3attr)

	NAME
	     gnu::format - specify the style of format string

	SYNOPSIS
	     [[gnu::format(style, fmt‐idx, first‐idx)]]

	DESCRIPTION
	     This  attribute  specifies  the  style of a format string.
	     This allows checking the syntax of the format  string,  as
	     well  as  the  types of the variadic arguments.  The style
	     can be one of the following.

	     printf
	     scanf
	     strftime
	     strfmon

	     fmt‐idx is a 1‐based index that specifies the position  of
	     the format string within the parameter list.

	     first‐idx  is  a 1‐based index that specifies the position
	     of the first  argument  that  corresponds  to  the  format
	     string.   If the first argument is part of a va_list argu‐
	     ment, it should be specified as 0.

	VERSIONS
	   GNU syntax
	     __attribute__((format(style, fmt‐idx, first‐idx)))

	   Styles
	     On some targets, other styles are additionally supported.

	     MinGW
	     Microsoft Windows
		    ms_printf
		    ms_scanf
		    ms_strftime

		    These correspond to the formats  supported  by  the
		    msvcrt.dll library.

	     Solaris
		    cmn_err
	     Darwin
		    CFString

	     In  some  languages,  other  styles  are additionally sup‐
	     ported.

	     Objective‐C
		    NSString

	   Clang
	     Clang accepts the attribute on non‐variadic  functions  as
	     an extension.

	STANDARDS
	     GNU.

	HISTORY
	     gcc, g++, clang ?.?, clang++ ?.?.

	Linux man‐pages (unreleased) (date)          gnu::format(3attr)


Have a lovely day!
Alex

 man/man3attr/gnu::format.3attr | 91 ++++++++++++++++++++++++++++++++++
 1 file changed, 91 insertions(+)
 create mode 100644 man/man3attr/gnu::format.3attr

diff --git a/man/man3attr/gnu::format.3attr b/man/man3attr/gnu::format.3attr
new file mode 100644
index 000000000..bb3a7a460
--- /dev/null
+++ b/man/man3attr/gnu::format.3attr
@@ -0,0 +1,91 @@
+.\" Copyright, the authors of the Linux man-pages project
+.\"
+.\" SPDX-License-Identifier: Linux-man-pages-copyleft
+.\"
+.TH gnu::format 3attr (date) "Linux man-pages (unreleased)"
+.SH NAME
+gnu::format \- specify the style of format string
+.SH SYNOPSIS
+.nf
+.BI [[gnu::format( style ,\~ fmt-idx ,\~ first-idx )]]
+.fi
+.SH DESCRIPTION
+This attribute specifies the style of a format string.
+This allows checking the syntax of the format string,
+as well as the types of the variadic arguments.
+The
+.I style
+can be one of the following.
+.TP
+.B printf
+.TQ
+.B scanf
+.TQ
+.B strftime
+.TQ
+.B strfmon
+.P
+.I fmt-idx
+is a 1-based index that
+specifies the position of the format string within the parameter list.
+.P
+.I first-idx
+is a 1-based index that
+specifies the position of the first argument
+that corresponds to the format string.
+If the first argument is part of a
+.I va_list
+argument,
+it should be specified as
+.BR 0 .
+.SH VERSIONS
+.SS GNU syntax
+.TP
+.BI __attribute__((format( style ,\~ fmt-idx ,\~ first-idx )))
+.SS Styles
+On some targets, other styles are additionally supported.
+.TP
+MinGW
+.TQ
+Microsoft Windows
+.RS
+.TQ
+.B ms_printf
+.TQ
+.B ms_scanf
+.TQ
+.B ms_strftime
+.P
+These correspond to the formats supported by the
+.I msvcrt.dll
+library.
+.RE
+.TP
+Solaris
+.RS
+.TQ
+.B cmn_err
+.RE
+.TQ
+Darwin
+.RS
+.TQ
+.B CFString
+.RE
+.P
+In some languages, other styles are additionally supported.
+.TP
+Objective-C
+.RS
+.TQ
+.B NSString
+.RE
+.SS Clang
+Clang accepts the attribute on non-variadic functions as an extension.
+.SH STANDARDS
+GNU.
+.SH HISTORY
+gcc,
+g++,
+clang ?.?,
+clang++ ?.?.

base-commit: 2351c7c0a472e31b601855f4b4d843d3f37cbfa0
-- 
2.50.0