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 <!-- ##### MACRO G_INLINE_FUNC ##### -->
  19 <para>
  20 Used to declare inline functions. If inline functions are not supported on
  21 the particular platform, the macro evaluates to the empty string.
  22 </para>
  23
  24
  25
  26 <!-- ##### MACRO G_STMT_START ##### -->
  27 <para>
  28 Used within multi-statement macros so that they can be used in places where
  29 only one statement is expected by the compiler.
  30 </para>
  31
  32
  33
  34 <!-- ##### MACRO G_STMT_END ##### -->
  35 <para>
  36 Used within multi-statement macros so that they can be used in places where
  37 only one statement is expected by the compiler.
  38 </para>
  39
  40
  41
  42 <!-- ##### MACRO G_BEGIN_DECLS ##### -->
  43 <para>
  44 Used (along with #G_END_DECLS) to bracket header files. If the
  45 compiler in use is a C++ compiler, adds <literal>extern "C"</literal>
  46 around the header.
  47 </para>
  48
  49
  50
  51 <!-- ##### MACRO G_END_DECLS ##### -->
  52 <para>
  53 Used (along with #G_BEGIN_DECLS) to bracket header files. If the
  54 compiler in use is a C++ compiler, adds <literal>extern "C"</literal>
  55 around the header.
  56 </para>
  57
  58
  59
  60 <!-- ##### MACRO G_N_ELEMENTS ##### -->
  61 <para>
  62 Determines the number of elements in an array. The array must be
  63 declared so the compiler knows its size at compile-time; this
  64 macro will not work on an array allocated on the heap, only static
  65 arrays or arrays on the stack.
  66 </para>
  67
  68 @arr: the array
  69
  70
  71 <!-- ##### MACRO G_VA_COPY ##### -->
  72 <para>
  73 Portable way to copy <type>va_list</type> variables.
  74 </para>
  75 <para>
  76 In order to use this function, you must include <filename>string.h</filename>
  77 yourself, because this macro may use <function>memmove()</function> and GLib
  78 does not include <function>string.h</function> for you.
  79 </para>
  80
  81 <!-- # Unused Parameters # -->
  82 @ap1: the <type>va_list</type> variable to place a copy of @ap2 in.
  83 @ap2: a <type>va_list</type>.
  84
  85
  86 <!-- ##### MACRO G_STRINGIFY ##### -->
  87 <para>
  88 Accepts a macro or a string and converts it into a string.
  89 </para>
  90
  91 @macro_or_string: a macro or a string.
  92
  93
  94 <!-- ##### MACRO G_GNUC_EXTENSION ##### -->
  95 <para>
  96 Expands to <literal>__extension__</literal> when <command>gcc</command> is
  97 used as the compiler.
  98 This simply tells <command>gcc</command> not to warn about the following non-standard code
  99 when compiling with the <option>-pedantic</option> option.
 100 </para>
 101
 102
 103
 104 <!-- ##### MACRO G_GNUC_CONST ##### -->
 105 <para>
 106 Expands to the GNU C <literal>const</literal> function attribute if the compiler is
 107 <command>gcc</command>. Declaring a function as const enables better optimization of calls
 108 to the function. A const function doesn't examine any values except its parameters, and has no
 109 effects except its return value. See the GNU C documentation for details.
 110 </para>
 111 <note><para>
 112 A function that has pointer arguments and examines the data pointed to
 113 must <emphasis>not</emphasis> be declared const. Likewise, a function that
 114 calls a non-const function usually must not be const. It doesn't make sense
 115 for a const function to return void.
 116 </para></note>
 117
 118
 119
 120 <!-- ##### MACRO G_GNUC_PURE ##### -->
 121 <para>
 122 Expands to the GNU C <literal>pure</literal> function attribute if the compiler is
 123 <command>gcc</command>. Declaring a function as pure enables better optimization of
 124 calls to the function. A pure function has no effects except its return value and the
 125 return value depends only on the parameters and/or global variables.
 126 See the GNU C documentation for details.
 127 </para>
 128
 129
 130
 131 <!-- ##### MACRO G_GNUC_MALLOC ##### -->
 132 <para>
 133 Expands to the GNU C <literal>malloc</literal> function attribute if the compiler is
 134 <command>gcc</command>. Declaring a function as malloc enables better optimization of the
 135 function. A function can have the malloc attribute if it returns a pointer which is guaranteed
 136 to not alias with any other pointer when the function returns (in practice, this means newly
 137 allocated memory).
 138 See the GNU C documentation for details.
 139 </para>
 140
 141 @Since: 2.6
 142
 143
 144 <!-- ##### MACRO G_GNUC_DEPRECATED ##### -->
 145 <para>
 146 Expands to the GNU C <literal>deprecated</literal> attribute if the compiler
 147 is <command>gcc</command>.
 148 It can be used to mark typedefs, variables and functions as deprecated.
 149 When called with the <option>-Wdeprecated</option> option, the compiler will
 150 generate warnings when deprecated interfaces are used.
 151 See the GNU C documentation for details.
 152 </para>
 153
 154 @Since: 2.2
 155
 156
 157 <!-- ##### MACRO G_GNUC_NORETURN ##### -->
 158 <para>
 159 Expands to the GNU C <literal>noreturn</literal> function attribute if the
 160 compiler is <command>gcc</command>. It is used for declaring functions which never return.
 161 It enables optimization of the function, and avoids possible compiler
 162 warnings. See the GNU C documentation for details.
 163 </para>
 164
 165
 166
 167 <!-- ##### MACRO G_GNUC_UNUSED ##### -->
 168 <para>
 169 Expands to the GNU C <literal>unused</literal> function attribute if the compiler is
 170 <command>gcc</command>. It is used for declaring functions which may never be used.
 171 It avoids possible compiler warnings. See the GNU C documentation for details.
 172 </para>
 173
 174
 175
 176 <!-- ##### MACRO G_GNUC_PRINTF ##### -->
 177 <para>
 178 Expands to the GNU C <literal>format</literal> function attribute if the compiler is
 179 <command>gcc</command>. This is used for declaring functions which take a variable number of
 180 arguments, with the same syntax as <function>printf()</function>.
 181 It allows the compiler to type-check the arguments passed to the function.
 182 See the GNU C documentation for details.
 183 </para>
 184 <informalexample><programlisting>
 185 gint g_snprintf (gchar  *string,
 186                  gulong       n,
 187                  gchar const *format,
 188                  ...) G_GNUC_PRINTF (3, 4);
 189 </programlisting></informalexample>
 190
 191 @format_idx: the index of the argument corresponding to the format string.
 192 (The arguments are numbered from 1).
 193 @arg_idx: the index of the first of the format arguments.
 194
 195
 196 <!-- ##### MACRO G_GNUC_SCANF ##### -->
 197 <para>
 198 Expands to the GNU C <literal>format</literal> function attribute if the compiler is <command>gcc</command>.
 199 This is used for declaring functions which take a variable number of
 200 arguments, with the same syntax as <function>scanf()</function>.
 201 It allows the compiler to type-check the arguments passed to the function.
 202 See the GNU C documentation for details.
 203 </para>
 204
 205 @format_idx: the index of the argument corresponding to the format string.
 206 (The arguments are numbered from 1).
 207 @arg_idx: the index of the first of the format arguments.
 208
 209
 210 <!-- ##### MACRO G_GNUC_FORMAT ##### -->
 211 <para>
 212 Expands to the GNU C <literal>format_arg</literal> function attribute if the compiler is <command>gcc</command>.
 213 This function attribute specifies that a function takes a format
 214 string for a <function>printf()</function>, <function>scanf()</function>,
 215 <function>strftime()</function> or <function>strfmon()</function> style
 216 function and modifies it, so that the result can be passed to a
 217 <function>printf()</function>, <function>scanf()</function>,
 218 <function>strftime()</function> or <function>strfmon()</function> style
 219 function (with the remaining arguments to the format function the same as
 220 they would have been for the unmodified string).
 221 See the GNU C documentation for details.
 222 </para>
 223 <informalexample><programlisting>
 224 gchar *g_dgettext (gchar *domain_name, gchar *msgid) G_GNUC_FORMAT (2);
 225 </programlisting></informalexample>
 226
 227 @arg_idx: the index of the argument.
 228
 229
 230 <!-- ##### MACRO G_GNUC_NULL_TERMINATED ##### -->
 231 <para>
 232 Expands to the GNU C <literal>sentinel</literal> function attribute if the
 233 compiler is <command>gcc</command>, or "" if it isn't. This function attribute
 234 only applies to variadic functions and instructs the compiler to check that
 235 the argument list is terminated with an explicit %NULL.
 236 See the GNU C documentation for details.
 237 </para>
 238
 239 Since: 2.8
 240
 241 <!-- ##### MACRO G_GNUC_FUNCTION ##### -->
 242 <para>
 243 Expands to the GNU C <literal>__FUNCTION__</literal> variable if the
 244 compiler is <command>gcc</command>, or "" if it isn't. The GNU C
 245 <literal>__FUNCTION__</literal> variable contains the name of the
 246 current function. See the GNU C documentation for details.
 247 </para>
 248
 249
 250
 251 <!-- ##### MACRO G_GNUC_PRETTY_FUNCTION ##### -->
 252 <para>
 253 Expands to the GNU C <literal>__PRETTY_FUNCTION__</literal> variable
 254 if the compiler is <command>gcc</command>, or "" if it isn't.
 255 The GNU C <literal>__PRETTY_FUNCTION__</literal> variable contains the
 256 name of the current function. For a C program this is the same as the
 257 <literal>__FUNCTION__</literal> variable but for C++ it also includes
 258 extra information such as the class and function prototype. See the
 259 GNU C documentation for details.
 260 </para>
 261
 262
 263
 264 <!-- ##### MACRO G_GNUC_NO_INSTRUMENT ##### -->
 265 <para>
 266 Expands to the GNU C <literal>no_instrument_function</literal> function
 267 attribute if the compiler is <command>gcc</command>. Functions with this
 268 attribute will not be
 269 instrumented for profiling, when the compiler is called with the
 270 <option>-finstrument-functions</option> option.
 271 See the GNU C documentation for details.
 272 </para>
 273
 274
 275
 276 <!-- ##### MACRO G_HAVE_GNUC_VISIBILITY ##### -->
 277 <para>
 278 This macro is defined as 1 if the the compiler supports ELF visibility
 279 attributes (currently only <command>gcc</command>).
 280 </para>
 281
 282 Since: 2.6
 283
 284
 285
 286 <!-- ##### MACRO G_GNUC_INTERNAL ##### -->
 287 <para>
 288 Expands to the GNU C <literal>visibility(hidden)</literal> attribute if the
 289 compiler supports it  (currently only <command>gcc</command>). This attribute
 290 can be used for marking library functions as being used internally to the lib
 291 only, to not create inefficient PLT entries. Note that static functions do not
 292 need to be marked as internal in this way. See the GNU C documentation for details.
 293 </para>
 294
 295 Since: 2.6
 296
 297
 298
 299 <!-- ##### MACRO G_LIKELY ##### -->
 300 <para>
 301 Hints the compiler that the expression is likely to evaluate to a true
 302 value. The compiler may use this information for optimizations.
 303 </para>
 304 <informalexample><programlisting>
 305 if (G_LIKELY (random () != 1))
 306   g_print ("not one");
 307 </programlisting></informalexample>
 308
 309 @expr: the expression
 310 @Since: 2.2
 311
 312
 313 <!-- ##### MACRO G_UNLIKELY ##### -->
 314 <para>
 315 Hints the compiler that the expression is unlikely to evaluate to a true
 316 value. The compiler may use this information for optimizations.
 317 </para>
 318 <informalexample><programlisting>
 319 if (G_UNLIKELY (random () == 1))
 320   g_print ("a random one");
 321 </programlisting></informalexample>
 322
 323 @expr: the expression
 324 @Since: 2.2
 325
 326
 327 <!-- ##### MACRO G_STRLOC ##### -->
 328 <para>
 329 Expands to a string identifying the current code position.
 330 </para>
 331
 332
 333
 334 <!-- ##### MACRO G_STRFUNC ##### -->
 335 <para>
 336 Expands to a string identifying the current function.
 337 </para>
 338
 339 @Since: 2.4
 340
 341
 342 <!-- ##### MACRO G_GINT16_MODIFIER ##### -->
 343 <para>
 344 The platform dependent length modifier for constructing printf() conversion
 345 specifiers for values of type #gint16 or #guint16. It is a string literal,
 346 but doesn't include the percent-sign, such that you can add precision and
 347 length modifiers between percent-sign and conversion specifier and append a
 348 conversion specifier.
 349 </para>
 350
 351 <para>
 352 The following example prints "0x7b";
 353 <informalexample>
 354 <programlisting>
 355 gint16 value = 123;
 356 g_print ("%#" G_GINT16_MODIFIER "x", value);
 357 </programlisting>
 358 </informalexample>
 359 </para>
 360
 361 @Since: 2.4
 362
 363
 364 <!-- ##### MACRO G_GINT16_FORMAT ##### -->
 365 <para>
 366 This is the platform dependent conversion specifier for scanning and
 367 printing values of type #gint16. It is a string literal, but doesn't
 368 include the percent-sign, such that you can add precision and length
 369 modifiers between percent-sign and conversion specifier.
 370 </para>
 371
 372 <para>
 373 <informalexample>
 374 <programlisting>
 375 gint16 in;
 376 gint32 out;
 377 sscanf ("42", "%" G_GINT16_FORMAT, &amp;in)
 378 out = in * 1000;
 379 g_print ("%" G_GINT32_FORMAT, out);
 380 </programlisting>
 381 </informalexample>
 382 </para>
 383
 384
 385
 386 <!-- ##### MACRO G_GUINT16_FORMAT ##### -->
 387 <para>
 388 This is the platform dependent conversion specifier for scanning and
 389 printing values of type #guint16. See also #G_GINT16_FORMAT.
 390 </para>
 391
 392
 393
 394 <!-- ##### MACRO G_GINT32_MODIFIER ##### -->
 395 <para>
 396 The platform dependent length modifier for constructing printf() conversion
 397 specifiers for values of type #gint32 or #guint32. See also #G_GINT16_MODIFIER.
 398 </para>
 399
 400 @Since: 2.4
 401
 402
 403 <!-- ##### MACRO G_GINT32_FORMAT ##### -->
 404 <para>
 405 This is the platform dependent conversion specifier for scanning and
 406 printing values of type #gint32. See also #G_GINT16_FORMAT.
 407 </para>
 408
 409
 410
 411 <!-- ##### MACRO G_GUINT32_FORMAT ##### -->
 412 <para>
 413 This is the platform dependent conversion specifier for scanning and
 414 printing values of type #guint32. See also #G_GINT16_FORMAT.
 415 </para>
 416
 417
 418
 419 <!-- ##### MACRO G_GINT64_MODIFIER ##### -->
 420 <para>
 421 The platform dependent length modifier for constructing printf() conversion
 422 specifiers for values of type #gint64 or #guint64. See also #G_GINT16_MODIFIER.
 423 </para>
 424
 425 <note>
 426 <para>
 427 Some platforms do not support printing 64 bit integers,
 428 even though the types are supported. On such platforms #G_GINT64_MODIFIER
 429 is not defined.
 430 </para>
 431 </note>
 432
 433 @Since: 2.4
 434
 435
 436 <!-- ##### MACRO G_GINT64_FORMAT ##### -->
 437 <para>
 438 This is the platform dependent conversion specifier for scanning and
 439 printing values of type #gint64. See also #G_GINT16_FORMAT.
 440 </para>
 441
 442 <note>
 443 <para>
 444 Some platforms do not support scanning and printing 64 bit integers,
 445 even though the types are supported. On such platforms #G_GINT64_FORMAT
 446 is not defined. Note that scanf() may not support 64 bit integers, even
 447 if #G_GINT64_FORMAT is defined. Due to its weak error handling, scanf() is not
 448 recommended for parsing anyway; consider using g_strtoull() instead.
 449 </para>
 450 </note>
 451
 452
 453
 454 <!-- ##### MACRO G_GUINT64_FORMAT ##### -->
 455 <para>
 456 This is the platform dependent conversion specifier for scanning and
 457 printing values of type #guint64. See also #G_GINT16_FORMAT.
 458 </para>
 459
 460 <note>
 461 <para>
 462 Some platforms do not support scanning and printing 64 bit integers,
 463 even though the types are supported. On such platforms #G_GUINT64_FORMAT
 464 is not defined.  Note that scanf() may not support 64 bit integers, even
 465 if #G_GINT64_FORMAT is defined. Due to its weak error handling, scanf() is not
 466 recommended for parsing anyway; consider using g_strtoull() instead.
 467 </para>
 468 </note>
 469
 470
 471
 472 <!-- ##### MACRO G_GSIZE_MODIFIER ##### -->
 473 <para>
 474 The platform dependent length modifier for constructing printf() conversion
 475 specifiers for values of type #gsize or #gssize. See also #G_GINT16_MODIFIER.
 476 </para>
 477
 478 @Since: 2.6
 479
 480
 481 <!-- ##### MACRO G_GSIZE_FORMAT ##### -->
 482 <para>
 483 This is the platform dependent conversion specifier for scanning and
 484 printing values of type #gsize. See also #G_GINT16_FORMAT.
 485 </para>
 486
 487 @Since: 2.6
 488
 489
 490 <!-- ##### MACRO G_GSSIZE_FORMAT ##### -->
 491 <para>
 492 This is the platform dependent conversion specifier for scanning and
 493 printing values of type #gssize. See also #G_GINT16_FORMAT.
 494 </para>
 495
 496 @Since: 2.6
 497
 498