1 /* ATTRIBUTE_* macros for using attributes in GCC and similar compilers
2
3 Copyright 2020-2023 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 /* These attributes can be placed in two ways:
24 - At the start of a declaration (i.e. even before storage-class
25 specifiers!); then they apply to all entities that are declared
26 by the declaration.
27 - Immediately after the name of an entity being declared by the
28 declaration; then they apply to that entity only. */
29
30 #ifndef _GL_ATTRIBUTE_H
31 #define _GL_ATTRIBUTE_H
32
33
34 /* This file defines two types of attributes:
35 * C23 standard attributes. These have macro names that do not begin with
36 'ATTRIBUTE_'.
37 * Selected GCC attributes; see:
38 https://gcc.gnu.org/onlinedocs/gcc/Common-Function-Attributes.html
39 https://gcc.gnu.org/onlinedocs/gcc/Common-Variable-Attributes.html
40 https://gcc.gnu.org/onlinedocs/gcc/Common-Type-Attributes.html
41 These names begin with 'ATTRIBUTE_' to avoid name clashes. */
42
43
44 /* This file uses _GL_ATTRIBUTE_ALLOC_SIZE, _GL_ATTRIBUTE_ALWAYS_INLINE,
45 _GL_ATTRIBUTE_ARTIFICIAL, _GL_ATTRIBUTE_COLD, _GL_ATTRIBUTE_CONST,
46 _GL_ATTRIBUTE_DEALLOC, _GL_ATTRIBUTE_DEPRECATED, _GL_ATTRIBUTE_ERROR,
47 _GL_ATTRIBUTE_WARNING, _GL_ATTRIBUTE_EXTERNALLY_VISIBLE,
48 _GL_ATTRIBUTE_FALLTHROUGH, _GL_ATTRIBUTE_FORMAT, _GL_ATTRIBUTE_LEAF,
49 _GL_ATTRIBUTE_MALLOC, _GL_ATTRIBUTE_MAY_ALIAS, _GL_ATTRIBUTE_MAYBE_UNUSED,
50 _GL_ATTRIBUTE_NODISCARD, _GL_ATTRIBUTE_NOINLINE, _GL_ATTRIBUTE_NONNULL,
51 _GL_ATTRIBUTE_NONSTRING, _GL_ATTRIBUTE_NOTHROW, _GL_ATTRIBUTE_PACKED,
52 _GL_ATTRIBUTE_PURE, _GL_ATTRIBUTE_RETURNS_NONNULL,
53 _GL_ATTRIBUTE_SENTINEL. */
54 #if !_GL_CONFIG_H_INCLUDED
55 #error "Please include config.h first."
56 #endif
57
58
59 /* =============== Attributes for specific kinds of functions =============== */
60
61 /* Attributes for functions that should not be used. */
62
63 /* Warn if the entity is used. */
64 /* Applies to:
65 - function, variable,
66 - struct, union, struct/union member,
67 - enumeration, enumeration item,
68 - typedef,
69 in C++ also: namespace, class, template specialization. */
70 #define DEPRECATED _GL_ATTRIBUTE_DEPRECATED
71
72 /* If a function call is not optimized way, warn with MSG. */
73 /* Applies to: functions. */
74 #define ATTRIBUTE_WARNING(msg) _GL_ATTRIBUTE_WARNING (msg)
75
76 /* If a function call is not optimized way, report an error with MSG. */
77 /* Applies to: functions. */
78 #define ATTRIBUTE_ERROR(msg) _GL_ATTRIBUTE_ERROR (msg)
79
80
81 /* Attributes for memory-allocating functions. */
82
83 /* The function returns a pointer to freshly allocated memory. */
84 /* Applies to: functions. */
85 #define ATTRIBUTE_MALLOC _GL_ATTRIBUTE_MALLOC
86
87 /* ATTRIBUTE_ALLOC_SIZE ((N)) - The Nth argument of the function
88 is the size of the returned memory block.
89 ATTRIBUTE_ALLOC_SIZE ((M, N)) - Multiply the Mth and Nth arguments
90 to determine the size of the returned memory block. */
91 /* Applies to: function, pointer to function, function types. */
92 #define ATTRIBUTE_ALLOC_SIZE(args) _GL_ATTRIBUTE_ALLOC_SIZE (args)
93
94 /* ATTRIBUTE_DEALLOC (F, I) declares that the function returns pointers
95 that can be freed by passing them as the Ith argument to the
96 function F.
97 ATTRIBUTE_DEALLOC_FREE declares that the function returns pointers that
98 can be freed via 'free'; it can be used only after declaring 'free'. */
99 /* Applies to: functions. Cannot be used on inline functions. */
100 #define ATTRIBUTE_DEALLOC(f, i) _GL_ATTRIBUTE_DEALLOC(f, i)
101 #define ATTRIBUTE_DEALLOC_FREE _GL_ATTRIBUTE_DEALLOC_FREE
102
103 /* Attributes for variadic functions. */
104
105 /* The variadic function expects a trailing NULL argument.
106 ATTRIBUTE_SENTINEL () - The last argument is NULL (requires C99).
107 ATTRIBUTE_SENTINEL ((N)) - The (N+1)st argument from the end is NULL. */
108 /* Applies to: functions. */
109 #define ATTRIBUTE_SENTINEL(pos) _GL_ATTRIBUTE_SENTINEL (pos)
110
111
112 /* ================== Attributes for compiler diagnostics ================== */
113
114 /* Attributes that help the compiler diagnose programmer mistakes.
115 Some of them may also help for some compiler optimizations. */
116
117 /* ATTRIBUTE_FORMAT ((ARCHETYPE, STRING-INDEX, FIRST-TO-CHECK)) -
118 The STRING-INDEXth function argument is a format string of style
119 ARCHETYPE, which is one of:
120 printf, gnu_printf
121 scanf, gnu_scanf,
122 strftime, gnu_strftime,
123 strfmon,
124 or the same thing prefixed and suffixed with '__'.
125 If FIRST-TO-CHECK is not 0, arguments starting at FIRST-TO_CHECK
126 are suitable for the format string. */
127 /* Applies to: functions. */
128 #define ATTRIBUTE_FORMAT(spec) _GL_ATTRIBUTE_FORMAT (spec)
129
130 /* ATTRIBUTE_NONNULL ((N1, N2,...)) - Arguments N1, N2,... must not be NULL.
131 ATTRIBUTE_NONNULL () - All pointer arguments must not be null. */
132 /* Applies to: functions. */
133 #define ATTRIBUTE_NONNULL(args) _GL_ATTRIBUTE_NONNULL (args)
134
135 /* The function's return value is a non-NULL pointer. */
136 /* Applies to: functions. */
137 #define ATTRIBUTE_RETURNS_NONNULL _GL_ATTRIBUTE_RETURNS_NONNULL
138
139 /* Warn if the caller does not use the return value,
140 unless the caller uses something like ignore_value. */
141 /* Applies to: function, enumeration, class. */
142 #define NODISCARD _GL_ATTRIBUTE_NODISCARD
143
144
145 /* Attributes that disable false alarms when the compiler diagnoses
146 programmer "mistakes". */
147
148 /* Do not warn if the entity is not used. */
149 /* Applies to:
150 - function, variable,
151 - struct, union, struct/union member,
152 - enumeration, enumeration item,
153 - typedef,
154 in C++ also: class. */
155 #define MAYBE_UNUSED _GL_ATTRIBUTE_MAYBE_UNUSED
156
157 /* The contents of a character array is not meant to be NUL-terminated. */
158 /* Applies to: struct/union members and variables that are arrays of element
159 type '[[un]signed] char'. */
160 #define ATTRIBUTE_NONSTRING _GL_ATTRIBUTE_NONSTRING
161
162 /* Do not warn if control flow falls through to the immediately
163 following 'case' or 'default' label. */
164 /* Applies to: Empty statement (;), inside a 'switch' statement. */
165 #define FALLTHROUGH _GL_ATTRIBUTE_FALLTHROUGH
166
167
168 /* ================== Attributes for debugging information ================== */
169
170 /* Attributes regarding debugging information emitted by the compiler. */
171
172 /* Omit the function from stack traces when debugging. */
173 /* Applies to: function. */
174 #define ATTRIBUTE_ARTIFICIAL _GL_ATTRIBUTE_ARTIFICIAL
175
176 /* Make the entity visible to debuggers etc., even with '-fwhole-program'. */
177 /* Applies to: functions, variables. */
178 #define ATTRIBUTE_EXTERNALLY_VISIBLE _GL_ATTRIBUTE_EXTERNALLY_VISIBLE
179
180
181 /* ========== Attributes that mainly direct compiler optimizations ========== */
182
183 /* The function does not throw exceptions. */
184 /* Applies to: functions. */
185 #define ATTRIBUTE_NOTHROW _GL_ATTRIBUTE_NOTHROW
186
187 /* Do not inline the function. */
188 /* Applies to: functions. */
189 #define ATTRIBUTE_NOINLINE _GL_ATTRIBUTE_NOINLINE
190
191 /* Always inline the function, and report an error if the compiler
192 cannot inline. */
193 /* Applies to: function. */
194 #define ATTRIBUTE_ALWAYS_INLINE _GL_ATTRIBUTE_ALWAYS_INLINE
195
196 /* It is OK for a compiler to omit duplicate calls with the same arguments.
197 This attribute is safe for a function that neither depends on
198 nor affects observable state, and always returns exactly once -
199 e.g., does not loop forever, and does not call longjmp.
200 (This attribute is stricter than ATTRIBUTE_PURE.) */
201 /* Applies to: functions. */
202 #define ATTRIBUTE_CONST _GL_ATTRIBUTE_CONST
203
204 /* It is OK for a compiler to omit duplicate calls with the same
205 arguments if observable state is not changed between calls.
206 This attribute is safe for a function that does not affect
207 observable state, and always returns exactly once.
208 (This attribute is looser than ATTRIBUTE_CONST.) */
209 /* Applies to: functions. */
210 #define ATTRIBUTE_PURE _GL_ATTRIBUTE_PURE
211
212 /* The function is rarely executed. */
213 /* Applies to: functions. */
214 #define ATTRIBUTE_COLD _GL_ATTRIBUTE_COLD
215
216 /* If called from some other compilation unit, the function executes
217 code from that unit only by return or by exception handling,
218 letting the compiler optimize that unit more aggressively. */
219 /* Applies to: functions. */
220 #define ATTRIBUTE_LEAF _GL_ATTRIBUTE_LEAF
221
222 /* For struct members: The member has the smallest possible alignment.
223 For struct, union, class: All members have the smallest possible alignment,
224 minimizing the memory required. */
225 /* Applies to: struct members, struct, union,
226 in C++ also: class. */
227 #define ATTRIBUTE_PACKED _GL_ATTRIBUTE_PACKED
228
229
230 /* ================ Attributes that make invalid code valid ================ */
231
232 /* Attributes that prevent fatal compiler optimizations for code that is not
233 fully ISO C compliant. */
234
235 /* Pointers to the type may point to the same storage as pointers to
236 other types, thus disabling strict aliasing optimization. */
237 /* Applies to: types. */
238 #define ATTRIBUTE_MAY_ALIAS _GL_ATTRIBUTE_MAY_ALIAS
239
240
241 #endif /* _GL_ATTRIBUTE_H */