| <!-- ##### 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 ##### --> |
| |
| |
| <!-- ##### SECTION Image ##### --> |
| |
| |
| <!-- ##### 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 after |
| preprocessor argument expansion. |
| </para> |
| |
| @macro_or_string: a macro or a string. |
| |
| |
| <!-- ##### MACRO G_PASTE ##### --> |
| <para> |
| Yields a new preprocessor pasted identifier 'identifier1identifier2' |
| from its expanded arguments 'identifier1' and 'identifier2'. |
| </para> |
| |
| @identifier1: an identifier |
| @identifier2: an identifier |
| @Since: 2.20 |
| |
| |
| <!-- ##### MACRO G_PASTE_ARGS ##### --> |
| <para> |
| |
| </para> |
| |
| @identifier1: |
| @identifier2: |
| |
| |
| <!-- ##### MACRO G_STATIC_ASSERT ##### --> |
| <para> |
| The G_STATIC_ASSERT macro lets the programmer check a condition at compile time, |
| the condition needs to be compile time computable. |
| The macro can be used in any place where a <literal>typedef</literal> is valid. |
| The macro should only be used once per source code line. |
| </para> |
| |
| @expr: a constant expression. |
| @Since: 2.20 |
| |
| |
| <!-- ##### 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-declarations</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: Use #G_STRFUNC instead. |
| |
| |
| <!-- ##### 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: Use #G_STRFUNC instead. |
| |
| |
| <!-- ##### 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_HAVE_GNUC_VISIBILITY ##### --> |
| <para> |
| |
| </para> |
| |
| |
| |
| <!-- ##### MACRO G_GNUC_INTERNAL ##### --> |
| <para> |
| This attribute can be used for marking library functions as being used |
| internally to the library only, which may allow the compiler to handle |
| function calls more efficiently. |
| Note that static functions do not need to be marked as internal in this way. |
| See the GNU C documentation for details. |
| </para> |
| <para> |
| When using a compiler that supports the GNU C hidden visibility attribute, |
| this macro expands to <literal>__attribute__((visibility("hidden")))</literal>. |
| When using the Sun Studio compiler, it expands to <literal>__hidden</literal>. |
| </para> |
| <para> |
| Note that for portability, the attribute should be placed before the |
| function declaration. While GCC allows the macro after the declaration, |
| Sun Studio does not. |
| </para> |
| <informalexample><programlisting> |
| G_GNUC_INTERNAL |
| void _g_log_fallback_handler (const gchar *log_domain, |
| GLogLevelFlags log_level, |
| const gchar *message, |
| gpointer unused_data); |
| </programlisting></informalexample> |
| |
| Since: 2.6 |
| |
| |
| |
| <!-- ##### 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 |
| |
| |
| |
| <!-- ##### MACRO 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> |
| |
| @expr: the expression |
| @Returns: the value of @expr |
| @Since: 2.2 |
| |
| |
| <!-- ##### 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 |
| |
| |
| <!-- ##### MACRO G_GINT16_MODIFIER ##### --> |
| <para> |
| The platform dependent length modifier for conversion specifiers for scanning |
| and printing values of type #gint16 or #guint16. It is a string literal, |
| but doesn't include the percent-sign, such that you can add precision and |
| length modifiers between percent-sign and conversion specifier and append a |
| conversion specifier. |
| </para> |
| |
| <para> |
| The following example prints "0x7b"; |
| <informalexample> |
| <programlisting> |
| gint16 value = 123; |
| g_print ("%#" G_GINT16_MODIFIER "x", value); |
| </programlisting> |
| </informalexample> |
| </para> |
| |
| @Since: 2.4 |
| |
| |
| <!-- ##### MACRO G_GINT16_FORMAT ##### --> |
| <para> |
| This is the platform dependent conversion specifier for scanning and |
| printing values of type #gint16. It is a string literal, but doesn't |
| include the percent-sign, such that you can add precision and length |
| modifiers between percent-sign and conversion specifier. |
| </para> |
| |
| <para> |
| <informalexample> |
| <programlisting> |
| gint16 in; |
| gint32 out; |
| sscanf ("42", "%" G_GINT16_FORMAT, &in) |
| out = in * 1000; |
| g_print ("%" G_GINT32_FORMAT, out); |
| </programlisting> |
| </informalexample> |
| </para> |
| |
| |
| |
| <!-- ##### MACRO G_GUINT16_FORMAT ##### --> |
| <para> |
| This is the platform dependent conversion specifier for scanning and |
| printing values of type #guint16. See also #G_GINT16_FORMAT. |
| </para> |
| |
| |
| |
| <!-- ##### MACRO G_GINT32_MODIFIER ##### --> |
| <para> |
| The platform dependent length modifier for conversion specifiers for scanning |
| and printing values of type #gint32 or #guint32. It is a string literal, |
| See also #G_GINT16_MODIFIER. |
| </para> |
| |
| @Since: 2.4 |
| |
| |
| <!-- ##### MACRO G_GINT32_FORMAT ##### --> |
| <para> |
| This is the platform dependent conversion specifier for scanning and |
| printing values of type #gint32. See also #G_GINT16_FORMAT. |
| </para> |
| |
| |
| |
| <!-- ##### MACRO G_GUINT32_FORMAT ##### --> |
| <para> |
| This is the platform dependent conversion specifier for scanning and |
| printing values of type #guint32. See also #G_GINT16_FORMAT. |
| </para> |
| |
| |
| |
| <!-- ##### MACRO G_GINT64_MODIFIER ##### --> |
| <para> |
| The platform dependent length modifier for conversion specifiers for scanning |
| and printing values of type #gint64 or #guint64. It is a string literal. |
| </para> |
| |
| <note> |
| <para> |
| Some platforms do not support printing 64 bit integers, |
| even though the types are supported. On such platforms #G_GINT64_MODIFIER |
| is not defined. |
| </para> |
| </note> |
| |
| @Since: 2.4 |
| |
| |
| <!-- ##### MACRO G_GINT64_FORMAT ##### --> |
| <para> |
| This is the platform dependent conversion specifier for scanning and |
| printing values of type #gint64. See also #G_GINT16_FORMAT. |
| </para> |
| |
| <note> |
| <para> |
| Some platforms do not support scanning and printing 64 bit integers, |
| even though the types are supported. On such platforms #G_GINT64_FORMAT |
| is not defined. Note that scanf() may not support 64 bit integers, even |
| if #G_GINT64_FORMAT is defined. Due to its weak error handling, scanf() |
| is not recommended for parsing anyway; consider using g_ascii_strtoull() |
| instead. |
| </para> |
| </note> |
| |
| |
| |
| <!-- ##### MACRO G_GUINT64_FORMAT ##### --> |
| <para> |
| This is the platform dependent conversion specifier for scanning and |
| printing values of type #guint64. See also #G_GINT16_FORMAT. |
| </para> |
| |
| <note> |
| <para> |
| Some platforms do not support scanning and printing 64 bit integers, |
| even though the types are supported. On such platforms #G_GUINT64_FORMAT |
| is not defined. Note that scanf() may not support 64 bit integers, even |
| if #G_GINT64_FORMAT is defined. Due to its weak error handling, scanf() is not |
| recommended for parsing anyway; consider using g_strtoull() instead. |
| </para> |
| </note> |
| |
| |
| |
| <!-- ##### MACRO G_GSIZE_MODIFIER ##### --> |
| <para> |
| The platform dependent length modifier for conversion specifiers for scanning |
| and printing values of type #gsize or #gssize. It is a string literal, |
| </para> |
| |
| @Since: 2.6 |
| |
| |
| <!-- ##### MACRO G_GSIZE_FORMAT ##### --> |
| <para> |
| This is the platform dependent conversion specifier for scanning and |
| printing values of type #gsize. See also #G_GINT16_FORMAT. |
| </para> |
| |
| @Since: 2.6 |
| |
| |
| <!-- ##### MACRO G_GSSIZE_FORMAT ##### --> |
| <para> |
| This is the platform dependent conversion specifier for scanning and |
| printing values of type #gssize. See also #G_GINT16_FORMAT. |
| </para> |
| |
| @Since: 2.6 |
| |
| |
| <!-- ##### MACRO G_GOFFSET_MODIFIER ##### --> |
| <para> |
| The platform dependent length modifier for conversion specifiers for scanning |
| and printing values of type #goffset. It is a string literal. See also |
| #G_GINT64_MODIFIER. |
| </para> |
| |
| @Since: 2.20 |
| |
| |
| <!-- ##### MACRO G_GOFFSET_FORMAT ##### --> |
| <para> |
| This is the platform dependent conversion specifier for scanning and |
| printing values of type #goffset. See also #G_GINT64_FORMAT. |
| </para> |
| |
| Since: 2.20 |
| |
| |
| |
| <!-- ##### MACRO G_GINTPTR_MODIFIER ##### --> |
| <para> |
| The platform dependent length modifier for conversion specifiers for scanning |
| and printing values of type #gintptr or #guintptr. It is a string literal. |
| </para> |
| |
| @Since: 2.22 |
| |
| |
| <!-- ##### MACRO G_GINTPTR_FORMAT ##### --> |
| <para> |
| This is the platform dependent conversion specifier for scanning and |
| printing values of type #gintptr. |
| </para> |
| |
| @Since: 2.22 |
| |
| |
| <!-- ##### MACRO G_GUINTPTR_FORMAT ##### --> |
| <para> |
| This is the platform dependent conversion specifier for scanning and |
| printing values of type #guintptr. |
| </para> |
| |
| @Since: 2.22 |
| |
| |