path: root/docs/reference/glib/tmpl/macros_misc.sgml

<!-- ##### SECTION Title ##### -->
Miscellaneous Macros

<!-- ##### SECTION Short_Description ##### -->
specialized macros which are not used often

<!-- ##### SECTION Long_Description ##### -->
<para>
These macros provide more specialized features which are not needed so often
by application programmers.
</para>

<!-- ##### SECTION See_Also ##### -->
<para>

</para>

<!-- ##### SECTION Stability_Level ##### -->


<!-- ##### MACRO G_INLINE_FUNC ##### -->
<para>
This macro is used to export function prototypes so they can be linked
with an external version when no inlining is performed. The file which
implements the functions should define %G_IMPLEMENTS_INLINES
before including the headers which contain %G_INLINE_FUNC declarations.
Since inlining is very compiler-dependent using these macros correctly
is very difficult. Their use is strongly discouraged.
</para>
<para>
This macro is often mistaken for a replacement for the inline keyword;
inline is already declared in a portable manner in the glib headers
and can be used normally.
</para>



<!-- ##### MACRO G_STMT_START ##### -->
<para>
Used within multi-statement macros so that they can be used in places where
only one statement is expected by the compiler.
</para>



<!-- ##### MACRO G_STMT_END ##### -->
<para>
Used within multi-statement macros so that they can be used in places where
only one statement is expected by the compiler.
</para>



