From 483c9498dd5bf9056e7a84c46f2b1ff962e6d814 Mon Sep 17 00:00:00 2001 From: Alejandro Colomar Date: Fri, 18 Jul 2025 14:08:15 +0200 Subject: [PATCH] man/man3attr/gnu::format.3attr: Add page Cc: Aaron Ballman Signed-off-by: Alejandro Colomar --- man/man3attr/gnu::format.3attr | 154 +++++++++++++++++++++++++++++++++ 1 file changed, 154 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..e48670ad7 --- /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 -- 2.47.2