1/* ATTRIBUTE_* macros for using attributes in GCC and similar compilers
2
3   Copyright 2020 Free Software Foundation, Inc.
4
5   This program is free software: you can redistribute it and/or modify it
6   under the terms of the GNU General Public License as published
7   by the Free Software Foundation; either version 3 of the License, or
8   (at your option) any later version.
9
10   This program 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 GNU
13   General Public License for more details.
14
15   You should have received a copy of the GNU 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
80/* Attributes for variadic functions.  */
81
82/* The variadic function expects a trailing NULL argument.
83   ATTRIBUTE_SENTINEL () - The last argument is NULL.
84   ATTRIBUTE_SENTINEL ((N)) - The (N+1)st argument from the end is NULL.  */
85/* Applies to: functions.  */
86#define ATTRIBUTE_SENTINEL(pos) _GL_ATTRIBUTE_SENTINEL (pos)
87
88
89/* ================== Attributes for compiler diagnostics ================== */
90
91/* Attributes that help the compiler diagnose programmer mistakes.
92   Some of them may also help for some compiler optimizations.  */
93
94/* ATTRIBUTE_FORMAT ((ARCHETYPE, STRING-INDEX, FIRST-TO-CHECK)) -
95   The STRING-INDEXth function argument is a format string of style
96   ARCHETYPE, which is one of:
97     printf, gnu_printf
98     scanf, gnu_scanf,
99     strftime, gnu_strftime,
100     strfmon,
101   or the same thing prefixed and suffixed with '__'.
102   If FIRST-TO-CHECK is not 0, arguments starting at FIRST-TO_CHECK
103   are suitable for the format string.  */
104/* Applies to: functions.  */
105#define ATTRIBUTE_FORMAT(spec) _GL_ATTRIBUTE_FORMAT (spec)
106
107/* ATTRIBUTE_NONNULL ((N1, N2,...)) - Arguments N1, N2,... must not be NULL.
108   ATTRIBUTE_NONNULL () - All pointer arguments must not be null.  */
109/* Applies to: functions.  */
110#define ATTRIBUTE_NONNULL(args) _GL_ATTRIBUTE_NONNULL (args)
111
112/* The function's return value is a non-NULL pointer.  */
113/* Applies to: functions.  */
114#define ATTRIBUTE_RETURNS_NONNULL _GL_ATTRIBUTE_RETURNS_NONNULL
115
116/* Warn if the caller does not use the return value,
117   unless the caller uses something like ignore_value.  */
118/* Applies to: function, enumeration, class.  */
119#define NODISCARD _GL_ATTRIBUTE_NODISCARD
120
121
122/* Attributes that disable false alarms when the compiler diagnoses
123   programmer "mistakes".  */
124
125/* Do not warn if the entity is not used.  */
126/* Applies to:
127     - function, variable,
128     - struct, union, struct/union member,
129     - enumeration, enumeration item,
130     - typedef,
131   in C++ also: class.  */
132#define MAYBE_UNUSED _GL_ATTRIBUTE_MAYBE_UNUSED
133
134/* The contents of a character array is not meant to be NUL-terminated.  */
135/* Applies to: struct/union members and variables that are arrays of element
136   type '[[un]signed] char'.  */
137#define ATTRIBUTE_NONSTRING _GL_ATTRIBUTE_NONSTRING
138
139/* Do not warn if control flow falls through to the immediately
140   following 'case' or 'default' label.  */
141/* Applies to: Empty statement (;), inside a 'switch' statement.  */
142#define FALLTHROUGH _GL_ATTRIBUTE_FALLTHROUGH
143
144
145/* ================== Attributes for debugging information ================== */
146
147/* Attributes regarding debugging information emitted by the compiler.  */
148
149/* Omit the function from stack traces when debugging.  */
150/* Applies to: function.  */
151#define ATTRIBUTE_ARTIFICIAL _GL_ATTRIBUTE_ARTIFICIAL
152
153/* Make the entity visible to debuggers etc., even with '-fwhole-program'.  */
154/* Applies to: functions, variables.  */
155#define ATTRIBUTE_EXTERNALLY_VISIBLE _GL_ATTRIBUTE_EXTERNALLY_VISIBLE
156
157
158/* ========== Attributes that mainly direct compiler optimizations ========== */
159
160/* The function does not throw exceptions.  */
161/* Applies to: functions.  */
162#define ATTRIBUTE_NOTHROW _GL_ATTRIBUTE_NOTHROW
163
164/* Do not inline the function.  */
165/* Applies to: functions.  */
166#define ATTRIBUTE_NOINLINE _GL_ATTRIBUTE_NOINLINE
167
168/* Always inline the function, and report an error if the compiler
169   cannot inline.  */
170/* Applies to: function.  */
171#define ATTRIBUTE_ALWAYS_INLINE _GL_ATTRIBUTE_ALWAYS_INLINE
172
173/* The function does not affect observable state, and always returns a value.
174   Compilers can omit duplicate calls with the same arguments if
175   observable state is not changed between calls.  (This attribute is
176   looser than ATTRIBUTE_CONST.)  */
177/* Applies to: functions.  */
178#define ATTRIBUTE_PURE _GL_ATTRIBUTE_PURE
179
180/* The function neither depends on nor affects observable state,
181   and always returns a value.  Compilers can omit duplicate calls with
182   the same arguments.  (This attribute is stricter than ATTRIBUTE_PURE.)  */
183/* Applies to: functions.  */
184#define ATTRIBUTE_CONST _GL_ATTRIBUTE_CONST
185
186/* The function is rarely executed.  */
187/* Applies to: functions.  */
188#define ATTRIBUTE_COLD _GL_ATTRIBUTE_COLD
189
190/* If called from some other compilation unit, the function executes
191   code from that unit only by return or by exception handling,
192   letting the compiler optimize that unit more aggressively.  */
193/* Applies to: functions.  */
194#define ATTRIBUTE_LEAF _GL_ATTRIBUTE_LEAF
195
196/* For struct members: The member has the smallest possible alignment.
197   For struct, union, class: All members have the smallest possible alignment,
198   minimizing the memory required.  */
199/* Applies to: struct members, struct, union,
200   in C++ also: class.  */
201#define ATTRIBUTE_PACKED _GL_ATTRIBUTE_PACKED
202
203
204/* ================ Attributes that make invalid code valid ================ */
205
206/* Attributes that prevent fatal compiler optimizations for code that is not
207   fully ISO C compliant.  */
208
209/* Pointers to the type may point to the same storage as pointers to
210   other types, thus disabling strict aliasing optimization.  */
211/* Applies to: types.  */
212#define ATTRIBUTE_MAY_ALIAS _GL_ATTRIBUTE_MAY_ALIAS
213
214
215#endif /* _GL_ATTRIBUTE_H */
216