<!-- ##### MACRO G_BEGIN_DECLS ##### -->
<para>
Used (along with #G_END_DECLS) to bracket header files. If the
compiler in use is a C++ compiler, adds <literal>extern "C"</literal> 
around the header.
</para>



<!-- ##### MACRO G_END_DECLS ##### -->
<para>
Used (along with #G_BEGIN_DECLS) to bracket header files. If the
compiler in use is a C++ compiler, adds <literal>extern "C"</literal> 
around the header.
</para>



<!-- ##### MACRO G_N_ELEMENTS ##### -->
<para>
Determines the number of elements in an array. The array must be
declared so the compiler knows its size at compile-time; this 
macro will not work on an array allocated on the heap, only static
arrays or arrays on the stack.
</para>

@arr: the array


<!-- ##### MACRO G_VA_COPY ##### -->
<para>
Portable way to copy <type>va_list</type> variables.
</para>
<para>
In order to use this function, you must include <filename>string.h</filename> 
yourself, because this macro may use <function>memmove()</function> and GLib 
does not include <function>string.h</function> for you.
</para>

@ap1: the <type>va_list</type> variable to place a copy of @ap2 in.
@ap2: a <type>va_list</type>.


<!-- ##### MACRO G_STRINGIFY ##### -->
<para>
Accepts a macro or a string and converts it into a string.
</para>

@macro_or_string: a macro or a string.


<!-- ##### MACRO G_GNUC_EXTENSION ##### -->
<para>
Expands to <literal>__extension__</literal> when <command>gcc</command> is 
used as the compiler.
This simply tells <command>gcc</command> not to warn about the following non-standard code
when compiling with the <option>-pedantic</option> option.
</para>



<!-- ##### MACRO G_GNUC_CONST ##### -->
<para>
Expands to the GNU C <literal>const</literal> function attribute if the compiler is 
<command>gcc</command>. Declaring a function as const enables better optimization of calls 
to the function. A const function doesn't examine any values except its parameters, and has no 
effects except its return value. See the GNU C documentation for details. 
</para>
<note><para>
A function that has pointer arguments and examines the data pointed to 
must <emphasis>not</emphasis> be declared const. Likewise, a function that 
calls a non-const function usually must not be const. It doesn't make sense 
for a const function to return void.
</para></note>



<!-- ##### MACRO G_GNUC_PURE ##### -->
<para>
Expands to the GNU C <literal>pure</literal> function attribute if the compiler is 
<command>gcc</command>. Declaring a function as pure enables better optimization of 
calls to the function. A pure function has no effects except its return value and the 
return value depends only on the parameters and/or global variables.
See the GNU C documentation for details. 
</para>



<!-- ##### MACRO G_GNUC_MALLOC ##### -->
<para>
Expands to the GNU C <literal>malloc</literal> function attribute if the 
compiler is <command>gcc</command>. Declaring a function as malloc enables 
better optimization of the function. A function can have the malloc attribute 
if it returns a pointer which is guaranteed to not alias with any other pointer
when the function returns (in practice, this means newly allocated memory).  
See the GNU C documentation for details. 
</para>

@Since: 2.6


<!-- ##### MACRO G_GNUC_ALLOC_SIZE ##### -->
<para>
Expands to the GNU C <literal>alloc_size</literal> function attribute if the 
compiler is a new enough <command>gcc</command>. This attribute tells the
compiler that the function returns a pointer to memory of a size that is
specified by the @x<!-- -->th function parameter.
See the GNU C documentation for details. 
</para>

@x: the index of the argument specifying the allocation size
@Since: 2.18


<!-- ##### MACRO G_GNUC_ALLOC_SIZE2 ##### -->
<para>
Expands to the GNU C <literal>alloc_size</literal> function attribute if the 
compiler is a new enough <command>gcc</command>. This attribute tells the
compiler that the function returns a pointer to memory of a size that is
specified by the product of two function parameters.
See the GNU C documentation for details. 
</para>

@x: the index of the argument specifying one factor of the allocation size
@y: the index of the argument specifying the second factor of the allocation size
@Since: 2.18


<!-- ##### MACRO G_GNUC_DEPRECATED ##### -->
<para>
Expands to the GNU C <literal>deprecated</literal> attribute if the compiler 
is <command>gcc</command>.
It can be used to mark typedefs, variables and functions as deprecated. 
When called with the <option>-Wdeprecated</option> option, the compiler will 
generate warnings when deprecated interfaces are used.
See the GNU C documentation for details. 
</para>

@Since: 2.2


<!-- ##### MACRO G_GNUC_NORETURN ##### -->
<para>
Expands to the GNU C <literal>noreturn</literal> function attribute if the 
compiler is <command>gcc</command>. It is used for declaring functions which never return.
It enables optimization of the function, and avoids possible compiler
warnings. See the GNU C documentation for details. 
</para>



<!-- ##### MACRO G_GNUC_UNUSED ##### -->
<para>
Expands to the GNU C <literal>unused</literal> function attribute if the compiler is 
<command>gcc</command>. It is used for declaring functions which may never be used.
It avoids possible compiler warnings. See the GNU C documentation for details. 
</para>



<!-- ##### MACRO G_GNUC_PRINTF ##### -->
<para>
Expands to the GNU C <literal>format</literal> function attribute if the compiler is 
<command>gcc</command>. This is used for declaring functions which take a variable number of
arguments, with the same syntax as <function>printf()</function>.
It allows the compiler to type-check the arguments passed to the function.
See the GNU C documentation for details. 
</para>
<informalexample><programlisting>
gint g_snprintf (gchar  *string,
                 gulong       n,
                 gchar const *format,
                 ...) G_GNUC_PRINTF (3, 4);
</programlisting></informalexample>

@format_idx: the index of the argument corresponding to the format string.
(The arguments are numbered from 1).
@arg_idx: the index of the first of the format arguments.


<!-- ##### MACRO G_GNUC_SCANF ##### -->
<para>
Expands to the GNU C <literal>format</literal> function attribute if the compiler is <command>gcc</command>.
This is used for declaring functions which take a variable number of
arguments, with the same syntax as <function>scanf()</function>.
It allows the compiler to type-check the arguments passed to the function.
See the GNU C documentation for details. 
</para>

@format_idx: the index of the argument corresponding to the format string.
(The arguments are numbered from 1).
@arg_idx: the index of the first of the format arguments.


<!-- ##### MACRO G_GNUC_FORMAT ##### -->
<para>
Expands to the GNU C <literal>format_arg</literal> function attribute if the compiler is <command>gcc</command>.
This function attribute specifies that a function takes a format
string for a <function>printf()</function>, <function>scanf()</function>, 
<function>strftime()</function> or <function>strfmon()</function> style
function and modifies it, so that the result can be passed to a 
<function>printf()</function>, <function>scanf()</function>, 
<function>strftime()</function> or <function>strfmon()</function> style 
function (with the remaining arguments to the format function the same as 
they would have been for the unmodified string). 
See the GNU C documentation for details. 
</para>
<informalexample><programlisting>
gchar *g_dgettext (gchar *domain_name, gchar *msgid) G_GNUC_FORMAT (2);
</programlisting></informalexample>

@arg_idx: the index of the argument.


<!-- ##### MACRO G_GNUC_NULL_TERMINATED ##### -->
<para>
Expands to the GNU C <literal>sentinel</literal> function attribute if the 
compiler is <command>gcc</command>, or "" if it isn't. This function attribute
only applies to variadic functions and instructs the compiler to check that 
the argument list is terminated with an explicit %NULL.
See the GNU C documentation for details. 
</para>

Since: 2.8



<!-- ##### MACRO G_GNUC_WARN_UNUSED_RESULT ##### -->
<para>
Expands to the GNU C <literal>warn_unused_result</literal> function attribute 
if the compiler is <command>gcc</command>, or "" if it isn't. This function 
attribute makes the compiler emit a warning if the result of a function call
is ignored. See the GNU C documentation for details. 
</para>

@Since: 2.10


<!-- ##### MACRO G_GNUC_FUNCTION ##### -->
<para>
Expands to "" on all modern compilers, and to <literal>__FUNCTION__</literal>
on <command>gcc</command> version 2.x. Don't use it.
</para>

@Deprecated: 2.16


<!-- ##### MACRO G_GNUC_PRETTY_FUNCTION ##### -->
<para>
Expands to "" on all modern compilers, and to 
<literal>__PRETTY_FUNCTION__</literal> on <command>gcc</command> version 2.x. 
Don't use it.
</para>

@Deprecated: 2.16


<!-- ##### MACRO G_GNUC_NO_INSTRUMENT ##### -->
<para>
Expands to the GNU C <literal>no_instrument_function</literal> function 
attribute if the compiler is <command>gcc</command>. Functions with this 
attribute will not be 
instrumented for profiling, when the compiler is called with the
<option>-finstrument-functions</option> option.
See the GNU C documentation for details. 
</para>



<!-- ##### MACRO G_GNUC_MAY_ALIAS ##### -->
<para>
Expands to the GNU C <literal>may_alias</literal> type attribute 
if the compiler is <command>gcc</command>. Types with this attribute 
will not be subjected to type-based alias analysis, but are assumed
to alias with any other type, just like char.
See the GNU C documentation for details. 
</para>

Since: 2.14



<!-- ##### FUNCTION G_LIKELY ##### -->
<para>
Hints the compiler that the expression is likely to evaluate to a true
value. The compiler may use this information for optimizations.
</para>
<informalexample><programlisting>
if (G_LIKELY (random () != 1))
  g_print ("not one");
</programlisting></informalexample>

@Returns: the value of @expr
@Since: 2.2
<!-- # Unused Parameters # -->
@expr: the expression


<!-- ##### MACRO G_UNLIKELY ##### -->
<para>
Hints the compiler that the expression is unlikely to evaluate to a true
value. The compiler may use this information for optimizations.
</para>
<informalexample><programlisting>
if (G_UNLIKELY (random () == 1))
  g_print ("a random one");
</programlisting></informalexample>

@expr: the expression
@Returns: the value of @expr
@Since: 2.2


<!-- ##### MACRO G_STRLOC ##### -->
<para>
Expands to a string identifying the current code position. 
</para>



<!-- ##### MACRO G_STRFUNC ##### -->
<para>
Expands to a string identifying the current function. 
</para>

@Since: 2.4