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