1
<!-- ##### SECTION Title ##### -->
4
<!-- ##### SECTION Short_Description ##### -->
5
specialized macros which are not used often.
7
<!-- ##### SECTION Long_Description ##### -->
9
These macros provide more specialized features which are not needed so often
10
by application programmers.
13
<!-- ##### SECTION See_Also ##### -->
18
<!-- ##### SECTION Stability_Level ##### -->
21
<!-- ##### MACRO G_INLINE_FUNC ##### -->
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.
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.
38
<!-- ##### MACRO G_STMT_START ##### -->
40
Used within multi-statement macros so that they can be used in places where
41
only one statement is expected by the compiler.
46
<!-- ##### MACRO G_STMT_END ##### -->
48
Used within multi-statement macros so that they can be used in places where
49
only one statement is expected by the compiler.
54
<!-- ##### MACRO G_BEGIN_DECLS ##### -->
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>
63
<!-- ##### MACRO G_END_DECLS ##### -->
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>
72
<!-- ##### MACRO G_N_ELEMENTS ##### -->
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.
83
<!-- ##### MACRO G_VA_COPY ##### -->
85
Portable way to copy <type>va_list</type> variables.
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.
93
@ap1: the <type>va_list</type> variable to place a copy of @ap2 in.
94
@ap2: a <type>va_list</type>.
97
<!-- ##### MACRO G_STRINGIFY ##### -->
99
Accepts a macro or a string and converts it into a string.
102
@macro_or_string: a macro or a string.
105
<!-- ##### MACRO G_GNUC_EXTENSION ##### -->
107
Expands to <literal>__extension__</literal> when <command>gcc</command> is
108
used as the compiler.
109
This simply tells <command>gcc</command> not to warn about the following non-standard code
110
when compiling with the <option>-pedantic</option> option.
115
<!-- ##### MACRO G_GNUC_CONST ##### -->
117
Expands to the GNU C <literal>const</literal> function attribute if the compiler is
118
<command>gcc</command>. Declaring a function as const enables better optimization of calls
119
to the function. A const function doesn't examine any values except its parameters, and has no
120
effects except its return value. See the GNU C documentation for details.
123
A function that has pointer arguments and examines the data pointed to
124
must <emphasis>not</emphasis> be declared const. Likewise, a function that
125
calls a non-const function usually must not be const. It doesn't make sense
126
for a const function to return void.
131
<!-- ##### MACRO G_GNUC_PURE ##### -->
133
Expands to the GNU C <literal>pure</literal> function attribute if the compiler is
134
<command>gcc</command>. Declaring a function as pure enables better optimization of
135
calls to the function. A pure function has no effects except its return value and the
136
return value depends only on the parameters and/or global variables.
137
See the GNU C documentation for details.
142
<!-- ##### MACRO G_GNUC_MALLOC ##### -->
144
Expands to the GNU C <literal>malloc</literal> function attribute if the compiler is
145
<command>gcc</command>. Declaring a function as malloc enables better optimization of the
146
function. A function can have the malloc attribute if it returns a pointer which is guaranteed
147
to not alias with any other pointer when the function returns (in practice, this means newly
149
See the GNU C documentation for details.
155
<!-- ##### MACRO G_GNUC_DEPRECATED ##### -->
157
Expands to the GNU C <literal>deprecated</literal> attribute if the compiler
158
is <command>gcc</command>.
159
It can be used to mark typedefs, variables and functions as deprecated.
160
When called with the <option>-Wdeprecated</option> option, the compiler will
161
generate warnings when deprecated interfaces are used.
162
See the GNU C documentation for details.
168
<!-- ##### MACRO G_GNUC_NORETURN ##### -->
170
Expands to the GNU C <literal>noreturn</literal> function attribute if the
171
compiler is <command>gcc</command>. It is used for declaring functions which never return.
172
It enables optimization of the function, and avoids possible compiler
173
warnings. See the GNU C documentation for details.
178
<!-- ##### MACRO G_GNUC_UNUSED ##### -->
180
Expands to the GNU C <literal>unused</literal> function attribute if the compiler is
181
<command>gcc</command>. It is used for declaring functions which may never be used.
182
It avoids possible compiler warnings. See the GNU C documentation for details.
187
<!-- ##### MACRO G_GNUC_PRINTF ##### -->
189
Expands to the GNU C <literal>format</literal> function attribute if the compiler is
190
<command>gcc</command>. This is used for declaring functions which take a variable number of
191
arguments, with the same syntax as <function>printf()</function>.
192
It allows the compiler to type-check the arguments passed to the function.
193
See the GNU C documentation for details.
195
<informalexample><programlisting>
196
gint g_snprintf (gchar *string,
199
...) G_GNUC_PRINTF (3, 4);
200
</programlisting></informalexample>
202
@format_idx: the index of the argument corresponding to the format string.
203
(The arguments are numbered from 1).
204
@arg_idx: the index of the first of the format arguments.
207
<!-- ##### MACRO G_GNUC_SCANF ##### -->
209
Expands to the GNU C <literal>format</literal> function attribute if the compiler is <command>gcc</command>.
210
This is used for declaring functions which take a variable number of
211
arguments, with the same syntax as <function>scanf()</function>.
212
It allows the compiler to type-check the arguments passed to the function.
213
See the GNU C documentation for details.
216
@format_idx: the index of the argument corresponding to the format string.
217
(The arguments are numbered from 1).
218
@arg_idx: the index of the first of the format arguments.
221
<!-- ##### MACRO G_GNUC_FORMAT ##### -->
223
Expands to the GNU C <literal>format_arg</literal> function attribute if the compiler is <command>gcc</command>.
224
This function attribute specifies that a function takes a format
225
string for a <function>printf()</function>, <function>scanf()</function>,
226
<function>strftime()</function> or <function>strfmon()</function> style
227
function and modifies it, so that the result can be passed to a
228
<function>printf()</function>, <function>scanf()</function>,
229
<function>strftime()</function> or <function>strfmon()</function> style
230
function (with the remaining arguments to the format function the same as
231
they would have been for the unmodified string).
232
See the GNU C documentation for details.
234
<informalexample><programlisting>
235
gchar *g_dgettext (gchar *domain_name, gchar *msgid) G_GNUC_FORMAT (2);
236
</programlisting></informalexample>
238
@arg_idx: the index of the argument.
241
<!-- ##### MACRO G_GNUC_NULL_TERMINATED ##### -->
243
Expands to the GNU C <literal>sentinel</literal> function attribute if the
244
compiler is <command>gcc</command>, or "" if it isn't. This function attribute
245
only applies to variadic functions and instructs the compiler to check that
246
the argument list is terminated with an explicit %NULL.
247
See the GNU C documentation for details.
254
<!-- ##### MACRO G_GNUC_WARN_UNUSED_RESULT ##### -->
256
Expands to the GNU C <literal>warn_unused_ersult</literal> function attribute
257
if the compiler is <command>gcc</command>, or "" if it isn't. This function
258
attribute makes the compiler emit a warning if the result of a function call
259
is ignored. See the GNU C documentation for details.
265
<!-- ##### MACRO G_GNUC_FUNCTION ##### -->
267
Expands to the GNU C <literal>__FUNCTION__</literal> variable if the
268
compiler is <command>gcc</command>, or "" if it isn't. The GNU C
269
<literal>__FUNCTION__</literal> variable contains the name of the
270
current function. See the GNU C documentation for details.
275
<!-- ##### MACRO G_GNUC_PRETTY_FUNCTION ##### -->
277
Expands to the GNU C <literal>__PRETTY_FUNCTION__</literal> variable
278
if the compiler is <command>gcc</command>, or "" if it isn't.
279
The GNU C <literal>__PRETTY_FUNCTION__</literal> variable contains the
280
name of the current function. For a C program this is the same as the
281
<literal>__FUNCTION__</literal> variable but for C++ it also includes
282
extra information such as the class and function prototype. See the
283
GNU C documentation for details.
288
<!-- ##### MACRO G_GNUC_NO_INSTRUMENT ##### -->
290
Expands to the GNU C <literal>no_instrument_function</literal> function
291
attribute if the compiler is <command>gcc</command>. Functions with this
292
attribute will not be
293
instrumented for profiling, when the compiler is called with the
294
<option>-finstrument-functions</option> option.
295
See the GNU C documentation for details.
300
<!-- ##### MACRO G_HAVE_GNUC_VISIBILITY ##### -->
302
This macro is defined as 1 if the the compiler supports ELF visibility
303
attributes (currently only <command>gcc</command>).
310
<!-- ##### MACRO G_GNUC_INTERNAL ##### -->
312
Expands to the GNU C <literal>visibility(hidden)</literal> attribute if the
313
compiler supports it (currently only <command>gcc</command>). This attribute
314
can be used for marking library functions as being used internally to the lib
315
only, to not create inefficient PLT entries. Note that static functions do not
316
need to be marked as internal in this way. See the GNU C documentation for details.
323
<!-- ##### MACRO G_LIKELY ##### -->
325
Hints the compiler that the expression is likely to evaluate to a true
326
value. The compiler may use this information for optimizations.
328
<informalexample><programlisting>
329
if (G_LIKELY (random () != 1))
331
</programlisting></informalexample>
333
@expr: the expression
337
<!-- ##### MACRO G_UNLIKELY ##### -->
339
Hints the compiler that the expression is unlikely to evaluate to a true
340
value. The compiler may use this information for optimizations.
342
<informalexample><programlisting>
343
if (G_UNLIKELY (random () == 1))
344
g_print ("a random one");
345
</programlisting></informalexample>
347
@expr: the expression
351
<!-- ##### MACRO G_STRLOC ##### -->
353
Expands to a string identifying the current code position.
358
<!-- ##### MACRO G_STRFUNC ##### -->
360
Expands to a string identifying the current function.
366
<!-- ##### MACRO G_GINT16_MODIFIER ##### -->
368
The platform dependent length modifier for constructing printf() conversion
369
specifiers for values of type #gint16 or #guint16. It is a string literal,
370
but doesn't include the percent-sign, such that you can add precision and
371
length modifiers between percent-sign and conversion specifier and append a
372
conversion specifier.
376
The following example prints "0x7b";
380
g_print ("%#" G_GINT16_MODIFIER "x", value);
388
<!-- ##### MACRO G_GINT16_FORMAT ##### -->
390
This is the platform dependent conversion specifier for scanning and
391
printing values of type #gint16. It is a string literal, but doesn't
392
include the percent-sign, such that you can add precision and length
393
modifiers between percent-sign and conversion specifier.
401
sscanf ("42", "%" G_GINT16_FORMAT, &in)
403
g_print ("%" G_GINT32_FORMAT, out);
410
<!-- ##### MACRO G_GUINT16_FORMAT ##### -->
412
This is the platform dependent conversion specifier for scanning and
413
printing values of type #guint16. See also #G_GINT16_FORMAT.
418
<!-- ##### MACRO G_GINT32_MODIFIER ##### -->
420
The platform dependent length modifier for constructing printf() conversion
421
specifiers for values of type #gint32 or #guint32. See also #G_GINT16_MODIFIER.
427
<!-- ##### MACRO G_GINT32_FORMAT ##### -->
429
This is the platform dependent conversion specifier for scanning and
430
printing values of type #gint32. See also #G_GINT16_FORMAT.
435
<!-- ##### MACRO G_GUINT32_FORMAT ##### -->
437
This is the platform dependent conversion specifier for scanning and
438
printing values of type #guint32. See also #G_GINT16_FORMAT.
443
<!-- ##### MACRO G_GINT64_MODIFIER ##### -->
445
The platform dependent length modifier for constructing printf() conversion
446
specifiers for values of type #gint64 or #guint64. See also #G_GINT16_MODIFIER.
451
Some platforms do not support printing 64 bit integers,
452
even though the types are supported. On such platforms #G_GINT64_MODIFIER
460
<!-- ##### MACRO G_GINT64_FORMAT ##### -->
462
This is the platform dependent conversion specifier for scanning and
463
printing values of type #gint64. See also #G_GINT16_FORMAT.
468
Some platforms do not support scanning and printing 64 bit integers,
469
even though the types are supported. On such platforms #G_GINT64_FORMAT
470
is not defined. Note that scanf() may not support 64 bit integers, even
471
if #G_GINT64_FORMAT is defined. Due to its weak error handling, scanf() is not
472
recommended for parsing anyway; consider using g_strtoull() instead.
478
<!-- ##### MACRO G_GUINT64_FORMAT ##### -->
480
This is the platform dependent conversion specifier for scanning and
481
printing values of type #guint64. See also #G_GINT16_FORMAT.
486
Some platforms do not support scanning and printing 64 bit integers,
487
even though the types are supported. On such platforms #G_GUINT64_FORMAT
488
is not defined. Note that scanf() may not support 64 bit integers, even
489
if #G_GINT64_FORMAT is defined. Due to its weak error handling, scanf() is not
490
recommended for parsing anyway; consider using g_strtoull() instead.
496
<!-- ##### MACRO G_GSIZE_MODIFIER ##### -->
498
The platform dependent length modifier for constructing printf() conversion
499
specifiers for values of type #gsize or #gssize. See also #G_GINT16_MODIFIER.
505
<!-- ##### MACRO G_GSIZE_FORMAT ##### -->
507
This is the platform dependent conversion specifier for scanning and
508
printing values of type #gsize. See also #G_GINT16_FORMAT.
514
<!-- ##### MACRO G_GSSIZE_FORMAT ##### -->
516
This is the platform dependent conversion specifier for scanning and
517
printing values of type #gssize. See also #G_GINT16_FORMAT.
added
removed
docs/reference/glib/tmpl/macros_misc.sgml
