gsasl  1.10.0
About: GNU SASL is an implementation of the Simple Authentication and Security Layer (SASL). Development version.
  Fossies Dox: gsasl-1.10.0.tar.gz  ("unofficial" and yet experimental doxygen-generated source code documentation)  

attribute.h
Go to the documentation of this file.
1 /* ATTRIBUTE_* macros for using attributes in GCC and similar compilers
2 
3  Copyright 2020-2021 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 (requires C99).
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 /* It is OK for a compiler to omit duplicate calls with the same arguments.
174  This attribute is safe for a function that neither depends on
175  nor affects observable state, and always returns exactly once -
176  e.g., does not loop forever, and does not call longjmp.
177  (This attribute is stricter than ATTRIBUTE_PURE.) */
178 /* Applies to: functions. */
179 #define ATTRIBUTE_CONST _GL_ATTRIBUTE_CONST
180 
181 /* It is OK for a compiler to omit duplicate calls with the same
182  arguments if observable state is not changed between calls.
183  This attribute is safe for a function that does not affect
184  observable state, and always returns exactly once.
185  (This attribute is looser than ATTRIBUTE_CONST.) */
186 /* Applies to: functions. */
187 #define ATTRIBUTE_PURE _GL_ATTRIBUTE_PURE
188 
189 /* The function is rarely executed. */
190 /* Applies to: functions. */
191 #define ATTRIBUTE_COLD _GL_ATTRIBUTE_COLD
192 
193 /* If called from some other compilation unit, the function executes
194  code from that unit only by return or by exception handling,
195  letting the compiler optimize that unit more aggressively. */
196 /* Applies to: functions. */
197 #define ATTRIBUTE_LEAF _GL_ATTRIBUTE_LEAF
198 
199 /* For struct members: The member has the smallest possible alignment.
200  For struct, union, class: All members have the smallest possible alignment,
201  minimizing the memory required. */
202 /* Applies to: struct members, struct, union,
203  in C++ also: class. */
204 #define ATTRIBUTE_PACKED _GL_ATTRIBUTE_PACKED
205 
206 
207 /* ================ Attributes that make invalid code valid ================ */
208 
209 /* Attributes that prevent fatal compiler optimizations for code that is not
210  fully ISO C compliant. */
211 
212 /* Pointers to the type may point to the same storage as pointers to
213  other types, thus disabling strict aliasing optimization. */
214 /* Applies to: types. */
215 #define ATTRIBUTE_MAY_ALIAS _GL_ATTRIBUTE_MAY_ALIAS
216 
217 
218 #endif /* _GL_ATTRIBUTE_H */