* This library is free software; you can redistribute it and/or
* modify it under the terms of the GNU Lesser General Public
* License as published by the Free Software Foundation; either
- * version 2 of the licence, or (at your option) any later version.
+ * version 2.1 of the License, or (at your option) any later version.
*
* This library is distributed in the hope that it will be useful,
* but WITHOUT ANY WARRANTY; without even the implied warranty of
* and portability
*
* GLib defines a number of commonly used types, which can be divided
- * into 4 groups:
+ * into several groups:
* - New types which are not part of standard C (but are defined in
- * various C standard library header files) - #gboolean, #gsize,
- * #gssize, #goffset, #gintptr, #guintptr.
+ * various C standard library header files) — #gboolean, #gssize.
* - Integer types which are guaranteed to be the same size across
- * all platforms - #gint8, #guint8, #gint16, #guint16, #gint32,
+ * all platforms — #gint8, #guint8, #gint16, #guint16, #gint32,
* #guint32, #gint64, #guint64.
* - Types which are easier to use than their standard C counterparts -
* #gpointer, #gconstpointer, #guchar, #guint, #gushort, #gulong.
* - Types which correspond exactly to standard C types, but are
- * included for completeness - #gchar, #gint, #gshort, #glong,
+ * included for completeness — #gchar, #gint, #gshort, #glong,
* #gfloat, #gdouble.
+ * - Types which correspond exactly to standard C99 types, but are available
+ * to use even if your compiler does not support C99 — #gsize, #goffset,
+ * #gintptr, #guintptr.
*
* GLib also defines macros for the limits of some of the standard
* integer and floating point types, as well as macros for suitable
/**
* G_GNUC_CHECK_VERSION:
+ * @major: major version to check against
+ * @minor: minor version to check against
*
* Expands to a a check for a compiler with __GNUC__ defined and a version
* greater than or equal to the major and minor numbers provided. For example,
/**
* G_GNUC_PRINTF:
* @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
+ * format string (the arguments are numbered from 1)
+ * @arg_idx: the index of the first of the format arguments, or 0 if
+ * there are no format arguments
*
* Expands to the GNU C format function attribute if the compiler is gcc.
* This is used for declaring functions which take a variable number of
* Place the attribute after the function declaration, just before the
* semicolon.
*
- * See the GNU C documentation for more details.
+ * See the
+ * [GNU C documentation](https://gcc.gnu.org/onlinedocs/gcc/Common-Function-Attributes.html#index-Wformat-3288)
+ * for more details.
*
* |[<!-- language="C" -->
* gint g_snprintf (gchar *string,
/**
* G_GNUC_SCANF:
* @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
+ * the format string (the arguments are numbered from 1)
+ * @arg_idx: the index of the first of the format arguments, or 0 if
+ * there are no format arguments
*
* Expands to the GNU C format function attribute if the compiler is gcc.
* This is used for declaring functions which take a variable number of
* arguments, with the same syntax as scanf(). It allows the compiler
* to type-check the arguments passed to the function.
*
- * See the GNU C documentation for details.
+ * See the
+ * [GNU C documentation](https://gcc.gnu.org/onlinedocs/gcc/Common-Function-Attributes.html#index-Wformat-3288)
+ * for details.
*/
/**
*
* membuf = g_malloc (8192);
*
- * /* Some computation on membuf */
+ * /<!-- -->* Some computation on membuf *<!-- -->/
*
- * /* membuf will be automatically freed here */
+ * /<!-- -->* membuf will be automatically freed here *<!-- -->/
* return TRUE;
* }
* ]|
*/
/**
+ * g_autolist:
+ * @TypeName: a supported variable type
+ *
+ * Helper to declare a list variable with automatic deep cleanup.
+ *
+ * The list is deeply freed, in a way appropriate to the specified type, when the
+ * variable goes out of scope. The type must support this.
+ *
+ * This feature is only supported on GCC and clang. This macro is not
+ * defined on other compilers and should not be used in programs that
+ * are intended to be portable to those compilers.
+ *
+ * This is meant to be used to declare lists of a type with a cleanup
+ * function. The type of the variable is a GList *. You
+ * must not add your own '*'.
+ *
+ * This macro can be used to avoid having to do explicit cleanups of
+ * local variables when exiting functions. It often vastly simplifies
+ * handling of error conditions, removing the need for various tricks
+ * such as 'goto out' or repeating of cleanup code. It is also helpful
+ * for non-error cases.
+ *
+ * See also g_autoslist(), g_autoptr() and g_steal_pointer().
+ *
+ * Since: 2.56
+ */
+
+/**
+ * g_autoslist:
+ * @TypeName: a supported variable type
+ *
+ * Helper to declare a singly linked list variable with automatic deep cleanup.
+ *
+ * The list is deeply freed, in a way appropriate to the specified type, when the
+ * variable goes out of scope. The type must support this.
+ *
+ * This feature is only supported on GCC and clang. This macro is not
+ * defined on other compilers and should not be used in programs that
+ * are intended to be portable to those compilers.
+ *
+ * This is meant to be used to declare lists of a type with a cleanup
+ * function. The type of the variable is a GSList *. You
+ * must not add your own '*'.
+ *
+ * This macro can be used to avoid having to do explicit cleanups of
+ * local variables when exiting functions. It often vastly simplifies
+ * handling of error conditions, removing the need for various tricks
+ * such as 'goto out' or repeating of cleanup code. It is also helpful
+ * for non-error cases.
+ *
+ * See also g_autolist(), g_autoptr() and g_steal_pointer().
+ *
+ * Since: 2.56
+ */
+
+/**
* G_DEFINE_AUTOPTR_CLEANUP_FUNC:
* @TypeName: a type name to define a g_autoptr() cleanup function for
* @func: the cleanup function