source: trunk/src/sed/lib/attribute.h@ 3661

Last change on this file since 3661 was 3613, checked in by bird, 14 months ago

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