Debian Codegraph @

lib/c++defs.h

raw
1 /* C++ compatible function declaration macros.
2 Copyright (C) 2010-2026 Free Software Foundation, Inc.
3
4 This program is free software: you can redistribute it and/or modify it
5 under the terms of the GNU Lesser General Public License as published
6 by the Free Software Foundation; either version 2 of the License, or
7 (at your option) any later version.
8
9 This program is distributed in the hope that it will be useful,
10 but WITHOUT ANY WARRANTY; without even the implied warranty of
11 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
12 Lesser General Public License for more details.
13
14 You should have received a copy of the GNU Lesser General Public License
15 along with this program. If not, see <https://www.gnu.org/licenses/>. */
16
17 #ifndef _GL_CXXDEFS_H
18 #define _GL_CXXDEFS_H
19
20 /* Begin/end the GNULIB_NAMESPACE namespace. */
21 #if defined __cplusplus && defined GNULIB_NAMESPACE
22 # define _GL_BEGIN_NAMESPACE namespace GNULIB_NAMESPACE {
23 # define _GL_END_NAMESPACE }
24 #else
25 # define _GL_BEGIN_NAMESPACE
26 # define _GL_END_NAMESPACE
27 #endif
28
29 /* The three most frequent use cases of these macros are:
30
31 * For providing a substitute for a function that is missing on some
32 platforms, but is declared and works fine on the platforms on which
33 it exists:
34
35 #if @GNULIB_FOO@
36 # if !@HAVE_FOO@
37 _GL_FUNCDECL_SYS (foo, ...);
38 # endif
39 _GL_CXXALIAS_SYS (foo, ...);
40 _GL_CXXALIASWARN (foo);
41 #elif defined GNULIB_POSIXCHECK
42 ...
43 #endif
44
45 * For providing a replacement for a function that exists on all platforms,
46 but is broken/insufficient and needs to be replaced on some platforms:
47
48 #if @GNULIB_FOO@
49 # if @REPLACE_FOO@
50 # if !(defined __cplusplus && defined GNULIB_NAMESPACE)
51 # undef foo
52 # define foo rpl_foo
53 # endif
54 _GL_FUNCDECL_RPL (foo, ...);
55 _GL_CXXALIAS_RPL (foo, ...);
56 # else
57 _GL_CXXALIAS_SYS (foo, ...);
58 # endif
59 _GL_CXXALIASWARN (foo);
60 #elif defined GNULIB_POSIXCHECK
61 ...
62 #endif
63
64 * For providing a replacement for a function that exists on some platforms
65 but is broken/insufficient and needs to be replaced on some of them and
66 is additionally either missing or undeclared on some other platforms:
67
68 #if @GNULIB_FOO@
69 # if @REPLACE_FOO@
70 # if !(defined __cplusplus && defined GNULIB_NAMESPACE)
71 # undef foo
72 # define foo rpl_foo
73 # endif
74 _GL_FUNCDECL_RPL (foo, ...);
75 _GL_CXXALIAS_RPL (foo, ...);
76 # else
77 # if !@HAVE_FOO@ or if !@HAVE_DECL_FOO@
78 _GL_FUNCDECL_SYS (foo, ...);
79 # endif
80 _GL_CXXALIAS_SYS (foo, ...);
81 # endif
82 _GL_CXXALIASWARN (foo);
83 #elif defined GNULIB_POSIXCHECK
84 ...
85 #endif
86 */
87
88 /* _GL_EXTERN_C declaration;
89 performs the declaration with C linkage. */
90 #if defined __cplusplus
91 # define _GL_EXTERN_C extern "C"
92 #else
93 # define _GL_EXTERN_C extern
94 #endif
95
96 /* _GL_EXTERN_C_FUNC declaration;
97 performs the declaration of a function with C linkage. */
98 #if defined __cplusplus
99 # define _GL_EXTERN_C_FUNC extern "C"
100 #else
101 /* In C mode, omit the 'extern' keyword, because attributes in bracket syntax
102 are not allowed between 'extern' and the return type (see gnulib-common.m4).
103 */
104 # define _GL_EXTERN_C_FUNC
105 #endif
106
107 /* _GL_FUNCDECL_RPL (func, rettype, parameters, [attributes]);
108 declares a replacement function, named rpl_func, with the given prototype,
109 consisting of return type, parameters, and attributes.
110 Although attributes are optional, the comma before them is required
111 for portability to C17 and earlier. The attribute _GL_ATTRIBUTE_NOTHROW,
112 if needed, must be placed after the _GL_FUNCDECL_RPL invocation,
113 at the end of the declaration.
114 Examples:
115 _GL_FUNCDECL_RPL (free, void, (void *ptr), ) _GL_ATTRIBUTE_NOTHROW;
116 _GL_FUNCDECL_RPL (open, int, (const char *filename, int flags, ...),
117 _GL_ARG_NONNULL ((1)));
118
119 Note: Attributes, such as _GL_ATTRIBUTE_DEPRECATED, are supported in front
120 of a _GL_FUNCDECL_RPL invocation only in C mode, not in C++ mode. (That's
121 because
122 [[...]] extern "C" <declaration>;
123 is invalid syntax in C++.)
124 */
125 #define _GL_FUNCDECL_RPL(func,rettype,parameters,...) \
126 _GL_FUNCDECL_RPL_1 (rpl_##func, rettype, parameters, __VA_ARGS__)
127 #define _GL_FUNCDECL_RPL_1(rpl_func,rettype,parameters,...) \
128 _GL_EXTERN_C_FUNC __VA_ARGS__ rettype rpl_func parameters
129
130 /* _GL_FUNCDECL_SYS_NAME (func) expands to plain func if C++, and to
131 parenthesized func otherwise. Parenthesization is needed in C23 if
132 the function is like strchr and so is a qualifier-generic macro
133 that expands to something more complicated. */
134 #ifdef __cplusplus
135 # define _GL_FUNCDECL_SYS_NAME(func) func
136 #else
137 # define _GL_FUNCDECL_SYS_NAME(func) (func)
138 #endif
139
140 /* _GL_FUNCDECL_SYS (func, rettype, parameters, [attributes]);
141 declares the system function, named func, with the given prototype,
142 consisting of return type, parameters, and attributes.
143 Although attributes are optional, the comma before them is required
144 for portability to C17 and earlier. The attribute _GL_ATTRIBUTE_NOTHROW,
145 if needed, must be placed after the _GL_FUNCDECL_RPL invocation,
146 at the end of the declaration.
147 Examples:
148 _GL_FUNCDECL_SYS (getumask, mode_t, (void), ) _GL_ATTRIBUTE_NOTHROW;
149 _GL_FUNCDECL_SYS (posix_openpt, int, (int flags), _GL_ATTRIBUTE_NODISCARD);
150 */
151 #define _GL_FUNCDECL_SYS(func,rettype,parameters,...) \
152 _GL_EXTERN_C_FUNC __VA_ARGS__ rettype _GL_FUNCDECL_SYS_NAME (func) parameters
153
154 /* _GL_CXXALIAS_RPL (func, rettype, parameters);
155 declares a C++ alias called GNULIB_NAMESPACE::func
156 that redirects to rpl_func, if GNULIB_NAMESPACE is defined.
157 Example:
158 _GL_CXXALIAS_RPL (open, int, (const char *filename, int flags, ...));
159
160 Wrapping rpl_func in an object with an inline conversion operator
161 avoids a reference to rpl_func unless GNULIB_NAMESPACE::func is
162 actually used in the program. */
163 #define _GL_CXXALIAS_RPL(func,rettype,parameters) \
164 _GL_CXXALIAS_RPL_1 (func, rpl_##func, rettype, parameters)
165 #if defined __cplusplus && defined GNULIB_NAMESPACE
166 # define _GL_CXXALIAS_RPL_1(func,rpl_func,rettype,parameters) \
167 namespace GNULIB_NAMESPACE \
168 { \
169 static const struct _gl_ ## func ## _wrapper \
170 { \
171 typedef rettype (*type) parameters; \
172 \
173 inline operator type () const \
174 { \
175 return ::rpl_func; \
176 } \
177 } func = {}; \
178 } \
179 _GL_EXTERN_C int _gl_cxxalias_dummy
180 #else
181 # define _GL_CXXALIAS_RPL_1(func,rpl_func,rettype,parameters) \
182 _GL_EXTERN_C int _gl_cxxalias_dummy
183 #endif
184
185 /* _GL_CXXALIAS_MDA (func, rettype, parameters);
186 is to be used when func is a Microsoft deprecated alias, on native Windows.
187 It declares a C++ alias called GNULIB_NAMESPACE::func
188 that redirects to _func, if GNULIB_NAMESPACE is defined.
189 Example:
190 _GL_CXXALIAS_MDA (open, int, (const char *filename, int flags, ...));
191 */
192 #define _GL_CXXALIAS_MDA(func,rettype,parameters) \
193 _GL_CXXALIAS_RPL_1 (func, _##func, rettype, parameters)
194
195 /* _GL_CXXALIAS_RPL_CAST_1 (func, rpl_func, rettype, parameters);
196 is like _GL_CXXALIAS_RPL_1 (func, rpl_func, rettype, parameters);
197 except that the C function rpl_func may have a slightly different
198 declaration. A cast is used to silence the "invalid conversion" error
199 that would otherwise occur. */
200 #if defined __cplusplus && defined GNULIB_NAMESPACE
201 # define _GL_CXXALIAS_RPL_CAST_1(func,rpl_func,rettype,parameters) \
202 namespace GNULIB_NAMESPACE \
203 { \
204 static const struct _gl_ ## func ## _wrapper \
205 { \
206 typedef rettype (*type) parameters; \
207 \
208 inline operator type () const \
209 { \
210 return reinterpret_cast<type>(::rpl_func); \
211 } \
212 } func = {}; \
213 } \
214 _GL_EXTERN_C int _gl_cxxalias_dummy
215 #else
216 # define _GL_CXXALIAS_RPL_CAST_1(func,rpl_func,rettype,parameters) \
217 _GL_EXTERN_C int _gl_cxxalias_dummy
218 #endif
219
220 /* _GL_CXXALIAS_MDA_CAST (func, rettype, parameters);
221 is like _GL_CXXALIAS_MDA (func, rettype, parameters);
222 except that the C function func may have a slightly different declaration.
223 A cast is used to silence the "invalid conversion" error that would
224 otherwise occur. */
225 #define _GL_CXXALIAS_MDA_CAST(func,rettype,parameters) \
226 _GL_CXXALIAS_RPL_CAST_1 (func, _##func, rettype, parameters)
227
228 /* _GL_CXXALIAS_SYS (func, rettype, parameters);
229 declares a C++ alias called GNULIB_NAMESPACE::func
230 that redirects to the system provided function func, if GNULIB_NAMESPACE
231 is defined.
232 Example:
233 _GL_CXXALIAS_SYS (open, int, (const char *filename, int flags, ...));
234
235 Wrapping func in an object with an inline conversion operator
236 avoids a reference to func unless GNULIB_NAMESPACE::func is
237 actually used in the program. */
238 #if defined __cplusplus && defined GNULIB_NAMESPACE
239 # define _GL_CXXALIAS_SYS(func,rettype,parameters) \
240 namespace GNULIB_NAMESPACE \
241 { \
242 static const struct _gl_ ## func ## _wrapper \
243 { \
244 typedef rettype (*type) parameters; \
245 \
246 inline operator type () const \
247 { \
248 return ::func; \
249 } \
250 } func = {}; \
251 } \
252 _GL_EXTERN_C int _gl_cxxalias_dummy
253 #else
254 # define _GL_CXXALIAS_SYS(func,rettype,parameters) \
255 _GL_EXTERN_C int _gl_cxxalias_dummy
256 #endif
257
258 /* _GL_CXXALIAS_SYS_CAST (func, rettype, parameters);
259 is like _GL_CXXALIAS_SYS (func, rettype, parameters);
260 except that the C function func may have a slightly different declaration.
261 A cast is used to silence the "invalid conversion" error that would
262 otherwise occur. */
263 #if defined __cplusplus && defined GNULIB_NAMESPACE
264 # define _GL_CXXALIAS_SYS_CAST(func,rettype,parameters) \
265 namespace GNULIB_NAMESPACE \
266 { \
267 static const struct _gl_ ## func ## _wrapper \
268 { \
269 typedef rettype (*type) parameters; \
270 \
271 inline operator type () const \
272 { \
273 return reinterpret_cast<type>(::func); \
274 } \
275 } func = {}; \
276 } \
277 _GL_EXTERN_C int _gl_cxxalias_dummy
278 #else
279 # define _GL_CXXALIAS_SYS_CAST(func,rettype,parameters) \
280 _GL_EXTERN_C int _gl_cxxalias_dummy
281 #endif
282
283 /* _GL_CXXALIAS_SYS_CAST2 (func, rettype, parameters, rettype2, parameters2);
284 is like _GL_CXXALIAS_SYS (func, rettype, parameters);
285 except that the C function is picked among a set of overloaded functions,
286 namely the one with rettype2 and parameters2. Two consecutive casts
287 are used to silence the "cannot find a match" and "invalid conversion"
288 errors that would otherwise occur. */
289 #if defined __cplusplus && defined GNULIB_NAMESPACE
290 /* The outer cast must be a reinterpret_cast.
291 The inner cast: When the function is defined as a set of overloaded
292 functions, it works as a static_cast<>, choosing the designated variant.
293 When the function is defined as a single variant, it works as a
294 reinterpret_cast<>. The parenthesized cast syntax works both ways. */
295 # define _GL_CXXALIAS_SYS_CAST2(func,rettype,parameters,rettype2,parameters2) \
296 namespace GNULIB_NAMESPACE \
297 { \
298 static const struct _gl_ ## func ## _wrapper \
299 { \
300 typedef rettype (*type) parameters; \
301 \
302 inline operator type () const \
303 { \
304 return reinterpret_cast<type>((rettype2 (*) parameters2)(::func)); \
305 } \
306 } func = {}; \
307 } \
308 _GL_EXTERN_C int _gl_cxxalias_dummy
309 #else
310 # define _GL_CXXALIAS_SYS_CAST2(func,rettype,parameters,rettype2,parameters2) \
311 _GL_EXTERN_C int _gl_cxxalias_dummy
312 #endif
313
314 /* _GL_CXXALIASWARN (func);
315 causes a warning to be emitted when ::func is used but not when
316 GNULIB_NAMESPACE::func is used. func must be defined without overloaded
317 variants. */
318 #if defined __cplusplus && defined GNULIB_NAMESPACE
319 # define _GL_CXXALIASWARN(func) \
320 _GL_CXXALIASWARN_1 (func, GNULIB_NAMESPACE)
321 # define _GL_CXXALIASWARN_1(func,namespace) \
322 _GL_CXXALIASWARN_2 (func, namespace)
323 /* To work around GCC bug <https://gcc.gnu.org/PR43881>,
324 we enable the warning only when not optimizing. */
325 # if !(defined __GNUC__ && !defined __clang__ && __OPTIMIZE__)
326 # define _GL_CXXALIASWARN_2(func,namespace) \
327 _GL_WARN_ON_USE (func, \
328 "The symbol ::" #func " refers to the system function. " \
329 "Use " #namespace "::" #func " instead.")
330 # elif (__GNUC__ >= 3 || defined __clang__) && GNULIB_STRICT_CHECKING
331 # define _GL_CXXALIASWARN_2(func,namespace) \
332 extern __typeof__ (func) func
333 # else
334 # define _GL_CXXALIASWARN_2(func,namespace) \
335 _GL_EXTERN_C int _gl_cxxalias_dummy
336 # endif
337 #else
338 # define _GL_CXXALIASWARN(func) \
339 _GL_EXTERN_C int _gl_cxxalias_dummy
340 #endif
341
342 /* _GL_CXXALIASWARN1 (func, rettype, parameters_and_attributes);
343 causes a warning to be emitted when the given overloaded variant of ::func
344 is used but not when GNULIB_NAMESPACE::func is used. */
345 #if defined __cplusplus && defined GNULIB_NAMESPACE
346 # define _GL_CXXALIASWARN1(func,rettype,parameters_and_attributes) \
347 _GL_CXXALIASWARN1_1 (func, rettype, parameters_and_attributes, \
348 GNULIB_NAMESPACE)
349 # define _GL_CXXALIASWARN1_1(func,rettype,parameters_and_attributes,namespace) \
350 _GL_CXXALIASWARN1_2 (func, rettype, parameters_and_attributes, namespace)
351 /* To work around GCC bug <https://gcc.gnu.org/PR43881>,
352 we enable the warning only when not optimizing. */
353 # if !(defined __GNUC__ && !defined __clang__ && __OPTIMIZE__)
354 # define _GL_CXXALIASWARN1_2(func,rettype,parameters_and_attributes,namespace) \
355 _GL_WARN_ON_USE_CXX (func, rettype, rettype, parameters_and_attributes, \
356 "The symbol ::" #func " refers to the system function. " \
357 "Use " #namespace "::" #func " instead.")
358 # else
359 # define _GL_CXXALIASWARN1_2(func,rettype,parameters_and_attributes,namespace) \
360 _GL_EXTERN_C int _gl_cxxalias_dummy
361 # endif
362 #else
363 # define _GL_CXXALIASWARN1(func,rettype,parameters_and_attributes) \
364 _GL_EXTERN_C int _gl_cxxalias_dummy
365 #endif
366
367 #endif /* _GL_CXXDEFS_H */