Debian Codegraph @

lib/attribute.h

raw
1 /* ATTRIBUTE_* macros for using attributes in GCC and similar compilers
2
3 Copyright 2020-2026 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, in a function declaration:
54 after the parameter list,
55 ∙ but after ATTRIBUTE_NOTHROW if present.
56
57 In other declarations, such as variable declarations:
58
59 * Either
60 - In C: before the storage-class specifier.
61 - In C++: between the storage-class specifier and the return type.
62 Then they apply to all entities that are declared by the declaration.
63
64 * Or immediately after the name of an entity being declared by the
65 declaration. Then they apply to that entity only.
66 */
67
68 #ifndef _GL_ATTRIBUTE_H
69 #define _GL_ATTRIBUTE_H
70
71
72 /* This file defines two types of attributes:
73 * C23 standard attributes. These have macro names that do not begin with
74 'ATTRIBUTE_'.
75 * Selected GCC attributes; see:
76 https://gcc.gnu.org/onlinedocs/gcc/Common-Function-Attributes.html
77 https://gcc.gnu.org/onlinedocs/gcc/Common-Variable-Attributes.html
78 https://gcc.gnu.org/onlinedocs/gcc/Common-Type-Attributes.html
79 These names begin with 'ATTRIBUTE_' to avoid name clashes. */
80
81
82 /* This file uses _GL_ATTRIBUTE_ALLOC_SIZE, _GL_ATTRIBUTE_ALWAYS_INLINE,
83 _GL_ATTRIBUTE_ARTIFICIAL, _GL_ATTRIBUTE_COLD, _GL_ATTRIBUTE_CONST,
84 _GL_ATTRIBUTE_DEALLOC, _GL_ATTRIBUTE_DEPRECATED, _GL_ATTRIBUTE_ERROR,
85 _GL_ATTRIBUTE_WARNING, _GL_ATTRIBUTE_EXTERNALLY_VISIBLE,
86 _GL_ATTRIBUTE_FALLTHROUGH, _GL_ATTRIBUTE_FORMAT, _GL_ATTRIBUTE_LEAF,
87 _GL_ATTRIBUTE_MALLOC, _GL_ATTRIBUTE_MAY_ALIAS, _GL_ATTRIBUTE_MAYBE_UNUSED,
88 _GL_ATTRIBUTE_NODISCARD, _GL_ATTRIBUTE_NOINLINE, _GL_ATTRIBUTE_NONNULL,
89 _GL_ATTRIBUTE_NONNULL_IF_NONZERO, _GL_ATTRIBUTE_NONSTRING,
90 _GL_ATTRIBUTE_NOTHROW, _GL_ATTRIBUTE_PACKED, _GL_ATTRIBUTE_PURE,
91 _GL_ATTRIBUTE_REPRODUCIBLE, _GL_ATTRIBUTE_RETURNS_NONNULL,
92 _GL_ATTRIBUTE_SENTINEL, _GL_ATTRIBUTE_UNSEQUENCED, _GL_UNNAMED. */
93 #if !_GL_CONFIG_H_INCLUDED
94 #error "Please include config.h first."
95 #endif
96
97
98 /* =============== Attributes for specific kinds of functions =============== */
99
100 /* Attributes for functions that should not be used. */
101
102 /* Warn if the entity is used. */
103 /* Applies to:
104 - function, variable,
105 - struct, union, struct/union member,
106 - enumeration, enumeration item,
107 - typedef,
108 in C++ also: namespace, class, template specialization. */
109 #define DEPRECATED _GL_ATTRIBUTE_DEPRECATED
110
111 /* If a function call is not optimized way, warn with MSG. */
112 /* Applies to: functions. */
113 #define ATTRIBUTE_WARNING(msg) _GL_ATTRIBUTE_WARNING (msg)
114
115 /* If a function call is not optimized way, report an error with MSG. */
116 /* Applies to: functions. */
117 #define ATTRIBUTE_ERROR(msg) _GL_ATTRIBUTE_ERROR (msg)
118
119
120 /* Attributes for memory-allocating functions. */
121
122 /* The function returns a pointer to freshly allocated memory. */
123 /* Applies to: functions. */
124 #define ATTRIBUTE_MALLOC _GL_ATTRIBUTE_MALLOC
125
126 /* ATTRIBUTE_ALLOC_SIZE ((N)) - The Nth argument of the function
127 is the size of the returned memory block.
128 ATTRIBUTE_ALLOC_SIZE ((M, N)) - Multiply the Mth and Nth arguments
129 to determine the size of the returned memory block. */
130 /* Applies to: functions, pointer to functions, function types. */
131 #define ATTRIBUTE_ALLOC_SIZE(args) _GL_ATTRIBUTE_ALLOC_SIZE (args)
132
133 /* ATTRIBUTE_DEALLOC (F, I) declares that the function returns pointers
134 that can be freed by passing them as the Ith argument to the
135 function F.
136 ATTRIBUTE_DEALLOC_FREE declares that the function returns pointers that
137 can be freed via 'free'; it can be used only after declaring 'free'. */
138 /* Applies to: functions. Cannot be used on inline functions. */
139 #define ATTRIBUTE_DEALLOC(f, i) _GL_ATTRIBUTE_DEALLOC(f, i)
140 #define ATTRIBUTE_DEALLOC_FREE _GL_ATTRIBUTE_DEALLOC_FREE
141
142 /* Attributes for variadic functions. */
143
144 /* The variadic function expects a trailing NULL argument.
145 ATTRIBUTE_SENTINEL () - The last argument is NULL (requires C99).
146 ATTRIBUTE_SENTINEL ((N)) - The (N+1)st argument from the end is NULL. */
147 /* Applies to: functions. */
148 #define ATTRIBUTE_SENTINEL(pos) _GL_ATTRIBUTE_SENTINEL (pos)
149
150
151 /* ================== Attributes for compiler diagnostics ================== */
152
153 /* Attributes that help the compiler diagnose programmer mistakes.
154 Some of them may also help for some compiler optimizations. */
155
156 /* ATTRIBUTE_FORMAT ((ARCHETYPE, STRING-INDEX, FIRST-TO-CHECK)) -
157 The STRING-INDEXth function argument is a format string of style
158 ARCHETYPE, which is one of:
159 printf, gnu_printf
160 scanf, gnu_scanf,
161 strftime, gnu_strftime,
162 strfmon,
163 or the same thing prefixed and suffixed with '__'.
164 If FIRST-TO-CHECK is not 0, arguments starting at FIRST-TO_CHECK
165 are suitable for the format string. */
166 /* Applies to: functions. */
167 #define ATTRIBUTE_FORMAT(spec) _GL_ATTRIBUTE_FORMAT (spec)
168
169 /* ATTRIBUTE_NONNULL ((N1, N2,...)) - Arguments N1, N2,... must not be NULL.
170 ATTRIBUTE_NONNULL () - All pointer arguments must not be null. */
171 /* Applies to: functions. */
172 #define ATTRIBUTE_NONNULL(args) _GL_ATTRIBUTE_NONNULL (args)
173
174 /* ATTRIBUTE_NONNULL_IF_NONZERO (NP, NI) - Argument NP (a pointer)
175 must not be NULL if the argument NI (an integer) is != 0. */
176 /* Applies to: functions. */
177 #define ATTRIBUTE_NONNULL_IF_NONZERO(np, ni) _GL_ATTRIBUTE_NONNULL_IF_NONZERO (np, ni)
178
179
180 /* The function's return value is a non-NULL pointer. */
181 /* Applies to: functions. */
182 #define ATTRIBUTE_RETURNS_NONNULL _GL_ATTRIBUTE_RETURNS_NONNULL
183
184 /* Warn if the caller does not use the return value,
185 unless the caller uses something like ignore_value. */
186 /* Applies to: function, enumeration, class. */
187 #define NODISCARD _GL_ATTRIBUTE_NODISCARD
188
189
190 /* Attributes that disable false alarms when the compiler diagnoses
191 programmer "mistakes". */
192
193 /* Do not warn if the entity is not used. */
194 /* Applies to:
195 - function, variable,
196 - struct, union, struct/union member,
197 - enumeration, enumeration item,
198 - typedef,
199 in C++ also: class. */
200 #define MAYBE_UNUSED _GL_ATTRIBUTE_MAYBE_UNUSED
201
202 /* The contents of a character array is not meant to be NUL-terminated. */
203 /* Applies to: struct/union members and variables that are arrays of element
204 type '[[un]signed] char'. */
205 #define ATTRIBUTE_NONSTRING _GL_ATTRIBUTE_NONSTRING
206
207 /* Do not warn if control flow falls through to the immediately
208 following 'case' or 'default' label. */
209 /* Applies to: Empty statement (;), inside a 'switch' statement. */
210 #define FALLTHROUGH _GL_ATTRIBUTE_FALLTHROUGH
211
212
213 /* ================== Attributes for debugging information ================== */
214
215 /* Attributes regarding debugging information emitted by the compiler. */
216
217 /* Omit the function from stack traces when debugging. */
218 /* Applies to: functions. */
219 #define ATTRIBUTE_ARTIFICIAL _GL_ATTRIBUTE_ARTIFICIAL
220
221 /* Make the entity visible to debuggers etc., even with '-fwhole-program'. */
222 /* Applies to: functions, variables. */
223 #define ATTRIBUTE_EXTERNALLY_VISIBLE _GL_ATTRIBUTE_EXTERNALLY_VISIBLE
224
225
226 /* ========== Attributes that mainly direct compiler optimizations ========== */
227
228 /* The function does not throw exceptions. */
229 /* Applies to: functions. */
230 /* After a function's parameter list, this attribute must come first, before
231 other attributes. */
232 #define ATTRIBUTE_NOTHROW _GL_ATTRIBUTE_NOTHROW
233
234 /* Do not inline the function. */
235 /* Applies to: functions. */
236 #define ATTRIBUTE_NOINLINE _GL_ATTRIBUTE_NOINLINE
237
238 /* Always inline the function, and report an error if the compiler
239 cannot inline. */
240 /* Applies to: functions. */
241 #define ATTRIBUTE_ALWAYS_INLINE _GL_ATTRIBUTE_ALWAYS_INLINE
242
243 /* It is OK for a compiler to move a call, or omit a duplicate call
244 and reuse a cached return value, even if the state changes between calls.
245 It is also OK to omit a call if the result is not used.
246 This attribute is safe if the function does not change observable state,
247 returns a value determined solely by its arguments' values
248 without examining state, and always returns exactly once -
249 e.g., does not raise an exception, call longjmp, or loop forever.
250 (This attribute is stricter than _GL_ATTRIBUTE_PURE because the
251 function cannot observe state. Unlike _GL_ATTRIBUTE_UNSEQUENCED
252 the function must return exactly once and cannot access state
253 addressed by its pointer arguments or that happens to have the same
254 value for all calls to the function, but the function is allowed to
255 return a pointer to storage that can be modified later. */
256 /* Applies to: functions. */
257 #define ATTRIBUTE_CONST _GL_ATTRIBUTE_CONST
258
259 /* It is OK for a compiler to move a call, or omit a duplicate call
260 and reuse a cached value returned either directly or indirectly via
261 a pointer, if the state addressed by its pointer arguments is the same;
262 however, pointer arguments cannot alias.
263 This attribute is safe for a function that is effectless, idempotent,
264 stateless, and independent; see ISO C 23 § 6.7.13.8 for a definition of
265 these terms.
266 (This attribute is stricter than _GL_ATTRIBUTE_REPRODUCIBLE because
267 the function must be stateless and independent. Unlike
268 _GL_ATTRIBUTE_CONST the function need not return exactly once, and
269 can depend on state accessed via its pointer arguments or that
270 happens to have the same value for all calls to the function, but
271 the function cannot return a pointer to storage whose contents
272 change later.)
273 See also <https://www.open-std.org/jtc1/sc22/wg14/www/docs/n2956.htm> and
274 <https://stackoverflow.com/questions/76847905/>. */
275 /* Applies to: functions, pointer to functions, function type. */
276 #define UNSEQUENCED _GL_ATTRIBUTE_UNSEQUENCED
277
278 /* It is OK for a compiler to move a call, or omit a duplicate call
279 and reuse a cached return value, if observable state is the same.
280 It is also OK to omit a call if the return value is not used.
281 This attribute is safe if the function does not change observable state,
282 returns a value determined solely by its arguments's values
283 together with observable state, and always returns exactly once.
284 (This attribute is looser than _GL_ATTRIBUTE_CONST because the function
285 can depend on observable state.
286 Unlike _GL_ATTRIBUTE_REPRODUCIBLE the function must return exactly
287 once and cannot change state addressed by its arguments, but the
288 function can return a pointer to storage whose contents change later.) */
289 /* Applies to: functions. */
290 #define ATTRIBUTE_PURE _GL_ATTRIBUTE_PURE
291
292 /* It is OK for a compiler to move a call, or omit a duplicate call
293 and reuse a cached value returned either directly or indirectly via
294 a pointer, if other observable state is the same;
295 however, pointer arguments cannot alias.
296 This attribute is safe for a function that is effectless and idempotent;
297 see ISO C 23 § 6.7.13.8 for a definition of these terms.
298 (This attribute is looser than _GL_ATTRIBUTE_UNSEQUENCED because
299 the function need not be stateless or independent.
300 Unlike _GL_ATTRIBUTE_PURE the function need not return exactly once
301 and can change state addressed by its pointer arguments, but the
302 function cannot return a pointer to storage whose contents change later.)
303 See also <https://www.open-std.org/jtc1/sc22/wg14/www/docs/n2956.htm> and
304 <https://stackoverflow.com/questions/76847905/>. */
305 /* Applies to: functions, pointer to functions, function type. */
306 #define REPRODUCIBLE _GL_ATTRIBUTE_REPRODUCIBLE
307
308 /* The function is rarely executed. */
309 /* Applies to: functions. */
310 #define ATTRIBUTE_COLD _GL_ATTRIBUTE_COLD
311
312 /* If called from some other compilation unit, the function executes
313 code from that unit only by return or by exception handling,
314 letting the compiler optimize that unit more aggressively. */
315 /* Applies to: functions. */
316 #define ATTRIBUTE_LEAF _GL_ATTRIBUTE_LEAF
317
318 /* For struct members: The member has the smallest possible alignment.
319 For struct, union, class: All members have the smallest possible alignment,
320 minimizing the memory required. */
321 /* Applies to: struct members, struct, union,
322 in C++ also: class. */
323 #define ATTRIBUTE_PACKED _GL_ATTRIBUTE_PACKED
324
325
326 /* ================ Attributes that make invalid code valid ================ */
327
328 /* Attributes that prevent fatal compiler optimizations for code that is not
329 fully ISO C compliant. */
330
331 /* Pointers to the type may point to the same storage as pointers to
332 other types, thus disabling strict aliasing optimization. */
333 /* Applies to: types. */
334 #define ATTRIBUTE_MAY_ALIAS _GL_ATTRIBUTE_MAY_ALIAS
335
336
337 /* ==================== Unnamed function parameters ======================== */
338
339 /* Although UNNAMED is not an attribute, it is related to MAYBE_UNUSED
340 and so is defined here for convenience. */
341
342 /* UNNAMED (ID) is the "name" of an unnamed function parameter.
343 Each of the function's unnamed parameters should have a unique "name".
344 The "name" cannot be used. This ports both to C17 and earlier, which
345 lack unnamed parameters, and to C++ and later C, which have them. */
346 /* Applies to:
347 - function parameters. */
348 #define UNNAMED(id) _GL_UNNAMED (id)
349
350
351 #endif /* _GL_ATTRIBUTE_H */