Debian Codegraph @

lib/attribute.h

raw
1 /* ATTRIBUTE_* macros for using attributes in GCC and similar compilers
2
3 Copyright 2020-2024 Free Software Foundation, Inc.
4
5 This file is free software: you can redistribute it and/or modify
6 it under the terms of the GNU Lesser General Public License as
7 published by the Free Software Foundation; either version 2.1 of the
8 License, or (at your option) any later version.
9
10 This file is distributed in the hope that it will be useful,
11 but WITHOUT ANY WARRANTY; without even the implied warranty of
12 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
13 GNU Lesser General Public License for more details.
14
15 You should have received a copy of the GNU Lesser General Public License
16 along with this program. If not, see <https://www.gnu.org/licenses/>. */
17
18 /* Written by Paul Eggert. */
19
20 /* Provide public ATTRIBUTE_* names for the private _GL_ATTRIBUTE_*
21 macros used within Gnulib. */
22
23 /* The placement of these attributes depends on the kind of declaration
24 and, in some cases, also on the programming language (C vs. C++).
25
26 In function declarations and function definitions:
27
28 * ATTRIBUTE_NOTHROW must come after the parameter list.
29
30 * The macros
31 ATTRIBUTE_CONST
32 ATTRIBUTE_PURE
33 DEPRECATED
34 MAYBE_UNUSED
35 NODISCARD
36 REPRODUCIBLE
37 UNSEQUENCED
38 must come before the return type, and more precisely:
39 - In a function declaration/definition without a storage-class
40 specifier: at the beginning of the declaration/definition.
41 - In a function declaration/definition with a storage-class
42 specifier:
43 - In C: before the storage-class specifier.
44 - In C++: between the storage-class specifier and the return type.
45
46 * The other macros can be placed
47 - Either
48 - In a function declaration/definition without a storage-class
49 specifier: at the beginning of the declaration/definition.
50 - In a function declaration/definition with a storage-class
51 specifier: between the storage-class specifier and the return
52 type.
53 - Or after the parameter list,
54 ∙ but after ATTRIBUTE_NOTHROW if present.
55
56 In other declarations, such as variable declarations:
57
58 * Either
59 - In C: before the storage-class specifier.
60 - In C++: between the storage-class specifier and the return type.
61 Then they apply to all entities that are declared by the declaration.
62
63 * Or immediately after the name of an entity being declared by the
64 declaration. Then they apply to that entity only.
65 */
66
67 #ifndef _GL_ATTRIBUTE_H
68 #define _GL_ATTRIBUTE_H
69
70
71 /* This file defines two types of attributes:
72 * C23 standard attributes. These have macro names that do not begin with
73 'ATTRIBUTE_'.
74 * Selected GCC attributes; see:
75 https://gcc.gnu.org/onlinedocs/gcc/Common-Function-Attributes.html
76 https://gcc.gnu.org/onlinedocs/gcc/Common-Variable-Attributes.html
77 https://gcc.gnu.org/onlinedocs/gcc/Common-Type-Attributes.html
78 These names begin with 'ATTRIBUTE_' to avoid name clashes. */
79
80
81 /* This file uses _GL_ATTRIBUTE_ALLOC_SIZE, _GL_ATTRIBUTE_ALWAYS_INLINE,
82 _GL_ATTRIBUTE_ARTIFICIAL, _GL_ATTRIBUTE_COLD, _GL_ATTRIBUTE_CONST,
83 _GL_ATTRIBUTE_DEALLOC, _GL_ATTRIBUTE_DEPRECATED, _GL_ATTRIBUTE_ERROR,
84 _GL_ATTRIBUTE_WARNING, _GL_ATTRIBUTE_EXTERNALLY_VISIBLE,
85 _GL_ATTRIBUTE_FALLTHROUGH, _GL_ATTRIBUTE_FORMAT, _GL_ATTRIBUTE_LEAF,
86 _GL_ATTRIBUTE_MALLOC, _GL_ATTRIBUTE_MAY_ALIAS, _GL_ATTRIBUTE_MAYBE_UNUSED,
87 _GL_ATTRIBUTE_NODISCARD, _GL_ATTRIBUTE_NOINLINE, _GL_ATTRIBUTE_NONNULL,
88 _GL_ATTRIBUTE_NONSTRING, _GL_ATTRIBUTE_NOTHROW, _GL_ATTRIBUTE_PACKED,
89 _GL_ATTRIBUTE_PURE, _GL_ATTRIBUTE_REPRODUCIBLE,
90 _GL_ATTRIBUTE_RETURNS_NONNULL, _GL_ATTRIBUTE_SENTINEL,
91 _GL_ATTRIBUTE_UNSEQUENCED. */
92 #if !_GL_CONFIG_H_INCLUDED
93 #error "Please include config.h first."
94 #endif
95
96
97 /* =============== Attributes for specific kinds of functions =============== */
98
99 /* Attributes for functions that should not be used. */
100
101 /* Warn if the entity is used. */
102 /* Applies to:
103 - function, variable,
104 - struct, union, struct/union member,
105 - enumeration, enumeration item,
106 - typedef,
107 in C++ also: namespace, class, template specialization. */
108 #define DEPRECATED _GL_ATTRIBUTE_DEPRECATED
109
110 /* If a function call is not optimized way, warn with MSG. */
111 /* Applies to: functions. */
112 #define ATTRIBUTE_WARNING(msg) _GL_ATTRIBUTE_WARNING (msg)
113
114 /* If a function call is not optimized way, report an error with MSG. */
115 /* Applies to: functions. */
116 #define ATTRIBUTE_ERROR(msg) _GL_ATTRIBUTE_ERROR (msg)
117
118
119 /* Attributes for memory-allocating functions. */
120
121 /* The function returns a pointer to freshly allocated memory. */
122 /* Applies to: functions. */
123 #define ATTRIBUTE_MALLOC _GL_ATTRIBUTE_MALLOC
124
125 /* ATTRIBUTE_ALLOC_SIZE ((N)) - The Nth argument of the function
126 is the size of the returned memory block.
127 ATTRIBUTE_ALLOC_SIZE ((M, N)) - Multiply the Mth and Nth arguments
128 to determine the size of the returned memory block. */
129 /* Applies to: functions, pointer to functions, function types. */
130 #define ATTRIBUTE_ALLOC_SIZE(args) _GL_ATTRIBUTE_ALLOC_SIZE (args)
131
132 /* ATTRIBUTE_DEALLOC (F, I) declares that the function returns pointers
133 that can be freed by passing them as the Ith argument to the
134 function F.
135 ATTRIBUTE_DEALLOC_FREE declares that the function returns pointers that
136 can be freed via 'free'; it can be used only after declaring 'free'. */
137 /* Applies to: functions. Cannot be used on inline functions. */
138 #define ATTRIBUTE_DEALLOC(f, i) _GL_ATTRIBUTE_DEALLOC(f, i)
139 #define ATTRIBUTE_DEALLOC_FREE _GL_ATTRIBUTE_DEALLOC_FREE
140
141 /* Attributes for variadic functions. */
142
143 /* The variadic function expects a trailing NULL argument.
144 ATTRIBUTE_SENTINEL () - The last argument is NULL (requires C99).
145 ATTRIBUTE_SENTINEL ((N)) - The (N+1)st argument from the end is NULL. */
146 /* Applies to: functions. */
147 #define ATTRIBUTE_SENTINEL(pos) _GL_ATTRIBUTE_SENTINEL (pos)
148
149
150 /* ================== Attributes for compiler diagnostics ================== */
151
152 /* Attributes that help the compiler diagnose programmer mistakes.
153 Some of them may also help for some compiler optimizations. */
154
155 /* ATTRIBUTE_FORMAT ((ARCHETYPE, STRING-INDEX, FIRST-TO-CHECK)) -
156 The STRING-INDEXth function argument is a format string of style
157 ARCHETYPE, which is one of:
158 printf, gnu_printf
159 scanf, gnu_scanf,
160 strftime, gnu_strftime,
161 strfmon,
162 or the same thing prefixed and suffixed with '__'.
163 If FIRST-TO-CHECK is not 0, arguments starting at FIRST-TO_CHECK
164 are suitable for the format string. */
165 /* Applies to: functions. */
166 #define ATTRIBUTE_FORMAT(spec) _GL_ATTRIBUTE_FORMAT (spec)
167
168 /* ATTRIBUTE_NONNULL ((N1, N2,...)) - Arguments N1, N2,... must not be NULL.
169 ATTRIBUTE_NONNULL () - All pointer arguments must not be null. */
170 /* Applies to: functions. */
171 #define ATTRIBUTE_NONNULL(args) _GL_ATTRIBUTE_NONNULL (args)
172
173 /* The function's return value is a non-NULL pointer. */
174 /* Applies to: functions. */
175 #define ATTRIBUTE_RETURNS_NONNULL _GL_ATTRIBUTE_RETURNS_NONNULL
176
177 /* Warn if the caller does not use the return value,
178 unless the caller uses something like ignore_value. */
179 /* Applies to: function, enumeration, class. */
180 #define NODISCARD _GL_ATTRIBUTE_NODISCARD
181
182
183 /* Attributes that disable false alarms when the compiler diagnoses
184 programmer "mistakes". */
185
186 /* Do not warn if the entity is not used. */
187 /* Applies to:
188 - function, variable,
189 - struct, union, struct/union member,
190 - enumeration, enumeration item,
191 - typedef,
192 in C++ also: class. */
193 #define MAYBE_UNUSED _GL_ATTRIBUTE_MAYBE_UNUSED
194
195 /* The contents of a character array is not meant to be NUL-terminated. */
196 /* Applies to: struct/union members and variables that are arrays of element
197 type '[[un]signed] char'. */
198 #define ATTRIBUTE_NONSTRING _GL_ATTRIBUTE_NONSTRING
199
200 /* Do not warn if control flow falls through to the immediately
201 following 'case' or 'default' label. */
202 /* Applies to: Empty statement (;), inside a 'switch' statement. */
203 #define FALLTHROUGH _GL_ATTRIBUTE_FALLTHROUGH
204
205
206 /* ================== Attributes for debugging information ================== */
207
208 /* Attributes regarding debugging information emitted by the compiler. */
209
210 /* Omit the function from stack traces when debugging. */
211 /* Applies to: functions. */
212 #define ATTRIBUTE_ARTIFICIAL _GL_ATTRIBUTE_ARTIFICIAL
213
214 /* Make the entity visible to debuggers etc., even with '-fwhole-program'. */
215 /* Applies to: functions, variables. */
216 #define ATTRIBUTE_EXTERNALLY_VISIBLE _GL_ATTRIBUTE_EXTERNALLY_VISIBLE
217
218
219 /* ========== Attributes that mainly direct compiler optimizations ========== */
220
221 /* The function does not throw exceptions. */
222 /* Applies to: functions. */
223 /* After a function's parameter list, this attribute must come first, before
224 other attributes. */
225 #define ATTRIBUTE_NOTHROW _GL_ATTRIBUTE_NOTHROW
226
227 /* Do not inline the function. */
228 /* Applies to: functions. */
229 #define ATTRIBUTE_NOINLINE _GL_ATTRIBUTE_NOINLINE
230
231 /* Always inline the function, and report an error if the compiler
232 cannot inline. */
233 /* Applies to: functions. */
234 #define ATTRIBUTE_ALWAYS_INLINE _GL_ATTRIBUTE_ALWAYS_INLINE
235
236 /* It is OK for a compiler to move calls to the function and to omit
237 calls to the function if another call has the same arguments or the
238 result is not used.
239 This attribute is safe for a function that neither depends on
240 nor affects state, and always returns exactly once -
241 e.g., does not raise an exception, call longjmp, or loop forever.
242 (This attribute is stricter than ATTRIBUTE_PURE because the
243 function cannot observe state. It is stricter than UNSEQUENCED
244 because the function must return exactly once and cannot depend on
245 state addressed by its arguments.) */
246 /* Applies to: functions. */
247 #define ATTRIBUTE_CONST _GL_ATTRIBUTE_CONST
248
249 /* It is OK for a compiler to move calls to the function and to omit duplicate
250 calls to the function with the same arguments, so long as the state
251 addressed by its arguments is the same.
252 This attribute is safe for a function that is effectless, idempotent,
253 stateless, and independent; see ISO C 23 § 6.7.12.7 for a definition of
254 these terms.
255 (This attribute is stricter than REPRODUCIBLE because the function
256 must be stateless and independent. It is looser than ATTRIBUTE_CONST
257 because the function need not return exactly once and can depend
258 on state addressed by its arguments.)
259 See also <https://www.open-std.org/jtc1/sc22/wg14/www/docs/n2956.htm> and
260 <https://stackoverflow.com/questions/76847905/>. */
261 /* Applies to: functions, pointer to functions, function type. */
262 #define UNSEQUENCED _GL_ATTRIBUTE_UNSEQUENCED
263
264 /* It is OK for a compiler to move calls to the function and to omit
265 calls to the function if another call has the same arguments or the
266 result is not used, and if observable state is the same.
267 This attribute is safe for a function that does not affect observable state
268 and always returns exactly once.
269 (This attribute is looser than ATTRIBUTE_CONST because the function
270 can depend on observable state. It is stricter than REPRODUCIBLE
271 because the function must return exactly once and cannot affect
272 state addressed by its arguments.) */
273 /* Applies to: functions. */
274 #define ATTRIBUTE_PURE _GL_ATTRIBUTE_PURE
275
276 /* It is OK for a compiler to move calls to the function and to omit duplicate
277 calls to the function with the same arguments, so long as the state
278 addressed by its arguments is the same and is updated in time for
279 the rest of the program.
280 This attribute is safe for a function that is effectless and idempotent; see
281 ISO C 23 § 6.7.12.7 for a definition of these terms.
282 (This attribute is looser than UNSEQUENCED because the function need
283 not be stateless and idempotent. It is looser than ATTRIBUTE_PURE
284 because the function need not return exactly once and can affect
285 state addressed by its arguments.)
286 See also <https://www.open-std.org/jtc1/sc22/wg14/www/docs/n2956.htm> and
287 <https://stackoverflow.com/questions/76847905/>. */
288 /* Applies to: functions, pointer to functions, function type. */
289 #define REPRODUCIBLE _GL_ATTRIBUTE_REPRODUCIBLE
290
291 /* The function is rarely executed. */
292 /* Applies to: functions. */
293 #define ATTRIBUTE_COLD _GL_ATTRIBUTE_COLD
294
295 /* If called from some other compilation unit, the function executes
296 code from that unit only by return or by exception handling,
297 letting the compiler optimize that unit more aggressively. */
298 /* Applies to: functions. */
299 #define ATTRIBUTE_LEAF _GL_ATTRIBUTE_LEAF
300
301 /* For struct members: The member has the smallest possible alignment.
302 For struct, union, class: All members have the smallest possible alignment,
303 minimizing the memory required. */
304 /* Applies to: struct members, struct, union,
305 in C++ also: class. */
306 #define ATTRIBUTE_PACKED _GL_ATTRIBUTE_PACKED
307
308
309 /* ================ Attributes that make invalid code valid ================ */
310
311 /* Attributes that prevent fatal compiler optimizations for code that is not
312 fully ISO C compliant. */
313
314 /* Pointers to the type may point to the same storage as pointers to
315 other types, thus disabling strict aliasing optimization. */
316 /* Applies to: types. */
317 #define ATTRIBUTE_MAY_ALIAS _GL_ATTRIBUTE_MAY_ALIAS
318
319
320 #endif /* _GL_ATTRIBUTE_H */