docs/reference/glib/tmpl/macros_misc.sgml

   1 <!-- ##### SECTION Title ##### -->
   2 Miscellaneous Macros
   3
   4 <!-- ##### SECTION Short_Description ##### -->
   5 specialized macros which are not used often
   6
   7 <!-- ##### SECTION Long_Description ##### -->
   8 <para>
   9 These macros provide more specialized features which are not needed so often
  10 by application programmers.
  11 </para>
  12
  13 <!-- ##### SECTION See_Also ##### -->
  14 <para>
  15
  16 </para>
  17
  18 <!-- ##### SECTION Stability_Level ##### -->
  19
  20
  21 <!-- ##### MACRO G_INLINE_FUNC ##### -->
  22 <para>
  23 This macro is used to export function prototypes so they can be linked
  24 with an external version when no inlining is performed. The file which
  25 implements the functions should define %G_IMPLEMENTS_INLINES
  26 before including the headers which contain %G_INLINE_FUNC declarations.
  27 Since inlining is very compiler-dependent using these macros correctly
  28 is very difficult. Their use is strongly discouraged.
  29 </para>
  30 <para>
  31 This macro is often mistaken for a replacement for the inline keyword;
  32 inline is already declared in a portable manner in the glib headers
  33 and can be used normally.
  34 </para>
  35
  36
  37
  38 <!-- ##### MACRO G_STMT_START ##### -->
  39 <para>
  40 Used within multi-statement macros so that they can be used in places where
  41 only one statement is expected by the compiler.
  42 </para>
  43
  44
  45
  46 <!-- ##### MACRO G_STMT_END ##### -->
  47 <para>
  48 Used within multi-statement macros so that they can be used in places where
  49 only one statement is expected by the compiler.
  50 </para>
  51
  52
  53
  54 <!-- ##### MACRO G_BEGIN_DECLS ##### -->
  55 <para>
  56 Used (along with #G_END_DECLS) to bracket header files. If the
  57 compiler in use is a C++ compiler, adds <literal>extern "C"</literal>
  58 around the header.
  59 </para>
  60
  61
  62
  63 <!-- ##### MACRO G_END_DECLS ##### -->
  64 <para>
  65 Used (along with #G_BEGIN_DECLS) to bracket header files. If the
  66 compiler in use is a C++ compiler, adds <literal>extern "C"</literal>
  67 around the header.
  68 </para>
  69
  70
  71
  72 <!-- ##### MACRO G_N_ELEMENTS ##### -->
  73 <para>
  74 Determines the number of elements in an array. The array must be
  75 declared so the compiler knows its size at compile-time; this
  76 macro will not work on an array allocated on the heap, only static
  77 arrays or arrays on the stack.
  78 </para>
  79
  80 @arr: the array
  81
  82
  83 <!-- ##### MACRO G_VA_COPY ##### -->
  84 <para>
  85 Portable way to copy <type>va_list</type> variables.
  86 </para>
  87 <para>
  88 In order to use this function, you must include <filename>string.h</filename>
  89 yourself, because this macro may use <function>memmove()</function> and GLib
  90 does not include <function>string.h</function> for you.
  91 </para>
  92
  93 @ap1: the <type>va_list</type> variable to place a copy of @ap2 in.
  94 @ap2: a <type>va_list</type>.
  95
  96
  97 <!-- ##### MACRO G_STRINGIFY ##### -->
  98 <para>
  99 Accepts a macro or a string and converts it into a string after
 100 preprocessor argument expansion.
 101 </para>
 102
 103 @macro_or_string: a macro or a string.
 104
 105
 106 <!-- ##### MACRO G_PASTE ##### -->
 107 <para>
 108 Yields a new preprocessor pasted identifier 'identifier1identifier2'
 109 from its expanded arguments 'identifier1' and 'identifier2'.
 110 </para>
 111
 112 @identifier1: an identifier
 113 @identifier2: an identifier
 114 @Since: 2.20
 115
 116
 117 <!-- ##### MACRO G_PASTE_ARGS ##### -->
 118 <para>
 119
 120 </para>
 121
 122 @identifier1:
 123 @identifier2:
 124
 125
 126 <!-- ##### MACRO G_STATIC_ASSERT ##### -->
 127 <para>
 128 The G_STATIC_ASSERT macro lets the programmer check a condition at compile time,
 129 the condition needs to be compile time computable.
 130 The macro can be used in any place where a <literal>typedef</literal> is valid.
 131 The macro should only be used once per source code line.
 132 </para>
 133
 134 @expr: a constant expression.
 135 @Since: 2.20
 136
 137
 138 <!-- ##### MACRO G_GNUC_EXTENSION ##### -->
 139 <para>
 140 Expands to <literal>__extension__</literal> when <command>gcc</command> is
 141 used as the compiler.
 142 This simply tells <command>gcc</command> not to warn about the following non-standard code
 143 when compiling with the <option>-pedantic</option> option.
 144 </para>
 145
 146
 147
 148 <!-- ##### MACRO G_GNUC_CONST ##### -->
 149 <para>
 150 Expands to the GNU C <literal>const</literal> function attribute if the compiler is
 151 <command>gcc</command>. Declaring a function as const enables better optimization of calls
 152 to the function. A const function doesn't examine any values except its parameters, and has no
 153 effects except its return value. See the GNU C documentation for details.
 154 </para>
 155 <note><para>
 156 A function that has pointer arguments and examines the data pointed to
 157 must <emphasis>not</emphasis> be declared const. Likewise, a function that
 158 calls a non-const function usually must not be const. It doesn't make sense
 159 for a const function to return void.
 160 </para></note>
 161
 162
 163
 164 <!-- ##### MACRO G_GNUC_PURE ##### -->
 165 <para>
 166 Expands to the GNU C <literal>pure</literal> function attribute if the compiler is
 167 <command>gcc</command>. Declaring a function as pure enables better optimization of
 168 calls to the function. A pure function has no effects except its return value and the
 169 return value depends only on the parameters and/or global variables.
 170 See the GNU C documentation for details.
 171 </para>
 172
 173
 174
 175 <!-- ##### MACRO G_GNUC_MALLOC ##### -->
 176 <para>
 177 Expands to the GNU C <literal>malloc</literal> function attribute if the
 178 compiler is <command>gcc</command>. Declaring a function as malloc enables
 179 better optimization of the function. A function can have the malloc attribute
 180 if it returns a pointer which is guaranteed to not alias with any other pointer
 181 when the function returns (in practice, this means newly allocated memory).
 182 See the GNU C documentation for details.
 183 </para>
 184
 185 @Since: 2.6
 186
 187
 188 <!-- ##### MACRO G_GNUC_ALLOC_SIZE ##### -->
 189 <para>
 190 Expands to the GNU C <literal>alloc_size</literal> function attribute if the
 191 compiler is a new enough <command>gcc</command>. This attribute tells the
 192 compiler that the function returns a pointer to memory of a size that is
 193 specified by the @x<!-- -->th function parameter.
 194 See the GNU C documentation for details.
 195 </para>
 196
 197 @x: the index of the argument specifying the allocation size
 198 @Since: 2.18
 199
 200
 201 <!-- ##### MACRO G_GNUC_ALLOC_SIZE2 ##### -->
 202 <para>
 203 Expands to the GNU C <literal>alloc_size</literal> function attribute if the
 204 compiler is a new enough <command>gcc</command>. This attribute tells the
 205 compiler that the function returns a pointer to memory of a size that is
 206 specified by the product of two function parameters.
 207 See the GNU C documentation for details.
 208 </para>
 209
 210 @x: the index of the argument specifying one factor of the allocation size
 211 @y: the index of the argument specifying the second factor of the allocation size
 212 @Since: 2.18
 213
 214
 215 <!-- ##### MACRO G_GNUC_DEPRECATED ##### -->
 216 <para>
 217 Expands to the GNU C <literal>deprecated</literal> attribute if the compiler
 218 is <command>gcc</command>.
 219 It can be used to mark typedefs, variables and functions as deprecated.
 220 When called with the <option>-Wdeprecated-declarations</option> option, the compiler will
 221 generate warnings when deprecated interfaces are used.
 222 See the GNU C documentation for details.
 223 </para>
 224
 225 @Since: 2.2
 226
 227
 228 <!-- ##### MACRO G_GNUC_NORETURN ##### -->
 229 <para>
 230 Expands to the GNU C <literal>noreturn</literal> function attribute if the
 231 compiler is <command>gcc</command>. It is used for declaring functions which never return.
 232 It enables optimization of the function, and avoids possible compiler
 233 warnings. See the GNU C documentation for details.
 234 </para>
 235
 236
 237
 238 <!-- ##### MACRO G_GNUC_UNUSED ##### -->
 239 <para>
 240 Expands to the GNU C <literal>unused</literal> function attribute if the compiler is
 241 <command>gcc</command>. It is used for declaring functions which may never be used.
 242 It avoids possible compiler warnings. See the GNU C documentation for details.
 243 </para>
 244
 245
 246
 247 <!-- ##### MACRO G_GNUC_PRINTF ##### -->
 248 <para>
 249 Expands to the GNU C <literal>format</literal> function attribute if the compiler is
 250 <command>gcc</command>. This is used for declaring functions which take a variable number of
 251 arguments, with the same syntax as <function>printf()</function>.
 252 It allows the compiler to type-check the arguments passed to the function.
 253 See the GNU C documentation for details.
 254 </para>
 255 <informalexample><programlisting>
 256 gint g_snprintf (gchar  *string,
 257                  gulong       n,
 258                  gchar const *format,
 259                  ...) G_GNUC_PRINTF (3, 4);
 260 </programlisting></informalexample>
 261
 262 @format_idx: the index of the argument corresponding to the format string.
 263 (The arguments are numbered from 1).
 264 @arg_idx: the index of the first of the format arguments.
 265
 266
 267 <!-- ##### MACRO G_GNUC_SCANF ##### -->
 268 <para>
 269 Expands to the GNU C <literal>format</literal> function attribute if the compiler is <command>gcc</command>.
 270 This is used for declaring functions which take a variable number of
 271 arguments, with the same syntax as <function>scanf()</function>.
 272 It allows the compiler to type-check the arguments passed to the function.
 273 See the GNU C documentation for details.
 274 </para>
 275
 276 @format_idx: the index of the argument corresponding to the format string.
 277 (The arguments are numbered from 1).
 278 @arg_idx: the index of the first of the format arguments.
 279
 280
 281 <!-- ##### MACRO G_GNUC_FORMAT ##### -->
 282 <para>
 283 Expands to the GNU C <literal>format_arg</literal> function attribute if the compiler is <command>gcc</command>.
 284 This function attribute specifies that a function takes a format
 285 string for a <function>printf()</function>, <function>scanf()</function>,
 286 <function>strftime()</function> or <function>strfmon()</function> style
 287 function and modifies it, so that the result can be passed to a
 288 <function>printf()</function>, <function>scanf()</function>,
 289 <function>strftime()</function> or <function>strfmon()</function> style
 290 function (with the remaining arguments to the format function the same as
 291 they would have been for the unmodified string).
 292 See the GNU C documentation for details.
 293 </para>
 294 <informalexample><programlisting>
 295 gchar *g_dgettext (gchar *domain_name, gchar *msgid) G_GNUC_FORMAT (2);
 296 </programlisting></informalexample>
 297
 298 @arg_idx: the index of the argument.
 299
 300
 301 <!-- ##### MACRO G_GNUC_NULL_TERMINATED ##### -->
 302 <para>
 303 Expands to the GNU C <literal>sentinel</literal> function attribute if the
 304 compiler is <command>gcc</command>, or "" if it isn't. This function attribute
 305 only applies to variadic functions and instructs the compiler to check that
 306 the argument list is terminated with an explicit %NULL.
 307 See the GNU C documentation for details.
 308 </para>
 309
 310 Since: 2.8
 311
 312
 313
 314 <!-- ##### MACRO G_GNUC_WARN_UNUSED_RESULT ##### -->
 315 <para>
 316 Expands to the GNU C <literal>warn_unused_result</literal> function attribute
 317 if the compiler is <command>gcc</command>, or "" if it isn't. This function
 318 attribute makes the compiler emit a warning if the result of a function call
 319 is ignored. See the GNU C documentation for details.
 320 </para>
 321
 322 @Since: 2.10
 323
 324
 325 <!-- ##### MACRO G_GNUC_FUNCTION ##### -->
 326 <para>
 327 Expands to "" on all modern compilers, and to <literal>__FUNCTION__</literal>
 328 on <command>gcc</command> version 2.x. Don't use it.
 329 </para>
 330
 331 @Deprecated: 2.16: Use #G_STRFUNC instead.
 332
 333
 334 <!-- ##### MACRO G_GNUC_PRETTY_FUNCTION ##### -->
 335 <para>
 336 Expands to "" on all modern compilers, and to
 337 <literal>__PRETTY_FUNCTION__</literal> on <command>gcc</command> version 2.x.
 338 Don't use it.
 339 </para>
 340
 341 @Deprecated: 2.16: Use #G_STRFUNC instead.
 342
 343
 344 <!-- ##### MACRO G_GNUC_NO_INSTRUMENT ##### -->
 345 <para>
 346 Expands to the GNU C <literal>no_instrument_function</literal> function
 347 attribute if the compiler is <command>gcc</command>. Functions with this
 348 attribute will not be
 349 instrumented for profiling, when the compiler is called with the
 350 <option>-finstrument-functions</option> option.
 351 See the GNU C documentation for details.
 352 </para>
 353
 354
 355
 356 <!-- ##### MACRO G_HAVE_GNUC_VISIBILITY ##### -->
 357 <para>
 358
 359 </para>
 360
 361
 362
 363 <!-- ##### MACRO G_GNUC_INTERNAL ##### -->
 364 <para>
 365 This attribute can be used for marking library functions as being used
 366 internally to the library only, which may allow the compiler to handle
 367 function calls more efficiently.
 368 Note that static functions do not need to be marked as internal in this way.
 369 See the GNU C documentation for details.
 370 </para>
 371 <para>
 372 When using a compiler that supports the GNU C hidden visibility attribute,
 373 this macro expands to <literal>__attribute__((visibility("hidden")))</literal>.
 374 When using the Sun Studio compiler, it expands to <literal>__hidden</literal>.
 375 </para>
 376 <para>
 377 Note that for portability, the attribute should be placed before the
 378 function declaration. While GCC allows the macro after the declaration,
 379 Sun Studio does not.
 380 </para>
 381 <informalexample><programlisting>
 382 G_GNUC_INTERNAL
 383 void _g_log_fallback_handler (const gchar    *log_domain,
 384                               GLogLevelFlags  log_level,
 385                               const gchar    *message,
 386                               gpointer        unused_data);
 387 </programlisting></informalexample>
 388
 389 Since: 2.6
 390
 391
 392
 393 <!-- ##### MACRO G_GNUC_MAY_ALIAS ##### -->
 394 <para>
 395 Expands to the GNU C <literal>may_alias</literal> type attribute
 396 if the compiler is <command>gcc</command>. Types with this attribute
 397 will not be subjected to type-based alias analysis, but are assumed
 398 to alias with any other type, just like char.
 399 See the GNU C documentation for details.
 400 </para>
 401
 402 Since: 2.14
 403
 404
 405
 406 <!-- ##### MACRO G_LIKELY ##### -->
 407 <para>
 408 Hints the compiler that the expression is likely to evaluate to a true
 409 value. The compiler may use this information for optimizations.
 410 </para>
 411 <informalexample><programlisting>
 412 if (G_LIKELY (random () != 1))
 413   g_print ("not one");
 414 </programlisting></informalexample>
 415
 416 @expr: the expression
 417 @Returns: the value of @expr
 418 @Since: 2.2
 419
 420
 421 <!-- ##### MACRO G_UNLIKELY ##### -->
 422 <para>
 423 Hints the compiler that the expression is unlikely to evaluate to a true
 424 value. The compiler may use this information for optimizations.
 425 </para>
 426 <informalexample><programlisting>
 427 if (G_UNLIKELY (random () == 1))
 428   g_print ("a random one");
 429 </programlisting></informalexample>
 430
 431 @expr: the expression
 432 @Returns: the value of @expr
 433 @Since: 2.2
 434
 435
 436 <!-- ##### MACRO G_STRLOC ##### -->
 437 <para>
 438 Expands to a string identifying the current code position.
 439 </para>
 440
 441
 442
 443 <!-- ##### MACRO G_STRFUNC ##### -->
 444 <para>
 445 Expands to a string identifying the current function.
 446 </para>
 447
 448 @Since: 2.4
 449
 450
 451 <!-- ##### MACRO G_GINT16_MODIFIER ##### -->
 452 <para>
 453 The platform dependent length modifier for conversion specifiers for scanning
 454 and printing values of type #gint16 or #guint16. It is a string literal,
 455 but doesn't include the percent-sign, such that you can add precision and
 456 length modifiers between percent-sign and conversion specifier and append a
 457 conversion specifier.
 458 </para>
 459
 460 <para>
 461 The following example prints "0x7b";
 462 <informalexample>
 463 <programlisting>
 464 gint16 value = 123;
 465 g_print ("%#" G_GINT16_MODIFIER "x", value);
 466 </programlisting>
 467 </informalexample>
 468 </para>
 469
 470 @Since: 2.4
 471
 472
 473 <!-- ##### MACRO G_GINT16_FORMAT ##### -->
 474 <para>
 475 This is the platform dependent conversion specifier for scanning and
 476 printing values of type #gint16. It is a string literal, but doesn't
 477 include the percent-sign, such that you can add precision and length
 478 modifiers between percent-sign and conversion specifier.
 479 </para>
 480
 481 <para>
 482 <informalexample>
 483 <programlisting>
 484 gint16 in;
 485 gint32 out;
 486 sscanf ("42", "%" G_GINT16_FORMAT, &amp;in)
 487 out = in * 1000;
 488 g_print ("%" G_GINT32_FORMAT, out);
 489 </programlisting>
 490 </informalexample>
 491 </para>
 492
 493
 494
 495 <!-- ##### MACRO G_GUINT16_FORMAT ##### -->
 496 <para>
 497 This is the platform dependent conversion specifier for scanning and
 498 printing values of type #guint16. See also #G_GINT16_FORMAT.
 499 </para>
 500
 501
 502
 503 <!-- ##### MACRO G_GINT32_MODIFIER ##### -->
 504 <para>
 505 The platform dependent length modifier for conversion specifiers for scanning
 506 and printing values of type #gint32 or #guint32. It is a string literal,
 507 See also #G_GINT16_MODIFIER.
 508 </para>
 509
 510 @Since: 2.4
 511
 512
 513 <!-- ##### MACRO G_GINT32_FORMAT ##### -->
 514 <para>
 515 This is the platform dependent conversion specifier for scanning and
 516 printing values of type #gint32. See also #G_GINT16_FORMAT.
 517 </para>
 518
 519
 520
 521 <!-- ##### MACRO G_GUINT32_FORMAT ##### -->
 522 <para>
 523 This is the platform dependent conversion specifier for scanning and
 524 printing values of type #guint32. See also #G_GINT16_FORMAT.
 525 </para>
 526
 527
 528
 529 <!-- ##### MACRO G_GINT64_MODIFIER ##### -->
 530 <para>
 531 The platform dependent length modifier for conversion specifiers for scanning
 532 and printing values of type #gint64 or #guint64. It is a string literal.
 533 </para>
 534
 535 <note>
 536 <para>
 537 Some platforms do not support printing 64 bit integers,
 538 even though the types are supported. On such platforms #G_GINT64_MODIFIER
 539 is not defined.
 540 </para>
 541 </note>
 542
 543 @Since: 2.4
 544
 545
 546 <!-- ##### MACRO G_GINT64_FORMAT ##### -->
 547 <para>
 548 This is the platform dependent conversion specifier for scanning and
 549 printing values of type #gint64. See also #G_GINT16_FORMAT.
 550 </para>
 551
 552 <note>
 553 <para>
 554 Some platforms do not support scanning and printing 64 bit integers,
 555 even though the types are supported. On such platforms #G_GINT64_FORMAT
 556 is not defined. Note that scanf() may not support 64 bit integers, even
 557 if #G_GINT64_FORMAT is defined. Due to its weak error handling, scanf()
 558 is not recommended for parsing anyway; consider using g_ascii_strtoull()
 559 instead.
 560 </para>
 561 </note>
 562
 563
 564
 565 <!-- ##### MACRO G_GUINT64_FORMAT ##### -->
 566 <para>
 567 This is the platform dependent conversion specifier for scanning and
 568 printing values of type #guint64. See also #G_GINT16_FORMAT.
 569 </para>
 570
 571 <note>
 572 <para>
 573 Some platforms do not support scanning and printing 64 bit integers,
 574 even though the types are supported. On such platforms #G_GUINT64_FORMAT
 575 is not defined.  Note that scanf() may not support 64 bit integers, even
 576 if #G_GINT64_FORMAT is defined. Due to its weak error handling, scanf() is not
 577 recommended for parsing anyway; consider using g_strtoull() instead.
 578 </para>
 579 </note>
 580
 581
 582
 583 <!-- ##### MACRO G_GSIZE_MODIFIER ##### -->
 584 <para>
 585 The platform dependent length modifier for conversion specifiers for scanning
 586 and printing values of type #gsize or #gssize. It is a string literal,
 587 </para>
 588
 589 @Since: 2.6
 590
 591
 592 <!-- ##### MACRO G_GSIZE_FORMAT ##### -->
 593 <para>
 594 This is the platform dependent conversion specifier for scanning and
 595 printing values of type #gsize. See also #G_GINT16_FORMAT.
 596 </para>
 597
 598 @Since: 2.6
 599
 600
 601 <!-- ##### MACRO G_GSSIZE_FORMAT ##### -->
 602 <para>
 603 This is the platform dependent conversion specifier for scanning and
 604 printing values of type #gssize. See also #G_GINT16_FORMAT.
 605 </para>
 606
 607 @Since: 2.6
 608
 609
 610 <!-- ##### MACRO G_GOFFSET_MODIFIER ##### -->
 611 <para>
 612 The platform dependent length modifier for conversion specifiers for scanning
 613 and printing values of type #goffset. It is a string literal. See also
 614 #G_GINT64_MODIFIER.
 615 </para>
 616
 617 @Since: 2.20
 618
 619
 620 <!-- ##### MACRO G_GOFFSET_FORMAT ##### -->
 621 <para>
 622 This is the platform dependent conversion specifier for scanning and
 623 printing values of type #goffset. See also #G_GINT64_FORMAT.
 624 </para>
 625
 626 Since: 2.20
 627
 628
 629
 630 <!-- ##### MACRO G_GINTPTR_MODIFIER ##### -->
 631 <para>
 632 The platform dependent length modifier for conversion specifiers for scanning
 633 and printing values of type #gintptr or #guintptr. It is a string literal.
 634 </para>
 635
 636 @Since: 2.22
 637
 638
 639 <!-- ##### MACRO G_GINTPTR_FORMAT ##### -->
 640 <para>
 641 This is the platform dependent conversion specifier for scanning and
 642 printing values of type #gintptr.
 643 </para>
 644
 645 @Since: 2.22
 646
 647
 648 <!-- ##### MACRO G_GUINTPTR_FORMAT ##### -->
 649 <para>
 650 This is the platform dependent conversion specifier for scanning and
 651 printing values of type #guintptr.
 652 </para>
 653
 654 @Since: 2.22
 655
 656