1/* GLIB - Library of useful routines for C programming
2 * Copyright (C) 1995-1997 Peter Mattis, Spencer Kimball and Josh MacDonald
3 *
4 * SPDX-License-Identifier: LGPL-2.1-or-later
5 *
6 * This library is free software; you can redistribute it and/or
7 * modify it under the terms of the GNU Lesser General Public
8 * License as published by the Free Software Foundation; either
9 * version 2.1 of the License, or (at your option) any later version.
10 *
11 * This library is distributed in the hope that it will be useful,
12 * but WITHOUT ANY WARRANTY; without even the implied warranty of
13 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
14 * Lesser General Public License for more details.
15 *
16 * You should have received a copy of the GNU Lesser General Public
17 * License along with this library; if not, see <http://www.gnu.org/licenses/>.
18 */
19
20/*
21 * Modified by the GLib Team and others 1997-2000. See the AUTHORS
22 * file for a list of people on the GLib Team. See the ChangeLog
23 * files for a list of changes. These files are distributed with
24 * GLib at ftp://ftp.gtk.org/pub/gtk/.
25 */
26
27/* This file must not include any other glib header file and must thus
28 * not refer to variables from glibconfig.h
29 */
30
31#ifndef __G_MACROS_H__
32#define __G_MACROS_H__
33
34#if !defined (__GLIB_H_INSIDE__) && !defined (GLIB_COMPILATION)
35#error "Only <glib.h> can be included directly."
36#endif
37
38/* We include stddef.h to get the system's definition of NULL
39 */
40#include <stddef.h>
41
42/*
43 * Note: Clang (but not clang-cl) defines __GNUC__ and __GNUC_MINOR__.
44 * Both Clang 11.1 on current Arch Linux and Apple's Clang 12.0 define
45 * __GNUC__ = 4 and __GNUC_MINOR__ = 2. So G_GNUC_CHECK_VERSION(4, 2) on
46 * current Clang will be 1.
47 */
48#ifdef __GNUC__
49#define G_GNUC_CHECK_VERSION(major, minor) \
50 ((__GNUC__ > (major)) || \
51 ((__GNUC__ == (major)) && \
52 (__GNUC_MINOR__ >= (minor))))
53#else
54#define G_GNUC_CHECK_VERSION(major, minor) 0
55#endif
56
57/* Here we provide G_GNUC_EXTENSION as an alias for __extension__,
58 * where this is valid. This allows for warningless compilation of
59 * "long long" types even in the presence of '-ansi -pedantic'.
60 */
61#if G_GNUC_CHECK_VERSION(2, 8)
62#define G_GNUC_EXTENSION __extension__
63#else
64#define G_GNUC_EXTENSION
65#endif
66
67#if !defined (__cplusplus)
68
69# undef G_CXX_STD_VERSION
70# define G_CXX_STD_CHECK_VERSION(version) (0)
71
72# if defined (__STDC_VERSION__)
73# define G_C_STD_VERSION __STDC_VERSION__
74# else
75# define G_C_STD_VERSION 199000L
76# endif /* defined (__STDC_VERSION__) */
77
78# define G_C_STD_CHECK_VERSION(version) ( \
79 ((version) >= 199000L && (version) <= G_C_STD_VERSION) || \
80 ((version) == 89 && G_C_STD_VERSION >= 199000L) || \
81 ((version) == 90 && G_C_STD_VERSION >= 199000L) || \
82 ((version) == 99 && G_C_STD_VERSION >= 199901L) || \
83 ((version) == 11 && G_C_STD_VERSION >= 201112L) || \
84 ((version) == 17 && G_C_STD_VERSION >= 201710L) || \
85 /* the canonical number for C23 is 202311L, but gcc 14 used 202000L and it \
86 * implemented almost all of the C23 standard (see https://en.cppreference.com/w/c/compiler_support/23) */ \
87 ((version) == 23 && G_C_STD_VERSION >= 202000L) || \
88 0)
89
90#else /* defined (__cplusplus) */
91
92# undef G_C_STD_VERSION
93# define G_C_STD_CHECK_VERSION(version) (0)
94
95# if defined (_MSVC_LANG)
96# define G_CXX_STD_VERSION (_MSVC_LANG > __cplusplus ? _MSVC_LANG : __cplusplus)
97# else
98# define G_CXX_STD_VERSION __cplusplus
99# endif /* defined(_MSVC_LANG) */
100
101# define G_CXX_STD_CHECK_VERSION(version) ( \
102 ((version) >= 199711L && (version) <= G_CXX_STD_VERSION) || \
103 ((version) == 98 && G_CXX_STD_VERSION >= 199711L) || \
104 ((version) == 03 && G_CXX_STD_VERSION >= 199711L) || \
105 ((version) == 11 && G_CXX_STD_VERSION >= 201103L) || \
106 ((version) == 14 && G_CXX_STD_VERSION >= 201402L) || \
107 ((version) == 17 && G_CXX_STD_VERSION >= 201703L) || \
108 ((version) == 20 && G_CXX_STD_VERSION >= 202002L) || \
109 ((version) == 23 && G_CXX_STD_VERSION >= 202302L) || \
110 0)
111
112#endif /* !defined (__cplusplus) */
113
114/* Every compiler that we target supports inlining, but some of them may
115 * complain about it if we don't say "__inline". If we have C99, or if
116 * we are using C++, then we can use "inline" directly.
117 * Otherwise, we say "__inline" to avoid the warning.
118 * Unfortunately Visual Studio does not define __STDC_VERSION__ (if not
119 * using /std:cXX) so we need to check whether we are on Visual Studio 2013
120 * or earlier to see whether we need to say "__inline" in C mode.
121 */
122#define G_CAN_INLINE
123#ifdef G_C_STD_VERSION
124# ifdef _MSC_VER
125# if (_MSC_VER < 1900)
126# define G_INLINE_DEFINE_NEEDED
127# endif
128# elif !G_C_STD_CHECK_VERSION (99)
129# define G_INLINE_DEFINE_NEEDED
130# endif
131#endif
132
133#ifdef G_INLINE_DEFINE_NEEDED
134# undef inline
135# define inline __inline
136#endif
137
138#undef G_INLINE_DEFINE_NEEDED
139
140/**
141 * G_INLINE_FUNC:
142 *
143 * This macro used to be used to conditionally define inline functions
144 * in a compatible way before this feature was supported in all
145 * compilers. These days, GLib requires inlining support from the
146 * compiler, so your GLib-using programs can safely assume that the
147 * "inline" keyword works properly.
148 *
149 * Never use this macro anymore. Just say "static inline".
150 *
151 * Deprecated: 2.48: Use "static inline" instead
152 */
153
154/* For historical reasons we need to continue to support those who
155 * define G_IMPLEMENT_INLINES to mean "don't implement this here".
156 */
157#ifdef G_IMPLEMENT_INLINES
158# define G_INLINE_FUNC extern GLIB_DEPRECATED_MACRO_IN_2_48_FOR(static inline)
159# undef G_CAN_INLINE
160#else
161# define G_INLINE_FUNC static inline GLIB_DEPRECATED_MACRO_IN_2_48_FOR(static inline)
162#endif /* G_IMPLEMENT_INLINES */
163
164/*
165 * Attribute support detection. Works on clang and GCC >= 5
166 * https://clang.llvm.org/docs/LanguageExtensions.html#has-attribute
167 * https://gcc.gnu.org/onlinedocs/cpp/_005f_005fhas_005fattribute.html
168 */
169
170#ifdef __has_attribute
171#define g_macro__has_attribute __has_attribute
172#else
173
174/*
175 * Fallback for GCC < 5 and other compilers not supporting __has_attribute.
176 */
177#define g_macro__has_attribute(x) g_macro__has_attribute_##x
178
179#define g_macro__has_attribute___alloc_size__ G_GNUC_CHECK_VERSION (4, 3)
180#define g_macro__has_attribute___always_inline__ G_GNUC_CHECK_VERSION (2, 0)
181#define g_macro__has_attribute___const__ G_GNUC_CHECK_VERSION (2, 4)
182#define g_macro__has_attribute___deprecated__ G_GNUC_CHECK_VERSION (3, 1)
183#define g_macro__has_attribute___format__ G_GNUC_CHECK_VERSION (2, 4)
184#define g_macro__has_attribute___format_arg__ G_GNUC_CHECK_VERSION (2, 4)
185#define g_macro__has_attribute___malloc__ G_GNUC_CHECK_VERSION (2, 96)
186#define g_macro__has_attribute___no_instrument_function__ G_GNUC_CHECK_VERSION (2, 4)
187#define g_macro__has_attribute___noinline__ G_GNUC_CHECK_VERSION (2, 96)
188#define g_macro__has_attribute___noreturn__ (G_GNUC_CHECK_VERSION (2, 8) || (0x5110 <= __SUNPRO_C))
189#define g_macro__has_attribute___pure__ G_GNUC_CHECK_VERSION (2, 96)
190#define g_macro__has_attribute___sentinel__ G_GNUC_CHECK_VERSION (4, 0)
191#define g_macro__has_attribute___unused__ G_GNUC_CHECK_VERSION (2, 4)
192#define g_macro__has_attribute___weak__ G_GNUC_CHECK_VERSION (2, 8)
193#define g_macro__has_attribute_cleanup G_GNUC_CHECK_VERSION (3, 3)
194#define g_macro__has_attribute_fallthrough G_GNUC_CHECK_VERSION (6, 0)
195#define g_macro__has_attribute_may_alias G_GNUC_CHECK_VERSION (3, 3)
196#define g_macro__has_attribute_warn_unused_result G_GNUC_CHECK_VERSION (3, 4)
197#define g_macro__has_attribute_no_sanitize_address 0
198#define g_macro__has_attribute_ifunc 0
199
200#endif
201
202/* Provide macros to feature the GCC function attribute.
203 */
204
205/**
206 * G_GNUC_PURE:
207 *
208 * Expands to the GNU C `pure` function attribute if the compiler is gcc.
209 * Declaring a function as `pure` enables better optimization of calls to
210 * the function. A `pure` function has no effects except its return value
211 * and the return value depends only on the parameters and/or global
212 * variables.
213 *
214 * Place the attribute after the declaration, just before the semicolon.
215 *
216 * |[<!-- language="C" -->
217 * gboolean g_type_check_value (const GValue *value) G_GNUC_PURE;
218 * ]|
219 *
220 * See the [GNU C documentation](https://gcc.gnu.org/onlinedocs/gcc/Common-Function-Attributes.html#index-pure-function-attribute) for more details.
221 */
222
223/**
224 * G_GNUC_MALLOC:
225 *
226 * Expands to the
227 * [GNU C `malloc` function attribute](https://gcc.gnu.org/onlinedocs/gcc/Common-Function-Attributes.html#index-functions-that-behave-like-malloc)
228 * if the compiler is gcc.
229 * Declaring a function as `malloc` enables better optimization of the function,
230 * but must only be done if the allocation behaviour of the function is fully
231 * understood, otherwise miscompilation can result.
232 *
233 * A function can have the `malloc` attribute if it returns a pointer which is
234 * guaranteed to not alias with any other pointer valid when the function
235 * returns, and moreover no pointers to valid objects occur in any storage
236 * addressed by the returned pointer.
237 *
238 * In practice, this means that `G_GNUC_MALLOC` can be used with any function
239 * which returns unallocated or zeroed-out memory, but not with functions which
240 * return initialised structures containing other pointers, or with functions
241 * that reallocate memory. This definition changed in GLib 2.58 to match the
242 * stricter definition introduced around GCC 5.
243 *
244 * Place the attribute after the declaration, just before the semicolon.
245 *
246 * |[<!-- language="C" -->
247 * gpointer g_malloc (gsize n_bytes) G_GNUC_MALLOC G_GNUC_ALLOC_SIZE(1);
248 * ]|
249 *
250 * See the
251 * [GNU C documentation](https://gcc.gnu.org/onlinedocs/gcc/Common-Function-Attributes.html#index-functions-that-behave-like-malloc)
252 * for more details.
253 *
254 * Since: 2.6
255 */
256
257/**
258 * G_GNUC_NO_INLINE:
259 *
260 * Expands to the GNU C `noinline` function attribute if the compiler is gcc.
261 * If the compiler is not gcc, this macro expands to nothing.
262 *
263 * Declaring a function as `noinline` prevents the function from being
264 * considered for inlining.
265 *
266 * This macro is provided for retro-compatibility and will be eventually
267 * deprecated, but %G_NO_INLINE should be used instead.
268 *
269 * The attribute may be placed before the declaration or definition,
270 * right before the `static` keyword.
271 *
272 * |[<!-- language="C" -->
273 * G_GNUC_NO_INLINE
274 * static int
275 * do_not_inline_this (void)
276 * {
277 * ...
278 * }
279 * ]|
280 *
281 * See the
282 * [GNU C documentation](https://gcc.gnu.org/onlinedocs/gcc/Common-Function-Attributes.html#index-noinline-function-attribute)
283 * for more details.
284 *
285 * See also: %G_NO_INLINE, %G_ALWAYS_INLINE.
286 *
287 * Since: 2.58
288 */
289
290#if g_macro__has_attribute(__pure__)
291#define G_GNUC_PURE __attribute__((__pure__))
292#else
293#define G_GNUC_PURE
294#endif
295
296#if g_macro__has_attribute(__malloc__)
297#define G_GNUC_MALLOC __attribute__ ((__malloc__))
298#else
299#define G_GNUC_MALLOC
300#endif
301
302#if g_macro__has_attribute(__noinline__)
303#define G_GNUC_NO_INLINE __attribute__ ((__noinline__)) \
304 GLIB_AVAILABLE_MACRO_IN_2_58
305#else
306#define G_GNUC_NO_INLINE \
307 GLIB_AVAILABLE_MACRO_IN_2_58
308#endif
309
310/**
311 * G_GNUC_NULL_TERMINATED:
312 *
313 * Expands to the GNU C `sentinel` function attribute if the compiler is gcc.
314 * This function attribute only applies to variadic functions and instructs
315 * the compiler to check that the argument list is terminated with an
316 * explicit %NULL.
317 *
318 * Place the attribute after the declaration, just before the semicolon.
319 *
320 * |[<!-- language="C" -->
321 * gchar *g_strconcat (const gchar *string1,
322 * ...) G_GNUC_NULL_TERMINATED;
323 * ]|
324 *
325 * See the [GNU C documentation](https://gcc.gnu.org/onlinedocs/gcc/Common-Function-Attributes.html#index-sentinel-function-attribute) for more details.
326 *
327 * Since: 2.8
328 */
329#if g_macro__has_attribute(__sentinel__)
330#define G_GNUC_NULL_TERMINATED __attribute__((__sentinel__))
331#else
332#define G_GNUC_NULL_TERMINATED
333#endif
334
335/*
336 * Clang feature detection: http://clang.llvm.org/docs/LanguageExtensions.html
337 * These are not available on GCC, but since the pre-processor doesn't do
338 * operator short-circuiting, we can't use it in a statement or we'll get:
339 *
340 * error: missing binary operator before token "("
341 *
342 * So we define it to 0 to satisfy the pre-processor.
343 */
344
345#ifdef __has_feature
346#define g_macro__has_feature __has_feature
347#else
348#define g_macro__has_feature(x) 0
349#endif
350
351#ifdef __has_builtin
352#define g_macro__has_builtin __has_builtin
353#else
354#define g_macro__has_builtin(x) 0
355#endif
356
357#ifdef __has_extension
358#define g_macro__has_extension __has_extension
359#else
360#define g_macro__has_extension(x) 0
361#endif
362
363/**
364 * G_GNUC_ALLOC_SIZE:
365 * @x: the index of the argument specifying the allocation size
366 *
367 * Expands to the GNU C `alloc_size` function attribute if the compiler
368 * is a new enough gcc. This attribute tells the compiler that the
369 * function returns a pointer to memory of a size that is specified
370 * by the @xth function parameter.
371 *
372 * Place the attribute after the function declaration, just before the
373 * semicolon.
374 *
375 * |[<!-- language="C" -->
376 * gpointer g_malloc (gsize n_bytes) G_GNUC_MALLOC G_GNUC_ALLOC_SIZE(1);
377 * ]|
378 *
379 * See the [GNU C documentation](https://gcc.gnu.org/onlinedocs/gcc/Common-Function-Attributes.html#index-alloc_005fsize-function-attribute) for more details.
380 *
381 * Since: 2.18
382 */
383
384/**
385 * G_GNUC_ALLOC_SIZE2:
386 * @x: the index of the argument specifying one factor of the allocation size
387 * @y: the index of the argument specifying the second factor of the allocation size
388 *
389 * Expands to the GNU C `alloc_size` function attribute if the compiler is a
390 * new enough gcc. This attribute tells the compiler that the function returns
391 * a pointer to memory of a size that is specified by the product of two
392 * function parameters.
393 *
394 * Place the attribute after the function declaration, just before the
395 * semicolon.
396 *
397 * |[<!-- language="C" -->
398 * gpointer g_malloc_n (gsize n_blocks,
399 * gsize n_block_bytes) G_GNUC_MALLOC G_GNUC_ALLOC_SIZE2(1, 2);
400 * ]|
401 *
402 * See the [GNU C documentation](https://gcc.gnu.org/onlinedocs/gcc/Common-Function-Attributes.html#index-alloc_005fsize-function-attribute) for more details.
403 *
404 * Since: 2.18
405 */
406#if g_macro__has_attribute(__alloc_size__)
407#define G_GNUC_ALLOC_SIZE(x) __attribute__((__alloc_size__(x)))
408#define G_GNUC_ALLOC_SIZE2(x,y) __attribute__((__alloc_size__(x,y)))
409#else
410#define G_GNUC_ALLOC_SIZE(x)
411#define G_GNUC_ALLOC_SIZE2(x,y)
412#endif
413
414/**
415 * G_GNUC_PRINTF:
416 * @format_idx: the index of the argument corresponding to the
417 * format string (the arguments are numbered from 1)
418 * @arg_idx: the index of the first of the format arguments, or 0 if
419 * there are no format arguments
420 *
421 * Expands to the GNU C `format` function attribute if the compiler is gcc.
422 * This is used for declaring functions which take a variable number of
423 * arguments, with the same syntax as `printf()`. It allows the compiler
424 * to type-check the arguments passed to the function.
425 *
426 * Place the attribute after the function declaration, just before the
427 * semicolon.
428 *
429 * See the
430 * [GNU C documentation](https://gcc.gnu.org/onlinedocs/gcc/Common-Function-Attributes.html#index-Wformat-3288)
431 * for more details.
432 *
433 * |[<!-- language="C" -->
434 * gint g_snprintf (gchar *string,
435 * gulong n,
436 * gchar const *format,
437 * ...) G_GNUC_PRINTF (3, 4);
438 * ]|
439 */
440
441/**
442 * G_GNUC_SCANF:
443 * @format_idx: the index of the argument corresponding to
444 * the format string (the arguments are numbered from 1)
445 * @arg_idx: the index of the first of the format arguments, or 0 if
446 * there are no format arguments
447 *
448 * Expands to the GNU C `format` function attribute if the compiler is gcc.
449 * This is used for declaring functions which take a variable number of
450 * arguments, with the same syntax as `scanf()`. It allows the compiler
451 * to type-check the arguments passed to the function.
452 *
453 * |[<!-- language="C" -->
454 * int my_scanf (MyStream *stream,
455 * const char *format,
456 * ...) G_GNUC_SCANF (2, 3);
457 * int my_vscanf (MyStream *stream,
458 * const char *format,
459 * va_list ap) G_GNUC_SCANF (2, 0);
460 * ]|
461 *
462 * See the
463 * [GNU C documentation](https://gcc.gnu.org/onlinedocs/gcc/Common-Function-Attributes.html#index-Wformat-3288)
464 * for details.
465 */
466
467/**
468 * G_GNUC_STRFTIME:
469 * @format_idx: the index of the argument corresponding to
470 * the format string (the arguments are numbered from 1)
471 *
472 * Expands to the GNU C `strftime` format function attribute if the compiler
473 * is gcc. This is used for declaring functions which take a format argument
474 * which is passed to `strftime()` or an API implementing its formats. It allows
475 * the compiler check the format passed to the function.
476 *
477 * |[<!-- language="C" -->
478 * gsize my_strftime (MyBuffer *buffer,
479 * const char *format,
480 * const struct tm *tm) G_GNUC_STRFTIME (2);
481 * ]|
482 *
483 * See the
484 * [GNU C documentation](https://gcc.gnu.org/onlinedocs/gcc/Common-Function-Attributes.html#index-Wformat-3288)
485 * for details.
486 *
487 * Since: 2.60
488 */
489
490/**
491 * G_GNUC_FORMAT:
492 * @arg_idx: the index of the argument
493 *
494 * Expands to the GNU C `format_arg` function attribute if the compiler
495 * is gcc. This function attribute specifies that a function takes a
496 * format string for a `printf()`, `scanf()`, `strftime()` or `strfmon()` style
497 * function and modifies it, so that the result can be passed to a `printf()`,
498 * `scanf()`, `strftime()` or `strfmon()` style function (with the remaining
499 * arguments to the format function the same as they would have been
500 * for the unmodified string).
501 *
502 * Place the attribute after the function declaration, just before the
503 * semicolon.
504 *
505 * See the [GNU C documentation](https://gcc.gnu.org/onlinedocs/gcc/Common-Function-Attributes.html#index-Wformat-nonliteral-1) for more details.
506 *
507 * |[<!-- language="C" -->
508 * gchar *g_dgettext (gchar *domain_name, gchar *msgid) G_GNUC_FORMAT (2);
509 * ]|
510 */
511
512/**
513 * G_GNUC_NORETURN:
514 *
515 * Expands to the GNU C `noreturn` function attribute if the compiler is gcc.
516 * It is used for declaring functions which never return. It enables
517 * optimization of the function, and avoids possible compiler warnings.
518 *
519 * Since 2.68, it is recommended that code uses %G_NORETURN instead of
520 * %G_GNUC_NORETURN, as that works on more platforms and compilers (in
521 * particular, MSVC and C++11) than %G_GNUC_NORETURN, which works with GCC and
522 * Clang only. %G_GNUC_NORETURN continues to work, so has not been deprecated
523 * yet.
524 *
525 * Place the attribute after the declaration, just before the semicolon.
526 *
527 * |[<!-- language="C" -->
528 * void g_abort (void) G_GNUC_NORETURN;
529 * ]|
530 *
531 * See the [GNU C documentation](https://gcc.gnu.org/onlinedocs/gcc/Common-Function-Attributes.html#index-noreturn-function-attribute) for more details.
532 */
533
534/**
535 * G_GNUC_CONST:
536 *
537 * Expands to the GNU C `const` function attribute if the compiler is gcc.
538 * Declaring a function as `const` enables better optimization of calls to
539 * the function. A `const` function doesn't examine any values except its
540 * parameters, and has no effects except its return value.
541 *
542 * Place the attribute after the declaration, just before the semicolon.
543 *
544 * |[<!-- language="C" -->
545 * gchar g_ascii_tolower (gchar c) G_GNUC_CONST;
546 * ]|
547 *
548 * See the [GNU C documentation](https://gcc.gnu.org/onlinedocs/gcc/Common-Function-Attributes.html#index-const-function-attribute) for more details.
549 *
550 * A function that has pointer arguments and examines the data pointed to
551 * must not be declared `const`. Likewise, a function that calls a non-`const`
552 * function usually must not be `const`. It doesn't make sense for a `const`
553 * function to return `void`.
554 */
555
556/**
557 * G_GNUC_UNUSED:
558 *
559 * Expands to the GNU C `unused` function attribute if the compiler is gcc.
560 * It is used for declaring functions and arguments which may never be used.
561 * It avoids possible compiler warnings.
562 *
563 * For functions, place the attribute after the declaration, just before the
564 * semicolon. For arguments, place the attribute at the beginning of the
565 * argument declaration.
566 *
567 * |[<!-- language="C" -->
568 * void my_unused_function (G_GNUC_UNUSED gint unused_argument,
569 * gint other_argument) G_GNUC_UNUSED;
570 * ]|
571 *
572 * See the [GNU C documentation](https://gcc.gnu.org/onlinedocs/gcc/Common-Function-Attributes.html#index-unused-function-attribute) for more details.
573 */
574
575/**
576 * G_GNUC_NO_INSTRUMENT:
577 *
578 * Expands to the GNU C `no_instrument_function` function attribute if the
579 * compiler is gcc. Functions with this attribute will not be instrumented
580 * for profiling, when the compiler is called with the
581 * `-finstrument-functions` option.
582 *
583 * Place the attribute after the declaration, just before the semicolon.
584 *
585 * |[<!-- language="C" -->
586 * int do_uninteresting_things (void) G_GNUC_NO_INSTRUMENT;
587 * ]|
588 *
589 * See the [GNU C documentation](https://gcc.gnu.org/onlinedocs/gcc/Common-Function-Attributes.html#index-no_005finstrument_005ffunction-function-attribute) for more details.
590 */
591
592#if g_macro__has_attribute(__format__)
593
594#if !defined (__clang__) && G_GNUC_CHECK_VERSION (4, 4)
595#define G_GNUC_PRINTF( format_idx, arg_idx ) \
596 __attribute__((__format__ (gnu_printf, format_idx, arg_idx)))
597#define G_GNUC_SCANF( format_idx, arg_idx ) \
598 __attribute__((__format__ (gnu_scanf, format_idx, arg_idx)))
599#define G_GNUC_STRFTIME( format_idx ) \
600 __attribute__((__format__ (gnu_strftime, format_idx, 0))) \
601 GLIB_AVAILABLE_MACRO_IN_2_60
602#else
603#define G_GNUC_PRINTF( format_idx, arg_idx ) \
604 __attribute__((__format__ (__printf__, format_idx, arg_idx)))
605#define G_GNUC_SCANF( format_idx, arg_idx ) \
606 __attribute__((__format__ (__scanf__, format_idx, arg_idx)))
607#define G_GNUC_STRFTIME( format_idx ) \
608 __attribute__((__format__ (__strftime__, format_idx, 0))) \
609 GLIB_AVAILABLE_MACRO_IN_2_60
610#endif
611
612#else
613
614#define G_GNUC_PRINTF( format_idx, arg_idx )
615#define G_GNUC_SCANF( format_idx, arg_idx )
616#define G_GNUC_STRFTIME( format_idx ) \
617 GLIB_AVAILABLE_MACRO_IN_2_60
618
619#endif
620
621#if g_macro__has_attribute(__format_arg__)
622#define G_GNUC_FORMAT(arg_idx) \
623 __attribute__ ((__format_arg__ (arg_idx)))
624#else
625#define G_GNUC_FORMAT( arg_idx )
626#endif
627
628#if g_macro__has_attribute(__noreturn__)
629#define G_GNUC_NORETURN \
630 __attribute__ ((__noreturn__))
631#else
632/* NOTE: MSVC has __declspec(noreturn) but unlike GCC __attribute__,
633 * __declspec can only be placed at the start of the function prototype
634 * and not at the end, so we can't use it without breaking API.
635 */
636#define G_GNUC_NORETURN
637#endif
638
639#if g_macro__has_attribute(__const__)
640#define G_GNUC_CONST \
641 __attribute__ ((__const__))
642#else
643#define G_GNUC_CONST
644#endif
645
646#if g_macro__has_attribute(__unused__)
647#define G_GNUC_UNUSED \
648 __attribute__ ((__unused__))
649#else
650#define G_GNUC_UNUSED
651#endif
652
653#if g_macro__has_attribute(__no_instrument_function__)
654#define G_GNUC_NO_INSTRUMENT \
655 __attribute__ ((__no_instrument_function__))
656#else
657#define G_GNUC_NO_INSTRUMENT
658#endif
659
660/**
661 * G_GNUC_FALLTHROUGH:
662 *
663 * Expands to the GNU C `fallthrough` statement attribute if the compiler supports it.
664 * This allows declaring case statement to explicitly fall through in switch
665 * statements. To enable this feature, use `-Wimplicit-fallthrough` during
666 * compilation.
667 *
668 * Put the attribute right before the case statement you want to fall through
669 * to.
670 *
671 * |[<!-- language="C" -->
672 * switch (foo)
673 * {
674 * case 1:
675 * g_message ("it's 1");
676 * G_GNUC_FALLTHROUGH;
677 * case 2:
678 * g_message ("it's either 1 or 2");
679 * break;
680 * }
681 * ]|
682 *
683 *
684 * See the [GNU C documentation](https://gcc.gnu.org/onlinedocs/gcc/Statement-Attributes.html#index-fallthrough-statement-attribute) for more details.
685 *
686 * Since: 2.60
687 */
688#if g_macro__has_attribute(fallthrough)
689#define G_GNUC_FALLTHROUGH __attribute__((fallthrough)) \
690 GLIB_AVAILABLE_MACRO_IN_2_60
691#else
692#define G_GNUC_FALLTHROUGH \
693 GLIB_AVAILABLE_MACRO_IN_2_60
694#endif
695
696/**
697 * G_GNUC_DEPRECATED:
698 *
699 * Expands to the GNU C `deprecated` attribute if the compiler is gcc.
700 * It can be used to mark `typedef`s, variables and functions as deprecated.
701 * When called with the `-Wdeprecated-declarations` option,
702 * gcc will generate warnings when deprecated interfaces are used.
703 *
704 * Place the attribute after the declaration, just before the semicolon.
705 *
706 * |[<!-- language="C" -->
707 * int my_mistake (void) G_GNUC_DEPRECATED;
708 * ]|
709 *
710 * See the [GNU C documentation](https://gcc.gnu.org/onlinedocs/gcc/Common-Function-Attributes.html#index-deprecated-function-attribute) for more details.
711 *
712 * Since: 2.2
713 */
714#if g_macro__has_attribute(__deprecated__)
715#define G_GNUC_DEPRECATED __attribute__((__deprecated__))
716#else
717#define G_GNUC_DEPRECATED
718#endif /* __GNUC__ */
719
720/**
721 * G_GNUC_DEPRECATED_FOR:
722 * @f: the intended replacement for the deprecated symbol,
723 * such as the name of a function
724 *
725 * Like %G_GNUC_DEPRECATED, but names the intended replacement for the
726 * deprecated symbol if the version of gcc in use is new enough to support
727 * custom deprecation messages.
728 *
729 * Place the attribute after the declaration, just before the semicolon.
730 *
731 * |[<!-- language="C" -->
732 * int my_mistake (void) G_GNUC_DEPRECATED_FOR(my_replacement);
733 * ]|
734 *
735 * See the [GNU C documentation](https://gcc.gnu.org/onlinedocs/gcc/Common-Function-Attributes.html#index-deprecated-function-attribute) for more details.
736 *
737 * Note that if @f is a macro, it will be expanded in the warning message.
738 * You can enclose it in quotes to prevent this. (The quotes will show up
739 * in the warning, but it's better than showing the macro expansion.)
740 *
741 * Since: 2.26
742 */
743#if G_GNUC_CHECK_VERSION(4, 5) || defined(__clang__)
744#define G_GNUC_DEPRECATED_FOR(f) \
745 __attribute__((deprecated("Use " #f " instead"))) \
746 GLIB_AVAILABLE_MACRO_IN_2_26
747#else
748#define G_GNUC_DEPRECATED_FOR(f) G_GNUC_DEPRECATED \
749 GLIB_AVAILABLE_MACRO_IN_2_26
750#endif /* __GNUC__ */
751
752#ifdef __ICC
753#define G_GNUC_BEGIN_IGNORE_DEPRECATIONS \
754 _Pragma ("warning (push)") \
755 _Pragma ("warning (disable:1478)")
756#define G_GNUC_END_IGNORE_DEPRECATIONS \
757 _Pragma ("warning (pop)")
758#elif G_GNUC_CHECK_VERSION(4, 6)
759#define G_GNUC_BEGIN_IGNORE_DEPRECATIONS \
760 _Pragma ("GCC diagnostic push") \
761 _Pragma ("GCC diagnostic ignored \"-Wdeprecated-declarations\"")
762#define G_GNUC_END_IGNORE_DEPRECATIONS \
763 _Pragma ("GCC diagnostic pop")
764#elif defined (_MSC_VER) && (_MSC_VER >= 1500) && !defined (__clang__)
765#define G_GNUC_BEGIN_IGNORE_DEPRECATIONS \
766 __pragma (warning (push)) \
767 __pragma (warning (disable : 4996))
768#define G_GNUC_END_IGNORE_DEPRECATIONS \
769 __pragma (warning (pop))
770#elif defined (__clang__)
771#define G_GNUC_BEGIN_IGNORE_DEPRECATIONS \
772 _Pragma("clang diagnostic push") \
773 _Pragma("clang diagnostic ignored \"-Wdeprecated-declarations\"")
774#define G_GNUC_END_IGNORE_DEPRECATIONS \
775 _Pragma("clang diagnostic pop")
776#else
777#define G_GNUC_BEGIN_IGNORE_DEPRECATIONS
778#define G_GNUC_END_IGNORE_DEPRECATIONS
779#define GLIB_CANNOT_IGNORE_DEPRECATIONS
780#endif
781
782/**
783 * G_GNUC_FLAG_ENUM:
784 *
785 * Expands to the GNU C `flag_enum` attribute if the compiler is gcc or clang.
786 * This attribute indicates that an enumerated type is used in bitwise
787 * operations.
788 * It is sometimes used in static analysis.
789 *
790 * See the
791 * [GNU C documentation](https://gcc.gnu.org/onlinedocs/gcc/Common-Type-Attributes.html#index-flag_005fenum-type-attribute)
792 * for details.
793 *
794 * |[<!-- language="C" -->
795 * typedef enum {
796 * G_KEY_FILE_NONE = 0,
797 * G_KEY_FILE_KEEP_COMMENTS = 1 << 0,
798 * G_KEY_FILE_KEEP_TRANSLATIONS = 1 << 1
799 * } G_GNUC_FLAG_ENUM GKeyFileFlags;
800 * ]|
801 *
802 * (The attribute can also be placed after `enum` and before the opening brace,
803 * but that may cause it to be misinterpreted as the name of the enum if the
804 * macro is not defined.)
805 *
806 * Since: 2.88
807 */
808#if g_macro__has_attribute(flag_enum)
809#define G_GNUC_FLAG_ENUM __attribute__((flag_enum))
810#else
811#define G_GNUC_FLAG_ENUM
812#endif
813
814/**
815 * G_GNUC_MAY_ALIAS:
816 *
817 * Expands to the GNU C `may_alias` type attribute if the compiler is gcc.
818 * Types with this attribute will not be subjected to type-based alias
819 * analysis, but are assumed to alias with any other type, just like `char`.
820 *
821 * See the [GNU C documentation](https://gcc.gnu.org/onlinedocs/gcc/Common-Type-Attributes.html#index-may_005falias-type-attribute) for details.
822 *
823 * Since: 2.14
824 */
825#if g_macro__has_attribute(may_alias)
826#define G_GNUC_MAY_ALIAS __attribute__((may_alias))
827#else
828#define G_GNUC_MAY_ALIAS
829#endif
830
831/**
832 * G_GNUC_WARN_UNUSED_RESULT:
833 *
834 * Expands to the GNU C `warn_unused_result` function attribute if the compiler
835 * is gcc. This function attribute makes the compiler emit a warning if the
836 * result of a function call is ignored.
837 *
838 * Place the attribute after the declaration, just before the semicolon.
839 *
840 * |[<!-- language="C" -->
841 * GList *g_list_append (GList *list,
842 * gpointer data) G_GNUC_WARN_UNUSED_RESULT;
843 * ]|
844 *
845 * See the [GNU C documentation](https://gcc.gnu.org/onlinedocs/gcc/Common-Function-Attributes.html#index-warn_005funused_005fresult-function-attribute) for more details.
846 *
847 * Since: 2.10
848 */
849#if g_macro__has_attribute(warn_unused_result)
850#define G_GNUC_WARN_UNUSED_RESULT __attribute__((warn_unused_result))
851#else
852#define G_GNUC_WARN_UNUSED_RESULT
853#endif /* __GNUC__ */
854
855/**
856 * G_GNUC_FUNCTION:
857 *
858 * Expands to "" on all modern compilers, and to __FUNCTION__ on gcc
859 * version 2.x. Don't use it.
860 *
861 * Deprecated: 2.16: Use G_STRFUNC() instead
862 */
863
864/**
865 * G_GNUC_PRETTY_FUNCTION:
866 *
867 * Expands to "" on all modern compilers, and to __PRETTY_FUNCTION__
868 * on gcc version 2.x. Don't use it.
869 *
870 * Deprecated: 2.16: Use G_STRFUNC() instead
871 */
872
873/* Wrap the gcc __PRETTY_FUNCTION__ and __FUNCTION__ variables with
874 * macros, so we can refer to them as strings unconditionally.
875 * usage not-recommended since gcc-3.0
876 *
877 * Mark them as deprecated since 2.26, since that’s when version macros were
878 * introduced.
879 */
880#if defined (__GNUC__) && (__GNUC__ < 3)
881#define G_GNUC_FUNCTION __FUNCTION__ GLIB_DEPRECATED_MACRO_IN_2_26_FOR(G_STRFUNC)
882#define G_GNUC_PRETTY_FUNCTION __PRETTY_FUNCTION__ GLIB_DEPRECATED_MACRO_IN_2_26_FOR(G_STRFUNC)
883#else /* !__GNUC__ */
884#define G_GNUC_FUNCTION "" GLIB_DEPRECATED_MACRO_IN_2_26_FOR(G_STRFUNC)
885#define G_GNUC_PRETTY_FUNCTION "" GLIB_DEPRECATED_MACRO_IN_2_26_FOR(G_STRFUNC)
886#endif /* !__GNUC__ */
887
888#if g_macro__has_feature(attribute_analyzer_noreturn) && defined(__clang_analyzer__)
889#define G_ANALYZER_ANALYZING 1
890#define G_ANALYZER_NORETURN __attribute__((analyzer_noreturn))
891#elif defined(__COVERITY__)
892#define G_ANALYZER_ANALYZING 1
893#define G_ANALYZER_NORETURN __attribute__((noreturn))
894#else
895#define G_ANALYZER_ANALYZING 0
896#define G_ANALYZER_NORETURN
897#endif
898
899#define G_STRINGIFY(macro_or_string) G_STRINGIFY_ARG (macro_or_string)
900#define G_STRINGIFY_ARG(contents) #contents
901
902#define G_PASTE_ARGS(identifier1,identifier2) identifier1 ## identifier2
903#define G_PASTE(identifier1,identifier2) G_PASTE_ARGS (identifier1, identifier2)
904
905#ifndef __GI_SCANNER__ /* The static assert macro really confuses the introspection parser */
906#if G_CXX_STD_CHECK_VERSION (11)
907#define G_STATIC_ASSERT(expr) static_assert (expr, "Expression evaluates to false")
908#elif (G_C_STD_CHECK_VERSION (11) || \
909 g_macro__has_feature(c_static_assert) || g_macro__has_extension(c_static_assert))
910#define G_STATIC_ASSERT(expr) _Static_assert (expr, "Expression evaluates to false")
911#else
912#ifdef __COUNTER__
913#define G_STATIC_ASSERT(expr) typedef char G_PASTE (_GStaticAssertCompileTimeAssertion_, __COUNTER__)[(expr) ? 1 : -1] G_GNUC_UNUSED
914#else
915#define G_STATIC_ASSERT(expr) typedef char G_PASTE (_GStaticAssertCompileTimeAssertion_, __LINE__)[(expr) ? 1 : -1] G_GNUC_UNUSED
916#endif
917#endif /* G_CXX_STD_CHECK_VERSION (11) */
918#define G_STATIC_ASSERT_EXPR(expr) ((void) sizeof (char[(expr) ? 1 : -1]))
919#else /* __GI_SCANNER__ */
920#define G_STATIC_ASSERT(expr) static int G_PASTE (_GStaticAssertGiScannerNoop, __LINE__) G_GNUC_UNUSED
921#define G_STATIC_ASSERT_EXPR(expr) static int G_PASTE (_GStaticAssertGiScannerNoop, __LINE__) G_GNUC_UNUSED
922#endif /* __GI_SCANNER__ */
923
924/* Provide a string identifying the current code position */
925#if defined (__GNUC__) && (__GNUC__ < 3) && !defined (G_CXX_STD_VERSION)
926#define G_STRLOC __FILE__ ":" G_STRINGIFY (__LINE__) ":" __PRETTY_FUNCTION__ "()"
927#else
928#define G_STRLOC __FILE__ ":" G_STRINGIFY (__LINE__)
929#endif
930
931/* Provide a string identifying the current function, non-concatenatable */
932#if defined (__GNUC__) && defined (G_CXX_STD_VERSION)
933#define G_STRFUNC ((const char*) (__PRETTY_FUNCTION__))
934#elif G_C_STD_CHECK_VERSION (99)
935#define G_STRFUNC ((const char*) (__func__))
936#elif defined (__GNUC__) || (defined(_MSC_VER) && (_MSC_VER > 1300))
937#define G_STRFUNC ((const char*) (__FUNCTION__))
938#else
939#define G_STRFUNC ((const char*) ("???"))
940#endif
941
942/* Guard C code in headers, while including them from C++ */
943#ifdef G_CXX_STD_VERSION
944#define G_BEGIN_DECLS extern "C" {
945#define G_END_DECLS }
946#else
947#define G_BEGIN_DECLS
948#define G_END_DECLS
949#endif
950
951/* Provide definitions for some commonly used macros.
952 * Some of them are only provided if they haven't already
953 * been defined. It is assumed that if they are already
954 * defined then the current definition is correct.
955 */
956#ifndef NULL
957# if G_CXX_STD_CHECK_VERSION (11)
958# define NULL (nullptr)
959# elif defined (G_CXX_STD_VERSION)
960# define NULL (0L)
961# else
962# define NULL ((void*) 0)
963# endif /* G_CXX_STD_CHECK_VERSION (11) */
964#endif
965
966#ifndef FALSE
967#define FALSE (0)
968#endif
969
970#ifndef TRUE
971#define TRUE (!FALSE)
972#endif
973
974#undef MAX
975#define MAX(a, b) (((a) > (b)) ? (a) : (b))
976
977#undef MIN
978#define MIN(a, b) (((a) < (b)) ? (a) : (b))
979
980#undef ABS
981#define ABS(a) (((a) < 0) ? -(a) : (a))
982
983#undef CLAMP
984#define CLAMP(x, low, high) (((x) > (high)) ? (high) : (((x) < (low)) ? (low) : (x)))
985
986#define G_APPROX_VALUE(a, b, epsilon) \
987 (((a) > (b) ? (a) - (b) : (b) - (a)) < (epsilon))
988
989/* Count the number of elements in an array. The array must be defined
990 * as such; using this with a dynamically allocated array will give
991 * incorrect results.
992 */
993#define G_N_ELEMENTS(arr) (sizeof (arr) / sizeof ((arr)[0]))
994
995/* Macros by analogy to GINT_TO_POINTER, GPOINTER_TO_INT
996 */
997#define GPOINTER_TO_SIZE(p) ((gsize) (p))
998#define GSIZE_TO_POINTER(s) ((gpointer) (guintptr) (gsize) (s))
999
1000/* Provide convenience macros for handling structure
1001 * fields through their offsets.
1002 */
1003
1004#if G_GNUC_CHECK_VERSION(4, 0) || defined(_MSC_VER)
1005#define G_STRUCT_OFFSET(struct_type, member) \
1006 ((glong) offsetof (struct_type, member))
1007#else
1008#define G_STRUCT_OFFSET(struct_type, member) \
1009 ((glong) ((guint8*) &((struct_type*) 0)->member))
1010#endif
1011
1012#define G_STRUCT_MEMBER_P(struct_p, struct_offset) \
1013 ((gpointer) ((guint8*) (struct_p) + (glong) (struct_offset)))
1014#define G_STRUCT_MEMBER(member_type, struct_p, struct_offset) \
1015 (*(member_type*) G_STRUCT_MEMBER_P ((struct_p), (struct_offset)))
1016
1017/* Provide simple macro statement wrappers:
1018 * G_STMT_START { statements; } G_STMT_END;
1019 * This can be used as a single statement, like:
1020 * if (x) G_STMT_START { ... } G_STMT_END; else ...
1021 * This intentionally does not use compiler extensions like GCC's '({...})' to
1022 * avoid portability issue or side effects when compiled with different compilers.
1023 * MSVC complains about "while(0)": C4127: "Conditional expression is constant",
1024 * so we use __pragma to avoid the warning since the use here is intentional.
1025 */
1026#if !(defined (G_STMT_START) && defined (G_STMT_END))
1027#define G_STMT_START do
1028#if defined (_MSC_VER) && (_MSC_VER >= 1500)
1029#define G_STMT_END \
1030 __pragma(warning(push)) \
1031 __pragma(warning(disable:4127)) \
1032 while(0) \
1033 __pragma(warning(pop))
1034#else
1035#define G_STMT_END while (0)
1036#endif
1037#endif
1038
1039/* Provide G_ALIGNOF alignment macro.
1040 *
1041 * Note we cannot use the gcc __alignof__ operator here, as that returns the
1042 * preferred alignment rather than the minimal alignment. See
1043 * https://gitlab.gnome.org/GNOME/glib/merge_requests/538/diffs#note_390790.
1044 */
1045
1046/**
1047 * G_ALIGNOF
1048 * @type: a type-name
1049 *
1050 * Return the minimal alignment required by the platform ABI for values of the given
1051 * type. The address of a variable or struct member of the given type must always be
1052 * a multiple of this alignment. For example, most platforms require int variables
1053 * to be aligned at a 4-byte boundary, so `G_ALIGNOF (int)` is 4 on most platforms.
1054 *
1055 * Note this is not necessarily the same as the value returned by GCC’s
1056 * `__alignof__` operator, which returns the preferred alignment for a type.
1057 * The preferred alignment may be a stricter alignment than the minimal
1058 * alignment.
1059 *
1060 * Since: 2.60
1061 */
1062#if G_C_STD_CHECK_VERSION (11)
1063#define G_ALIGNOF(type) _Alignof (type) \
1064 GLIB_AVAILABLE_MACRO_IN_2_60
1065#else
1066#define G_ALIGNOF(type) (G_STRUCT_OFFSET (struct { char a; type b; }, b)) \
1067 GLIB_AVAILABLE_MACRO_IN_2_60
1068#endif
1069
1070/**
1071 * G_CONST_RETURN:
1072 *
1073 * If %G_DISABLE_CONST_RETURNS is defined, this macro expands
1074 * to nothing. By default, the macro expands to const. The macro
1075 * can be used in place of const for functions that return a value
1076 * that should not be modified. The purpose of this macro is to allow
1077 * us to turn on const for returned constant strings by default, while
1078 * allowing programmers who find that annoying to turn it off. This macro
1079 * should only be used for return values and for "out" parameters, it
1080 * doesn't make sense for "in" parameters.
1081 *
1082 * Deprecated: 2.30: API providers should replace all existing uses with
1083 * const and API consumers should adjust their code accordingly
1084 */
1085#ifdef G_DISABLE_CONST_RETURNS
1086#define G_CONST_RETURN GLIB_DEPRECATED_MACRO_IN_2_30_FOR(const)
1087#else
1088#define G_CONST_RETURN const GLIB_DEPRECATED_MACRO_IN_2_30_FOR(const)
1089#endif
1090
1091/**
1092 * G_NORETURN:
1093 *
1094 * Expands to the GNU C or MSVC `noreturn` function attribute depending on
1095 * the compiler. It is used for declaring functions which never return.
1096 * Enables optimization of the function, and avoids possible compiler warnings.
1097 *
1098 * Note that %G_NORETURN supersedes the previous %G_GNUC_NORETURN macro, which
1099 * will eventually be deprecated. %G_NORETURN supports more platforms.
1100 *
1101 * Place the attribute before the function declaration as follows:
1102 *
1103 * |[<!-- language="C" -->
1104 * G_NORETURN void g_abort (void);
1105 * ]|
1106 *
1107 * Since: 2.68
1108 */
1109/* Note: We can’t annotate this with GLIB_AVAILABLE_MACRO_IN_2_68 because it’s
1110 * used within the GLib headers in function declarations which are always
1111 * evaluated when a header is included. This results in warnings in third party
1112 * code which includes glib.h, even if the third party code doesn’t use the new
1113 * macro itself. */
1114#if G_CXX_STD_CHECK_VERSION (11)
1115 /* Use ISO C++11 syntax when the compiler supports it. */
1116# define G_NORETURN [[noreturn]]
1117#elif g_macro__has_attribute(__noreturn__)
1118 /* For compatibility with G_NORETURN_FUNCPTR on clang, use
1119 __attribute__((__noreturn__)), not _Noreturn. */
1120# define G_NORETURN __attribute__ ((__noreturn__))
1121#elif defined (_MSC_VER) && (1200 <= _MSC_VER)
1122 /* Use MSVC specific syntax. */
1123# define G_NORETURN __declspec (noreturn)
1124 /* Use ISO C11 syntax when the compiler supports it. */
1125#elif G_C_STD_CHECK_VERSION (11)
1126# define G_NORETURN _Noreturn
1127#else
1128# define G_NORETURN /* empty */
1129#endif
1130
1131/**
1132 * G_NORETURN_FUNCPTR:
1133 *
1134 * Expands to the GNU C or MSVC `noreturn` function attribute depending on
1135 * the compiler. It is used for declaring function pointers which never return.
1136 * Enables optimization of the function, and avoids possible compiler warnings.
1137 *
1138 * Place the attribute before the function declaration as follows:
1139 *
1140 * |[<!-- language="C" -->
1141 * G_NORETURN_FUNCPTR void (*funcptr) (void);
1142 * ]|
1143 *
1144 * Note that if the function is not a function pointer, you can simply use
1145 * the %G_NORETURN macro as follows:
1146 *
1147 * |[<!-- language="C" -->
1148 * G_NORETURN void g_abort (void);
1149 * ]|
1150 *
1151 * Since: 2.68
1152 */
1153#if g_macro__has_attribute(__noreturn__)
1154# define G_NORETURN_FUNCPTR __attribute__ ((__noreturn__)) \
1155 GLIB_AVAILABLE_MACRO_IN_2_68
1156#else
1157# define G_NORETURN_FUNCPTR /* empty */ \
1158 GLIB_AVAILABLE_MACRO_IN_2_68
1159#endif
1160
1161/**
1162 * G_ALWAYS_INLINE:
1163 *
1164 * Expands to the GNU C `always_inline` or MSVC `__forceinline` function
1165 * attribute depending on the compiler. It is used for declaring functions
1166 * as always inlined, ignoring the compiler optimization levels.
1167 *
1168 * The attribute may be placed before the declaration or definition,
1169 * right before the `static` keyword.
1170 *
1171 * |[<!-- language="C" -->
1172 * G_ALWAYS_INLINE
1173 * static int
1174 * do_inline_this (void)
1175 * {
1176 * ...
1177 * }
1178 * ]|
1179 *
1180 * See the
1181 * [GNU C documentation](https://gcc.gnu.org/onlinedocs/gcc/Common-Function-Attributes.html#index-always_005finline-function-attribute)
1182 * and the
1183 * [MSVC documentation](https://docs.microsoft.com/en-us/visualstudio/misc/inline-inline-forceinline)
1184 *
1185 * Since: 2.74
1186 */
1187/* Note: We can’t annotate this with GLIB_AVAILABLE_MACRO_IN_2_74 because it’s
1188 * used within the GLib headers in function declarations which are always
1189 * evaluated when a header is included. This results in warnings in third party
1190 * code which includes glib.h, even if the third party code doesn’t use the new
1191 * macro itself. */
1192#if g_macro__has_attribute(__always_inline__)
1193# if G_CXX_STD_CHECK_VERSION (11)
1194 /* Use ISO C++11 syntax when the compiler supports it. */
1195# define G_ALWAYS_INLINE [[gnu::always_inline]]
1196# else
1197# define G_ALWAYS_INLINE __attribute__ ((__always_inline__))
1198# endif
1199#elif defined (_MSC_VER)
1200 /* Use MSVC specific syntax. */
1201# if G_CXX_STD_CHECK_VERSION (20) && _MSC_VER >= 1927
1202# define G_ALWAYS_INLINE [[msvc::forceinline]]
1203# else
1204# define G_ALWAYS_INLINE __forceinline
1205# endif
1206#else
1207# define G_ALWAYS_INLINE /* empty */
1208#endif
1209
1210/**
1211 * G_NO_INLINE:
1212 *
1213 * Expands to the GNU C or MSVC `noinline` function attribute
1214 * depending on the compiler. It is used for declaring functions
1215 * preventing from being considered for inlining.
1216 *
1217 * Note that %G_NO_INLINE supersedes the previous %G_GNUC_NO_INLINE
1218 * macro, which will eventually be deprecated.
1219 * %G_NO_INLINE supports more platforms.
1220 *
1221 * The attribute may be placed before the declaration or definition,
1222 * right before the `static` keyword.
1223 *
1224 * |[<!-- language="C" -->
1225 * G_NO_INLINE
1226 * static int
1227 * do_not_inline_this (void)
1228 * {
1229 * ...
1230 * }
1231 * ]|
1232 *
1233 * Since: 2.74
1234 */
1235/* Note: We can’t annotate this with GLIB_AVAILABLE_MACRO_IN_2_74 because it’s
1236 * used within the GLib headers in function declarations which are always
1237 * evaluated when a header is included. This results in warnings in third party
1238 * code which includes glib.h, even if the third party code doesn’t use the new
1239 * macro itself. */
1240#if g_macro__has_attribute(__noinline__)
1241# if G_CXX_STD_CHECK_VERSION (11)
1242 /* Use ISO C++11 syntax when the compiler supports it. */
1243# if defined (__GNUC__)
1244# define G_NO_INLINE [[gnu::noinline]]
1245# elif defined (_MSC_VER)
1246# if G_CXX_STD_CHECK_VERSION (20) && _MSC_VER >= 1927
1247# define G_NO_INLINE [[msvc::noinline]]
1248# else
1249# define G_NO_INLINE __declspec (noinline)
1250# endif
1251# endif
1252# else
1253# define G_NO_INLINE __attribute__ ((__noinline__))
1254# endif
1255#elif defined (_MSC_VER) && (1200 <= _MSC_VER)
1256 /* Use MSVC specific syntax. */
1257 /* Use ISO C++11 syntax when the compiler supports it. */
1258# if G_CXX_STD_CHECK_VERSION (20) && _MSC_VER >= 1927
1259# define G_NO_INLINE [[msvc::noinline]]
1260# else
1261# define G_NO_INLINE __declspec (noinline)
1262# endif
1263#else
1264# define G_NO_INLINE /* empty */
1265#endif
1266
1267/*
1268 * The G_LIKELY and G_UNLIKELY macros let the programmer give hints to
1269 * the compiler about the expected result of an expression. Some compilers
1270 * can use this information for optimizations.
1271 *
1272 * The _G_BOOLEAN_EXPR macro is intended to trigger a gcc warning when
1273 * putting assignments in g_return_if_fail ().
1274 */
1275#if G_GNUC_CHECK_VERSION(2, 0) && defined(__OPTIMIZE__)
1276#define _G_BOOLEAN_EXPR_IMPL(uniq, expr) \
1277 G_GNUC_EXTENSION ({ \
1278 int G_PASTE (_g_boolean_var_, uniq) = 0; \
1279 if (expr) \
1280 G_PASTE (_g_boolean_var_, uniq) = 1; \
1281 G_PASTE (_g_boolean_var_, uniq); \
1282})
1283#define _G_BOOLEAN_EXPR(expr) _G_BOOLEAN_EXPR_IMPL (__COUNTER__, expr)
1284#define G_LIKELY(expr) (__builtin_expect (_G_BOOLEAN_EXPR(expr), 1))
1285#define G_UNLIKELY(expr) (__builtin_expect (_G_BOOLEAN_EXPR(expr), 0))
1286#else
1287#define G_LIKELY(expr) (expr)
1288#define G_UNLIKELY(expr) (expr)
1289#endif
1290
1291#if __GNUC__ >= 4 && !defined(_WIN32) && !defined(__CYGWIN__)
1292#define G_HAVE_GNUC_VISIBILITY 1
1293#endif
1294
1295/* GLIB_CANNOT_IGNORE_DEPRECATIONS is defined above for compilers that do not
1296 * have a way to temporarily suppress deprecation warnings. In these cases,
1297 * suppress the deprecated attribute altogether (otherwise a simple #include
1298 * <glib.h> will emit a barrage of warnings).
1299 */
1300#if defined(GLIB_CANNOT_IGNORE_DEPRECATIONS)
1301#define G_DEPRECATED
1302#elif G_GNUC_CHECK_VERSION(3, 1) || defined(__clang__)
1303#define G_DEPRECATED __attribute__((__deprecated__))
1304#elif defined(_MSC_VER) && (_MSC_VER >= 1300)
1305#define G_DEPRECATED __declspec(deprecated)
1306#else
1307#define G_DEPRECATED
1308#endif
1309
1310#if defined(GLIB_CANNOT_IGNORE_DEPRECATIONS)
1311#define G_DEPRECATED_FOR(f) G_DEPRECATED
1312#elif G_GNUC_CHECK_VERSION(4, 5) || defined(__clang__)
1313#define G_DEPRECATED_FOR(f) __attribute__((__deprecated__("Use '" #f "' instead")))
1314#elif defined(_MSC_FULL_VER) && (_MSC_FULL_VER > 140050320)
1315#define G_DEPRECATED_FOR(f) __declspec(deprecated("is deprecated. Use '" #f "' instead"))
1316#else
1317#define G_DEPRECATED_FOR(f) G_DEPRECATED
1318#endif
1319
1320#if G_GNUC_CHECK_VERSION(4, 5) || defined(__clang__)
1321#define G_UNAVAILABLE(maj,min) __attribute__((deprecated("Not available before " #maj "." #min)))
1322#elif defined(_MSC_FULL_VER) && (_MSC_FULL_VER > 140050320)
1323#define G_UNAVAILABLE(maj,min) __declspec(deprecated("is not available before " #maj "." #min))
1324#else
1325#define G_UNAVAILABLE(maj,min) G_DEPRECATED
1326#endif
1327
1328/* These macros are used to mark deprecated symbols in GLib headers,
1329 * and thus have to be exposed in installed headers. But please
1330 * do *not* use them in other projects. Instead, use G_DEPRECATED
1331 * or define your own wrappers around it.
1332 */
1333
1334#if !defined(GLIB_DISABLE_DEPRECATION_WARNINGS) && \
1335 (G_GNUC_CHECK_VERSION(4, 6) || \
1336 __clang_major__ > 3 || (__clang_major__ == 3 && __clang_minor__ >= 4))
1337#define _GLIB_GNUC_DO_PRAGMA(x) _Pragma(G_STRINGIFY (x))
1338#define GLIB_DEPRECATED_MACRO _GLIB_GNUC_DO_PRAGMA(GCC warning "Deprecated pre-processor symbol")
1339#define GLIB_DEPRECATED_MACRO_FOR(f) \
1340 _GLIB_GNUC_DO_PRAGMA(GCC warning G_STRINGIFY (Deprecated pre-processor symbol: replace with #f))
1341#define GLIB_UNAVAILABLE_MACRO(maj,min) \
1342 _GLIB_GNUC_DO_PRAGMA(GCC warning G_STRINGIFY (Not available before maj.min))
1343#else
1344#define GLIB_DEPRECATED_MACRO
1345#define GLIB_DEPRECATED_MACRO_FOR(f)
1346#define GLIB_UNAVAILABLE_MACRO(maj,min)
1347#endif
1348
1349#if !defined(GLIB_DISABLE_DEPRECATION_WARNINGS) && \
1350 (G_GNUC_CHECK_VERSION(6, 1) || \
1351 (defined (__clang_major__) && (__clang_major__ > 3 || (__clang_major__ == 3 && __clang_minor__ >= 0))))
1352#define GLIB_DEPRECATED_ENUMERATOR G_DEPRECATED
1353#define GLIB_DEPRECATED_ENUMERATOR_FOR(f) G_DEPRECATED_FOR(f)
1354#define GLIB_UNAVAILABLE_ENUMERATOR(maj,min) G_UNAVAILABLE(maj,min)
1355#else
1356#define GLIB_DEPRECATED_ENUMERATOR
1357#define GLIB_DEPRECATED_ENUMERATOR_FOR(f)
1358#define GLIB_UNAVAILABLE_ENUMERATOR(maj,min)
1359#endif
1360
1361#if !defined(GLIB_DISABLE_DEPRECATION_WARNINGS) && \
1362 (G_GNUC_CHECK_VERSION(3, 1) || \
1363 (defined (__clang_major__) && (__clang_major__ > 3 || (__clang_major__ == 3 && __clang_minor__ >= 0))))
1364#define GLIB_DEPRECATED_TYPE G_DEPRECATED
1365#define GLIB_DEPRECATED_TYPE_FOR(f) G_DEPRECATED_FOR(f)
1366#define GLIB_UNAVAILABLE_TYPE(maj,min) G_UNAVAILABLE(maj,min)
1367#else
1368#define GLIB_DEPRECATED_TYPE
1369#define GLIB_DEPRECATED_TYPE_FOR(f)
1370#define GLIB_UNAVAILABLE_TYPE(maj,min)
1371#endif
1372
1373#ifndef __GI_SCANNER__
1374
1375#if g_macro__has_attribute(cleanup)
1376
1377/* these macros are private; note that gstdio.h also uses _GLIB_CLEANUP */
1378#define _GLIB_AUTOPTR_FUNC_NAME(TypeName) glib_autoptr_cleanup_##TypeName
1379#define _GLIB_AUTOPTR_CLEAR_FUNC_NAME(TypeName) glib_autoptr_clear_##TypeName
1380#define _GLIB_AUTOPTR_DESTROY_FUNC_NAME(TypeName) glib_autoptr_destroy_##TypeName
1381#define _GLIB_AUTOPTR_TYPENAME(TypeName) TypeName##_autoptr
1382#define _GLIB_AUTOPTR_LIST_FUNC_NAME(TypeName) glib_listautoptr_cleanup_##TypeName
1383#define _GLIB_AUTOPTR_LIST_TYPENAME(TypeName) TypeName##_listautoptr
1384#define _GLIB_AUTOPTR_SLIST_FUNC_NAME(TypeName) glib_slistautoptr_cleanup_##TypeName
1385#define _GLIB_AUTOPTR_SLIST_TYPENAME(TypeName) TypeName##_slistautoptr
1386#define _GLIB_AUTOPTR_QUEUE_FUNC_NAME(TypeName) glib_queueautoptr_cleanup_##TypeName
1387#define _GLIB_AUTOPTR_QUEUE_TYPENAME(TypeName) TypeName##_queueautoptr
1388#define _GLIB_AUTO_FUNC_NAME(TypeName) glib_auto_cleanup_##TypeName
1389#define _GLIB_CLEANUP(func) __attribute__((cleanup(func)))
1390#define _GLIB_DEFINE_AUTOPTR_CLEANUP_FUNCS(TypeName, ParentName, cleanup) \
1391 typedef TypeName *_GLIB_AUTOPTR_TYPENAME(TypeName); \
1392 typedef GList *_GLIB_AUTOPTR_LIST_TYPENAME(TypeName); \
1393 typedef GSList *_GLIB_AUTOPTR_SLIST_TYPENAME(TypeName); \
1394 typedef GQueue *_GLIB_AUTOPTR_QUEUE_TYPENAME(TypeName); \
1395 G_GNUC_BEGIN_IGNORE_DEPRECATIONS \
1396 static G_GNUC_UNUSED inline void _GLIB_AUTOPTR_CLEAR_FUNC_NAME(TypeName) (TypeName *_ptr) \
1397 { if (_ptr) (cleanup) ((ParentName *) _ptr); } \
1398 static G_GNUC_UNUSED inline void _GLIB_AUTOPTR_FUNC_NAME(TypeName) (TypeName **_ptr) \
1399 { _GLIB_AUTOPTR_CLEAR_FUNC_NAME(TypeName) (*_ptr); } \
1400 static G_GNUC_UNUSED inline void _GLIB_AUTOPTR_DESTROY_FUNC_NAME(TypeName) (void *_ptr) \
1401 { (cleanup) ((ParentName *) _ptr); } \
1402 static G_GNUC_UNUSED inline void _GLIB_AUTOPTR_LIST_FUNC_NAME(TypeName) (GList **_l) \
1403 { g_list_free_full (*_l, _GLIB_AUTOPTR_DESTROY_FUNC_NAME(TypeName)); } \
1404 static G_GNUC_UNUSED inline void _GLIB_AUTOPTR_SLIST_FUNC_NAME(TypeName) (GSList **_l) \
1405 { g_slist_free_full (*_l, _GLIB_AUTOPTR_DESTROY_FUNC_NAME(TypeName)); } \
1406 static G_GNUC_UNUSED inline void _GLIB_AUTOPTR_QUEUE_FUNC_NAME(TypeName) (GQueue **_q) \
1407 { if (*_q) g_queue_free_full (*_q, _GLIB_AUTOPTR_DESTROY_FUNC_NAME(TypeName)); } \
1408 G_GNUC_END_IGNORE_DEPRECATIONS
1409#define _GLIB_DEFINE_AUTOPTR_CHAINUP(ModuleObjName, ParentName) \
1410 _GLIB_DEFINE_AUTOPTR_CLEANUP_FUNCS(ModuleObjName, ParentName, _GLIB_AUTOPTR_CLEAR_FUNC_NAME(ParentName))
1411
1412
1413/* these macros are API */
1414#define G_DEFINE_AUTOPTR_CLEANUP_FUNC(TypeName, func) \
1415 _GLIB_DEFINE_AUTOPTR_CLEANUP_FUNCS(TypeName, TypeName, func)
1416#define G_DEFINE_AUTO_CLEANUP_CLEAR_FUNC(TypeName, func) \
1417 G_GNUC_BEGIN_IGNORE_DEPRECATIONS \
1418 static G_GNUC_UNUSED inline void _GLIB_AUTO_FUNC_NAME(TypeName) (TypeName *_ptr) { (func) (_ptr); } \
1419 G_GNUC_END_IGNORE_DEPRECATIONS
1420#define G_DEFINE_AUTO_CLEANUP_FREE_FUNC(TypeName, func, none) \
1421 G_GNUC_BEGIN_IGNORE_DEPRECATIONS \
1422 static G_GNUC_UNUSED inline void _GLIB_AUTO_FUNC_NAME(TypeName) (TypeName *_ptr) { if (*_ptr != none) (func) (*_ptr); } \
1423 G_GNUC_END_IGNORE_DEPRECATIONS
1424#define g_autoptr(TypeName) _GLIB_CLEANUP(_GLIB_AUTOPTR_FUNC_NAME(TypeName)) _GLIB_AUTOPTR_TYPENAME(TypeName)
1425#define g_autolist(TypeName) _GLIB_CLEANUP(_GLIB_AUTOPTR_LIST_FUNC_NAME(TypeName)) _GLIB_AUTOPTR_LIST_TYPENAME(TypeName)
1426#define g_autoslist(TypeName) _GLIB_CLEANUP(_GLIB_AUTOPTR_SLIST_FUNC_NAME(TypeName)) _GLIB_AUTOPTR_SLIST_TYPENAME(TypeName)
1427#define g_autoqueue(TypeName) _GLIB_CLEANUP(_GLIB_AUTOPTR_QUEUE_FUNC_NAME(TypeName)) _GLIB_AUTOPTR_QUEUE_TYPENAME(TypeName)
1428#define g_auto(TypeName) _GLIB_CLEANUP(_GLIB_AUTO_FUNC_NAME(TypeName)) TypeName
1429#define g_autofree _GLIB_CLEANUP(g_autoptr_cleanup_generic_gfree)
1430
1431#else /* not GNU C */
1432/* this (dummy) macro is private */
1433#define _GLIB_DEFINE_AUTOPTR_CHAINUP(ModuleObjName, ParentName)
1434
1435/* these (dummy) macros are API */
1436#define G_DEFINE_AUTOPTR_CLEANUP_FUNC(TypeName, func)
1437#define G_DEFINE_AUTO_CLEANUP_CLEAR_FUNC(TypeName, func)
1438#define G_DEFINE_AUTO_CLEANUP_FREE_FUNC(TypeName, func, none)
1439
1440/* no declaration of g_auto() or g_autoptr() here */
1441#endif /* __GNUC__ */
1442
1443#else
1444
1445#define _GLIB_DEFINE_AUTOPTR_CHAINUP(ModuleObjName, ParentName)
1446
1447#define G_DEFINE_AUTOPTR_CLEANUP_FUNC(TypeName, func)
1448#define G_DEFINE_AUTO_CLEANUP_CLEAR_FUNC(TypeName, func)
1449#define G_DEFINE_AUTO_CLEANUP_FREE_FUNC(TypeName, func, none)
1450
1451#endif /* __GI_SCANNER__ */
1452
1453/**
1454 * G_SIZEOF_MEMBER:
1455 * @struct_type: a structure type, e.g. #GOutputVector
1456 * @member: a field in the structure, e.g. `size`
1457 *
1458 * Returns the size of @member in the struct definition without having a
1459 * declared instance of @struct_type.
1460 *
1461 * Returns: the size of @member in bytes.
1462 *
1463 * Since: 2.64
1464 */
1465#define G_SIZEOF_MEMBER(struct_type, member) \
1466 GLIB_AVAILABLE_MACRO_IN_2_64 \
1467 sizeof (((struct_type *) 0)->member)
1468
1469#endif /* __G_MACROS_H__ */
1470