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