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