Debian Codegraph @

upstream/debian-unstable/man3/gnu::format.3attr

raw
1 .\" Copyright, the authors of the Linux man-pages project
2 .\"
3 .\" SPDX-License-Identifier: Linux-man-pages-copyleft
4 .\"
5 .TH gnu::format 3attr 2025-09-25 "Linux man-pages 6.18"
6 .SH NAME
7 gnu::format \- specify the style of format string
8 .SH SYNOPSIS
9 .nf
10 .BI [[gnu::format( style ,\~ fmt-idx ,\~ first-idx )]]
11 .fi
12 .SH DESCRIPTION
13 This attribute can be applied to a function.
14 It specifies that a function parameter is a format string,
15 and specifies the style of the format string.
16 This allows checking the syntax of the format string,
17 as well as the types of the variadic arguments.
18 The
19 .I style
20 can be one of the following.
21 .TP
22 .B printf
23 .TQ
24 .B scanf
25 .TQ
26 .B strftime
27 .TQ
28 .B strfmon
29 .P
30 .I fmt-idx
31 is a 1-based index that
32 specifies the position of the format string within the parameter list.
33 .P
34 .I first-idx
35 is a 1-based index that
36 specifies the position of the first argument
37 that corresponds to the format string.
38 If the first argument is part of a
39 .I va_list
40 argument,
41 it should be specified as
42 .BR 0 .
43 .SH VERSIONS
44 .SS GNU syntax
45 .TP
46 .BI __attribute__((format( style ,\~ fmt-idx ,\~ first-idx )))
47 .SS Styles
48 On some targets, other styles are additionally supported.
49 .TP
50 MinGW
51 .TQ
52 Microsoft Windows
53 .RS
54 .TQ
55 .B ms_printf
56 .TQ
57 .B ms_scanf
58 .TQ
59 .B ms_strftime
60 .P
61 These correspond to the formats supported by the
62 .I msvcrt.dll
63 library.
64 .P
65 GCC-only.
66 .RE
67 .TP
68 Solaris
69 .RS
70 .TQ
71 .B cmn_err
72 .RE
73 .TP
74 Darwin
75 .RS
76 .TQ
77 .B CFString
78 .RE
79 .TP
80 OpenBSD
81 .RS
82 .TQ
83 .B kprintf
84 .TQ
85 .B syslog
86 .TQ
87 .B syslog
88 Clang-only.
89 .RE
90 .TP
91 FreeBSD
92 .RS
93 .TQ
94 freebsd_kprintf
95 Clang-only.
96 .RE
97 .P
98 In some languages, other styles are additionally supported.
99 .TP
100 Objective-C
101 .RS
102 .TQ
103 .B NSString
104 .RE
105 .SS Non-variadic functions
106 Clang accepts the attribute on non-variadic functions as an extension.
107 .SH STANDARDS
108 GNU.
109 .SH HISTORY
110 gcc,
111 g++,
112 clang 2.8,
113 clang++ 2.8.
114 .SH EXAMPLES
115 .in +4n
116 .EX
117 [[gnu::format(printf, 3, 0)]]
118 int
119 vstprintf(int size;
120 char buf[restrict size], int size,
121 const char *restrict fmt, va_list args)
122 {
123 int len;
124 \&
125 if (size == 0) {
126 errno = EOVERFLOW;
127 return \-1;
128 }
129 \&
130 len = vsnprintf(buf, size, fmt, args);
131 if (len >= size) {
132 errno = E2BIG;
133 return \-1;
134 }
135 \&
136 return len;
137 }
138 \&
139 [[gnu::format(printf, 3, 4)]]
140 int
141 stprintf(int size;
142 char buf[restrict size], int size,
143 const char *restrict fmt, ...)
144 {
145 int len;
146 va_list args;
147 \&
148 va_start(args, fmt);
149 len = vstprintf(buf, size, fmt, args);
150 va_end(args);
151 \&
152 return len;
153 }
154 .EE