man/man3attr/gnu::format.3attr: Add page

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

diff --git a/man/man3attr/gnu::format.3attr b/man/man3attr/gnu::format.3attr
new file mode 100644 (file)
index 0000000..e48670a
--- /dev/null
+++ b/man/man3attr/gnu::format.3attr
@@ -0,0 +1,154 @@
+.\" 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 can be applied to a function.
+It specifies that a function parameter is a format string,
+and specifies the style of the 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.
+.P
+GCC-only.
+.RE
+.TP
+Solaris
+.RS
+.TQ
+.B cmn_err
+.RE
+.TP
+Darwin
+.RS
+.TQ
+.B CFString
+.RE
+.TP
+OpenBSD
+.RS
+.TQ
+.B kprintf
+.TQ
+.B syslog
+.TQ
+.B syslog
+Clang-only.
+.RE
+.TP
+FreeBSD
+.RS
+.TQ
+freebsd_kprintf
+Clang-only.
+.RE
+.P
+In some languages, other styles are additionally supported.
+.TP
+Objective-C
+.RS
+.TQ
+.B NSString
+.RE
+.SS Non-variadic functions
+Clang accepts the attribute on non-variadic functions as an extension.
+.SH STANDARDS
+GNU.
+.SH HISTORY
+gcc,
+g++,
+clang 2.8,
+clang++ 2.8.
+.SH EXAMPLES
+.in +4n
+.EX
+[[gnu::format(printf, 3, 0)]]
+int
+vstprintf(int size;
+    char buf[restrict size], int size,
+    const char *restrict fmt, va_list args)
+{
+       int len;
+\&
+       if (size == 0) {
+               errno = EOVERFLOW;
+               return -1;
+       }
+\&
+       len = vsnprintf(buf, size, fmt, args);
+       if (len >= size) {
+               errno = E2BIG;
+               return -1;
+       }
+\&
+       return len;
+}
+\&
+[[gnu::format(printf, 3, 4)]]
+int
+stprintf(int size;
+    char buf[restrict size], int size,
+    const char *restrict fmt, ...)
+{
+       int len;
+       va_list args;
+\&
+       va_start(args, fmt);
+       len = vstprintf(buf, size, fmt, args);
+       va_end(args);
+\&
+       return len;
+}
+.EE