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