glib/gmacros.h

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