mirror of
https://gitlab.gnome.org/GNOME/glib.git
synced 2024-12-26 23:46:15 +01:00
Merge branch 'g-gnuc-unused-docs' into 'master'
Improve formatting of GCC attribute documentation See merge request GNOME/glib!717
This commit is contained in:
Simon McVittie
commit
8ec492ba4e
335
glib/docs.c
335
glib/docs.c
@ -2038,157 +2038,6 @@
|
||||
* Since: 2.42
|
||||
*/
|
||||
|
||||
/**
|
||||
* G_GNUC_CONST:
|
||||
*
|
||||
* Expands to the GNU C const function attribute if the compiler is gcc.
|
||||
* 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.
|
||||
*
|
||||
* Place the attribute after the declaration, just before the semicolon.
|
||||
*
|
||||
* See the GNU C documentation for more details.
|
||||
*
|
||||
* A function that has pointer arguments and examines the data pointed to
|
||||
* must not 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.
|
||||
*/
|
||||
|
||||
/**
|
||||
* G_GNUC_PURE:
|
||||
*
|
||||
* Expands to the GNU C pure function attribute if the compiler is gcc.
|
||||
* 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.
|
||||
*
|
||||
* Place the attribute after the declaration, just before the semicolon.
|
||||
*
|
||||
* See the GNU C documentation for more details.
|
||||
*/
|
||||
|
||||
/**
|
||||
* G_GNUC_NO_INLINE:
|
||||
*
|
||||
* Expands to the GNU C `noinline` function attribute if the compiler is gcc.
|
||||
* If the compiler is not gcc, this macro expands to nothing.
|
||||
*
|
||||
* Declaring a function as `noinline` prevents the function from being
|
||||
* considered for inlining.
|
||||
*
|
||||
* The attribute may be placed before the declaration, right before the
|
||||
* `static` keyword.
|
||||
*
|
||||
* See the
|
||||
* [GNU C documentation](https://gcc.gnu.org/onlinedocs/gcc/Common-Function-Attributes.html#index-noinline-function-attribute)
|
||||
* for more details.
|
||||
*
|
||||
* Since: 2.58
|
||||
*/
|
||||
|
||||
/**
|
||||
* G_GNUC_MALLOC:
|
||||
*
|
||||
* Expands to the
|
||||
* [GNU C `malloc` function attribute](https://gcc.gnu.org/onlinedocs/gcc/Common-Function-Attributes.html#index-functions-that-behave-like-malloc)
|
||||
* if the compiler is gcc.
|
||||
* Declaring a function as `malloc` enables better optimization of the function,
|
||||
* but must only be done if the allocation behaviour of the function is fully
|
||||
* understood, otherwise miscompilation can result.
|
||||
*
|
||||
* A function can have the `malloc` attribute if it returns a pointer which is
|
||||
* guaranteed to not alias with any other pointer valid when the function
|
||||
* returns, and moreover no pointers to valid objects occur in any storage
|
||||
* addressed by the returned pointer.
|
||||
*
|
||||
* In practice, this means that `G_GNUC_MALLOC` can be used with any function
|
||||
* which returns unallocated or zeroed-out memory, but not with functions which
|
||||
* return initialised structures containing other pointers, or with functions
|
||||
* that reallocate memory. This definition changed in GLib 2.58 to match the
|
||||
* stricter definition introduced around GCC 5.
|
||||
*
|
||||
* Place the attribute after the declaration, just before the semicolon.
|
||||
*
|
||||
* See the
|
||||
* [GNU C documentation](https://gcc.gnu.org/onlinedocs/gcc/Common-Function-Attributes.html#index-functions-that-behave-like-malloc)
|
||||
* for more details.
|
||||
*
|
||||
* Since: 2.6
|
||||
*/
|
||||
|
||||
/**
|
||||
* G_GNUC_ALLOC_SIZE:
|
||||
* @x: the index of the argument specifying the allocation size
|
||||
*
|
||||
* Expands to the GNU C alloc_size function attribute if the compiler
|
||||
* is a new enough gcc. This attribute tells the compiler that the
|
||||
* function returns a pointer to memory of a size that is specified
|
||||
* by the @xth function parameter.
|
||||
*
|
||||
* Place the attribute after the function declaration, just before the
|
||||
* semicolon.
|
||||
*
|
||||
* See the GNU C documentation for more details.
|
||||
*
|
||||
* Since: 2.18
|
||||
*/
|
||||
|
||||
/**
|
||||
* G_GNUC_ALLOC_SIZE2:
|
||||
* @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
|
||||
*
|
||||
* Expands to the GNU C alloc_size function attribute if the compiler is a
|
||||
* new enough gcc. 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.
|
||||
*
|
||||
* Place the attribute after the function declaration, just before the
|
||||
* semicolon.
|
||||
*
|
||||
* See the GNU C documentation for more details.
|
||||
*
|
||||
* Since: 2.18
|
||||
*/
|
||||
|
||||
/**
|
||||
* G_GNUC_DEPRECATED:
|
||||
*
|
||||
* Expands to the GNU C deprecated attribute if the compiler is gcc.
|
||||
* It can be used to mark typedefs, variables and functions as deprecated.
|
||||
* When called with the `-Wdeprecated-declarations` option,
|
||||
* gcc will generate warnings when deprecated interfaces are used.
|
||||
*
|
||||
* Place the attribute after the declaration, just before the semicolon.
|
||||
*
|
||||
* See the GNU C documentation for more details.
|
||||
*
|
||||
* Since: 2.2
|
||||
*/
|
||||
|
||||
/**
|
||||
* G_GNUC_DEPRECATED_FOR:
|
||||
* @f: the intended replacement for the deprecated symbol,
|
||||
* such as the name of a function
|
||||
*
|
||||
* Like %G_GNUC_DEPRECATED, but names the intended replacement for the
|
||||
* deprecated symbol if the version of gcc in use is new enough to support
|
||||
* custom deprecation messages.
|
||||
*
|
||||
* Place the attribute after the declaration, just before the semicolon.
|
||||
*
|
||||
* See the GNU C documentation for more details.
|
||||
*
|
||||
* Note that if @f is a macro, it will be expanded in the warning message.
|
||||
* You can enclose it in quotes to prevent this. (The quotes will show up
|
||||
* in the warning, but it's better than showing the macro expansion.)
|
||||
*
|
||||
* Since: 2.26
|
||||
*/
|
||||
|
||||
/**
|
||||
* G_GNUC_BEGIN_IGNORE_DEPRECATIONS:
|
||||
*
|
||||
@ -2264,165 +2113,6 @@
|
||||
* of deprecated GLib APIs.
|
||||
*/
|
||||
|
||||
/**
|
||||
* G_GNUC_NORETURN:
|
||||
*
|
||||
* Expands to the GNU C noreturn function attribute if the compiler is gcc.
|
||||
* It is used for declaring functions which never return. It enables
|
||||
* optimization of the function, and avoids possible compiler warnings.
|
||||
*
|
||||
* Place the attribute after the declaration, just before the semicolon.
|
||||
*
|
||||
* See the GNU C documentation for more details.
|
||||
*/
|
||||
|
||||
/**
|
||||
* G_GNUC_FALLTHROUGH:
|
||||
*
|
||||
* Expands to the GNU C fallthrough statement attribute if the compiler is gcc.
|
||||
* This allows declaring case statement to explicitly fall through in switch
|
||||
* statements. To enable this feature, use -Wimplicit-fallthrough during
|
||||
* compilation.
|
||||
*
|
||||
* Put the attribute right before the case statement you want to fall through
|
||||
* to.
|
||||
*
|
||||
* See the GNU C documentation for more details.
|
||||
*
|
||||
* Since: 2.60
|
||||
*/
|
||||
|
||||
/**
|
||||
* G_GNUC_UNUSED:
|
||||
*
|
||||
* Expands to the GNU C unused function attribute if the compiler is gcc.
|
||||
* It is used for declaring functions and arguments which may never be used.
|
||||
* It avoids possible compiler warnings.
|
||||
*
|
||||
* For functions, place the attribute after the declaration, just before the
|
||||
* semicolon. For arguments, place the attribute at the beginning of the
|
||||
* argument declaration.
|
||||
*
|
||||
* |[<!-- language="C" -->
|
||||
* void my_unused_function (G_GNUC_UNUSED gint unused_argument,
|
||||
* gint other_argument) G_GNUC_UNUSED;
|
||||
* ]|
|
||||
*
|
||||
* See the GNU C documentation for more details.
|
||||
*/
|
||||
|
||||
/**
|
||||
* 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, 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 printf(). It allows the compiler
|
||||
* to type-check the arguments passed to the function.
|
||||
*
|
||||
* Place the attribute after the function declaration, just before the
|
||||
* semicolon.
|
||||
*
|
||||
* 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,
|
||||
* gulong n,
|
||||
* gchar const *format,
|
||||
* ...) G_GNUC_PRINTF (3, 4);
|
||||
* ]|
|
||||
*/
|
||||
|
||||
/**
|
||||
* 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, 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](https://gcc.gnu.org/onlinedocs/gcc/Common-Function-Attributes.html#index-Wformat-3288)
|
||||
* for details.
|
||||
*/
|
||||
|
||||
/**
|
||||
* G_GNUC_STRFTIME:
|
||||
* @format_idx: the index of the argument corresponding to
|
||||
* the format string (the arguments are numbered from 1)
|
||||
*
|
||||
* Expands to the GNU C strftime format function attribute if the compiler
|
||||
* is gcc. This is used for declaring functions which take a format argument
|
||||
* which is passed to strftime() or an API implementing its formats. It allows
|
||||
* the compiler check the format passed to the function.
|
||||
*
|
||||
* See the
|
||||
* [GNU C documentation](https://gcc.gnu.org/onlinedocs/gcc/Common-Function-Attributes.html#index-Wformat-3288)
|
||||
* for details.
|
||||
*
|
||||
* Since: 2.60
|
||||
*/
|
||||
|
||||
/**
|
||||
* G_GNUC_FORMAT:
|
||||
* @arg_idx: the index of the argument
|
||||
*
|
||||
* Expands to the GNU C format_arg function attribute if the compiler
|
||||
* is gcc. This function attribute specifies that a function takes a
|
||||
* format string for a printf(), scanf(), strftime() or strfmon() style
|
||||
* function and modifies it, so that the result can be passed to a printf(),
|
||||
* scanf(), strftime() or strfmon() style function (with the remaining
|
||||
* arguments to the format function the same as they would have been
|
||||
* for the unmodified string).
|
||||
*
|
||||
* Place the attribute after the function declaration, just before the
|
||||
* semicolon.
|
||||
*
|
||||
* See the GNU C documentation for more details.
|
||||
*
|
||||
* |[<!-- language="C" -->
|
||||
* gchar *g_dgettext (gchar *domain_name, gchar *msgid) G_GNUC_FORMAT (2);
|
||||
* ]|
|
||||
*/
|
||||
|
||||
/**
|
||||
* G_GNUC_NULL_TERMINATED:
|
||||
*
|
||||
* Expands to the GNU C sentinel function attribute if the compiler is gcc.
|
||||
* This function attribute only applies to variadic functions and instructs
|
||||
* the compiler to check that the argument list is terminated with an
|
||||
* explicit %NULL.
|
||||
*
|
||||
* Place the attribute after the declaration, just before the semicolon.
|
||||
*
|
||||
* See the GNU C documentation for more details.
|
||||
*
|
||||
* Since: 2.8
|
||||
*/
|
||||
|
||||
/**
|
||||
* G_GNUC_WARN_UNUSED_RESULT:
|
||||
*
|
||||
* Expands to the GNU C warn_unused_result function attribute if the compiler
|
||||
* is gcc. This function attribute makes the compiler emit a warning if the
|
||||
* result of a function call is ignored.
|
||||
*
|
||||
* Place the attribute after the declaration, just before the semicolon.
|
||||
*
|
||||
* See the GNU C documentation for more details.
|
||||
*
|
||||
* Since: 2.10
|
||||
*/
|
||||
|
||||
/**
|
||||
* G_GNUC_FUNCTION:
|
||||
*
|
||||
@ -2441,19 +2131,6 @@
|
||||
* Deprecated: 2.16: Use G_STRFUNC() instead
|
||||
*/
|
||||
|
||||
/**
|
||||
* G_GNUC_NO_INSTRUMENT:
|
||||
*
|
||||
* Expands to the GNU C no_instrument_function function attribute if the
|
||||
* compiler is gcc. Functions with this attribute will not be instrumented
|
||||
* for profiling, when the compiler is called with the
|
||||
* `-finstrument-functions` option.
|
||||
*
|
||||
* Place the attribute after the declaration, just before the semicolon.
|
||||
*
|
||||
* See the GNU C documentation for more details.
|
||||
*/
|
||||
|
||||
/**
|
||||
* G_GNUC_INTERNAL:
|
||||
*
|
||||
@ -2482,18 +2159,6 @@
|
||||
* Since: 2.6
|
||||
*/
|
||||
|
||||
/**
|
||||
* G_GNUC_MAY_ALIAS:
|
||||
*
|
||||
* Expands to the GNU C may_alias type attribute if the compiler is gcc.
|
||||
* 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.
|
||||
*
|
||||
* Since: 2.14
|
||||
*/
|
||||
|
||||
/**
|
||||
* G_LIKELY:
|
||||
* @expr: the expression
|
||||
|
||||
329
glib/gmacros.h
329
glib/gmacros.h
@ -94,6 +94,70 @@
|
||||
|
||||
/* Provide macros to feature the GCC function attribute.
|
||||
*/
|
||||
|
||||
/**
|
||||
* G_GNUC_PURE:
|
||||
*
|
||||
* Expands to the GNU C `pure` function attribute if the compiler is gcc.
|
||||
* 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.
|
||||
*
|
||||
* Place the attribute after the declaration, just before the semicolon.
|
||||
*
|
||||
* See the [GNU C documentation](https://gcc.gnu.org/onlinedocs/gcc/Common-Function-Attributes.html#index-pure-function-attribute) for more details.
|
||||
*/
|
||||
|
||||
/**
|
||||
* G_GNUC_MALLOC:
|
||||
*
|
||||
* Expands to the
|
||||
* [GNU C `malloc` function attribute](https://gcc.gnu.org/onlinedocs/gcc/Common-Function-Attributes.html#index-functions-that-behave-like-malloc)
|
||||
* if the compiler is gcc.
|
||||
* Declaring a function as `malloc` enables better optimization of the function,
|
||||
* but must only be done if the allocation behaviour of the function is fully
|
||||
* understood, otherwise miscompilation can result.
|
||||
*
|
||||
* A function can have the `malloc` attribute if it returns a pointer which is
|
||||
* guaranteed to not alias with any other pointer valid when the function
|
||||
* returns, and moreover no pointers to valid objects occur in any storage
|
||||
* addressed by the returned pointer.
|
||||
*
|
||||
* In practice, this means that `G_GNUC_MALLOC` can be used with any function
|
||||
* which returns unallocated or zeroed-out memory, but not with functions which
|
||||
* return initialised structures containing other pointers, or with functions
|
||||
* that reallocate memory. This definition changed in GLib 2.58 to match the
|
||||
* stricter definition introduced around GCC 5.
|
||||
*
|
||||
* Place the attribute after the declaration, just before the semicolon.
|
||||
*
|
||||
* See the
|
||||
* [GNU C documentation](https://gcc.gnu.org/onlinedocs/gcc/Common-Function-Attributes.html#index-functions-that-behave-like-malloc)
|
||||
* for more details.
|
||||
*
|
||||
* Since: 2.6
|
||||
*/
|
||||
|
||||
/**
|
||||
* G_GNUC_NO_INLINE:
|
||||
*
|
||||
* Expands to the GNU C `noinline` function attribute if the compiler is gcc.
|
||||
* If the compiler is not gcc, this macro expands to nothing.
|
||||
*
|
||||
* Declaring a function as `noinline` prevents the function from being
|
||||
* considered for inlining.
|
||||
*
|
||||
* The attribute may be placed before the declaration, right before the
|
||||
* `static` keyword.
|
||||
*
|
||||
* See the
|
||||
* [GNU C documentation](https://gcc.gnu.org/onlinedocs/gcc/Common-Function-Attributes.html#index-noinline-function-attribute)
|
||||
* for more details.
|
||||
*
|
||||
* Since: 2.58
|
||||
*/
|
||||
|
||||
#if __GNUC__ > 2 || (__GNUC__ == 2 && __GNUC_MINOR__ >= 96)
|
||||
#define G_GNUC_PURE __attribute__((__pure__))
|
||||
#define G_GNUC_MALLOC __attribute__((__malloc__))
|
||||
@ -104,6 +168,20 @@
|
||||
#define G_GNUC_NO_INLINE
|
||||
#endif
|
||||
|
||||
/**
|
||||
* G_GNUC_NULL_TERMINATED:
|
||||
*
|
||||
* Expands to the GNU C `sentinel` function attribute if the compiler is gcc.
|
||||
* This function attribute only applies to variadic functions and instructs
|
||||
* the compiler to check that the argument list is terminated with an
|
||||
* explicit %NULL.
|
||||
*
|
||||
* Place the attribute after the declaration, just before the semicolon.
|
||||
*
|
||||
* See the [GNU C documentation](https://gcc.gnu.org/onlinedocs/gcc/Common-Function-Attributes.html#index-sentinel-function-attribute) for more details.
|
||||
*
|
||||
* Since: 2.8
|
||||
*/
|
||||
#if __GNUC__ >= 4
|
||||
#define G_GNUC_NULL_TERMINATED __attribute__((__sentinel__))
|
||||
#else
|
||||
@ -150,6 +228,40 @@
|
||||
#define g_macro__has_builtin(x) 0
|
||||
#endif
|
||||
|
||||
/**
|
||||
* G_GNUC_ALLOC_SIZE:
|
||||
* @x: the index of the argument specifying the allocation size
|
||||
*
|
||||
* Expands to the GNU C `alloc_size` function attribute if the compiler
|
||||
* is a new enough gcc. This attribute tells the compiler that the
|
||||
* function returns a pointer to memory of a size that is specified
|
||||
* by the @xth function parameter.
|
||||
*
|
||||
* Place the attribute after the function declaration, just before the
|
||||
* semicolon.
|
||||
*
|
||||
* See the [GNU C documentation](https://gcc.gnu.org/onlinedocs/gcc/Common-Function-Attributes.html#index-alloc_005fsize-function-attribute) for more details.
|
||||
*
|
||||
* Since: 2.18
|
||||
*/
|
||||
|
||||
/**
|
||||
* G_GNUC_ALLOC_SIZE2:
|
||||
* @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
|
||||
*
|
||||
* Expands to the GNU C `alloc_size` function attribute if the compiler is a
|
||||
* new enough gcc. 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.
|
||||
*
|
||||
* Place the attribute after the function declaration, just before the
|
||||
* semicolon.
|
||||
*
|
||||
* See the [GNU C documentation](https://gcc.gnu.org/onlinedocs/gcc/Common-Function-Attributes.html#index-alloc_005fsize-function-attribute) for more details.
|
||||
*
|
||||
* Since: 2.18
|
||||
*/
|
||||
#if (!defined(__clang__) && ((__GNUC__ > 4) || (__GNUC__ == 4 && __GNUC_MINOR__ >= 3))) || \
|
||||
(defined(__clang__) && g_macro__has_attribute(__alloc_size__))
|
||||
#define G_GNUC_ALLOC_SIZE(x) __attribute__((__alloc_size__(x)))
|
||||
@ -159,6 +271,151 @@
|
||||
#define G_GNUC_ALLOC_SIZE2(x,y)
|
||||
#endif
|
||||
|
||||
/**
|
||||
* 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, 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 `printf()`. It allows the compiler
|
||||
* to type-check the arguments passed to the function.
|
||||
*
|
||||
* Place the attribute after the function declaration, just before the
|
||||
* semicolon.
|
||||
*
|
||||
* 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,
|
||||
* gulong n,
|
||||
* gchar const *format,
|
||||
* ...) G_GNUC_PRINTF (3, 4);
|
||||
* ]|
|
||||
*/
|
||||
|
||||
/**
|
||||
* 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, 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](https://gcc.gnu.org/onlinedocs/gcc/Common-Function-Attributes.html#index-Wformat-3288)
|
||||
* for details.
|
||||
*/
|
||||
|
||||
/**
|
||||
* G_GNUC_STRFTIME:
|
||||
* @format_idx: the index of the argument corresponding to
|
||||
* the format string (the arguments are numbered from 1)
|
||||
*
|
||||
* Expands to the GNU C `strftime` format function attribute if the compiler
|
||||
* is gcc. This is used for declaring functions which take a format argument
|
||||
* which is passed to `strftime()` or an API implementing its formats. It allows
|
||||
* the compiler check the format passed to the function.
|
||||
*
|
||||
* See the
|
||||
* [GNU C documentation](https://gcc.gnu.org/onlinedocs/gcc/Common-Function-Attributes.html#index-Wformat-3288)
|
||||
* for details.
|
||||
*
|
||||
* Since: 2.60
|
||||
*/
|
||||
|
||||
/**
|
||||
* G_GNUC_FORMAT:
|
||||
* @arg_idx: the index of the argument
|
||||
*
|
||||
* Expands to the GNU C `format_arg` function attribute if the compiler
|
||||
* is gcc. This function attribute specifies that a function takes a
|
||||
* format string for a `printf()`, `scanf()`, `strftime()` or `strfmon()` style
|
||||
* function and modifies it, so that the result can be passed to a `printf()`,
|
||||
* `scanf()`, `strftime()` or `strfmon()` style function (with the remaining
|
||||
* arguments to the format function the same as they would have been
|
||||
* for the unmodified string).
|
||||
*
|
||||
* Place the attribute after the function declaration, just before the
|
||||
* semicolon.
|
||||
*
|
||||
* See the [GNU C documentation](https://gcc.gnu.org/onlinedocs/gcc/Common-Function-Attributes.html#index-Wformat-nonliteral-1) for more details.
|
||||
*
|
||||
* |[<!-- language="C" -->
|
||||
* gchar *g_dgettext (gchar *domain_name, gchar *msgid) G_GNUC_FORMAT (2);
|
||||
* ]|
|
||||
*/
|
||||
|
||||
/**
|
||||
* G_GNUC_NORETURN:
|
||||
*
|
||||
* Expands to the GNU C `noreturn` function attribute if the compiler is gcc.
|
||||
* It is used for declaring functions which never return. It enables
|
||||
* optimization of the function, and avoids possible compiler warnings.
|
||||
*
|
||||
* Place the attribute after the declaration, just before the semicolon.
|
||||
*
|
||||
* See the [GNU C documentation](https://gcc.gnu.org/onlinedocs/gcc/Common-Function-Attributes.html#index-noreturn-function-attribute) for more details.
|
||||
*/
|
||||
|
||||
/**
|
||||
* G_GNUC_CONST:
|
||||
*
|
||||
* Expands to the GNU C `const` function attribute if the compiler is gcc.
|
||||
* 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.
|
||||
*
|
||||
* Place the attribute after the declaration, just before the semicolon.
|
||||
*
|
||||
* See the [GNU C documentation](https://gcc.gnu.org/onlinedocs/gcc/Common-Function-Attributes.html#index-const-function-attribute) for more details.
|
||||
*
|
||||
* A function that has pointer arguments and examines the data pointed to
|
||||
* must not 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`.
|
||||
*/
|
||||
|
||||
/**
|
||||
* G_GNUC_UNUSED:
|
||||
*
|
||||
* Expands to the GNU C `unused` function attribute if the compiler is gcc.
|
||||
* It is used for declaring functions and arguments which may never be used.
|
||||
* It avoids possible compiler warnings.
|
||||
*
|
||||
* For functions, place the attribute after the declaration, just before the
|
||||
* semicolon. For arguments, place the attribute at the beginning of the
|
||||
* argument declaration.
|
||||
*
|
||||
* |[<!-- language="C" -->
|
||||
* void my_unused_function (G_GNUC_UNUSED gint unused_argument,
|
||||
* gint other_argument) G_GNUC_UNUSED;
|
||||
* ]|
|
||||
*
|
||||
* See the [GNU C documentation](https://gcc.gnu.org/onlinedocs/gcc/Common-Function-Attributes.html#index-unused-function-attribute) for more details.
|
||||
*/
|
||||
|
||||
/**
|
||||
* G_GNUC_NO_INSTRUMENT:
|
||||
*
|
||||
* Expands to the GNU C `no_instrument_function` function attribute if the
|
||||
* compiler is gcc. Functions with this attribute will not be instrumented
|
||||
* for profiling, when the compiler is called with the
|
||||
* `-finstrument-functions` option.
|
||||
*
|
||||
* Place the attribute after the declaration, just before the semicolon.
|
||||
*
|
||||
* See the [GNU C documentation](https://gcc.gnu.org/onlinedocs/gcc/Common-Function-Attributes.html#index-no_005finstrument_005ffunction-function-attribute) for more details.
|
||||
*/
|
||||
|
||||
#if __GNUC__ > 2 || (__GNUC__ == 2 && __GNUC_MINOR__ > 4)
|
||||
#if !defined (__clang__) && G_GNUC_CHECK_VERSION (4, 4)
|
||||
#define G_GNUC_PRINTF( format_idx, arg_idx ) \
|
||||
@ -200,18 +457,66 @@
|
||||
#define G_GNUC_NO_INSTRUMENT
|
||||
#endif /* !__GNUC__ */
|
||||
|
||||
/**
|
||||
* G_GNUC_FALLTHROUGH:
|
||||
*
|
||||
* Expands to the GNU C `fallthrough` statement attribute if the compiler is gcc.
|
||||
* This allows declaring case statement to explicitly fall through in switch
|
||||
* statements. To enable this feature, use `-Wimplicit-fallthrough` during
|
||||
* compilation.
|
||||
*
|
||||
* Put the attribute right before the case statement you want to fall through
|
||||
* to.
|
||||
*
|
||||
* See the [GNU C documentation](https://gcc.gnu.org/onlinedocs/gcc/Statement-Attributes.html#index-fallthrough-statement-attribute) for more details.
|
||||
*
|
||||
* Since: 2.60
|
||||
*/
|
||||
#if __GNUC__ > 6
|
||||
#define G_GNUC_FALLTHROUGH __attribute__((fallthrough))
|
||||
#else
|
||||
#define G_GNUC_FALLTHROUGH
|
||||
#endif /* __GNUC__ */
|
||||
|
||||
/**
|
||||
* G_GNUC_DEPRECATED:
|
||||
*
|
||||
* Expands to the GNU C `deprecated` attribute if the compiler is gcc.
|
||||
* It can be used to mark `typedef`s, variables and functions as deprecated.
|
||||
* When called with the `-Wdeprecated-declarations` option,
|
||||
* gcc will generate warnings when deprecated interfaces are used.
|
||||
*
|
||||
* Place the attribute after the declaration, just before the semicolon.
|
||||
*
|
||||
* See the [GNU C documentation](https://gcc.gnu.org/onlinedocs/gcc/Common-Function-Attributes.html#index-deprecated-function-attribute) for more details.
|
||||
*
|
||||
* Since: 2.2
|
||||
*/
|
||||
#if __GNUC__ > 3 || (__GNUC__ == 3 && __GNUC_MINOR__ >= 1)
|
||||
#define G_GNUC_DEPRECATED __attribute__((__deprecated__))
|
||||
#else
|
||||
#define G_GNUC_DEPRECATED
|
||||
#endif /* __GNUC__ */
|
||||
|
||||
/**
|
||||
* G_GNUC_DEPRECATED_FOR:
|
||||
* @f: the intended replacement for the deprecated symbol,
|
||||
* such as the name of a function
|
||||
*
|
||||
* Like %G_GNUC_DEPRECATED, but names the intended replacement for the
|
||||
* deprecated symbol if the version of gcc in use is new enough to support
|
||||
* custom deprecation messages.
|
||||
*
|
||||
* Place the attribute after the declaration, just before the semicolon.
|
||||
*
|
||||
* See the [GNU C documentation](https://gcc.gnu.org/onlinedocs/gcc/Common-Function-Attributes.html#index-deprecated-function-attribute) for more details.
|
||||
*
|
||||
* Note that if @f is a macro, it will be expanded in the warning message.
|
||||
* You can enclose it in quotes to prevent this. (The quotes will show up
|
||||
* in the warning, but it's better than showing the macro expansion.)
|
||||
*
|
||||
* Since: 2.26
|
||||
*/
|
||||
#if __GNUC__ > 4 || (__GNUC__ == 4 && __GNUC_MINOR__ >= 5)
|
||||
#define G_GNUC_DEPRECATED_FOR(f) \
|
||||
__attribute__((deprecated("Use " #f " instead")))
|
||||
@ -248,12 +553,36 @@
|
||||
#define G_GNUC_END_IGNORE_DEPRECATIONS
|
||||
#endif
|
||||
|
||||
/**
|
||||
* G_GNUC_MAY_ALIAS:
|
||||
*
|
||||
* Expands to the GNU C `may_alias` type attribute if the compiler is gcc.
|
||||
* 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](https://gcc.gnu.org/onlinedocs/gcc/Common-Type-Attributes.html#index-may_005falias-type-attribute) for details.
|
||||
*
|
||||
* Since: 2.14
|
||||
*/
|
||||
#if __GNUC__ > 3 || (__GNUC__ == 3 && __GNUC_MINOR__ >= 3)
|
||||
#define G_GNUC_MAY_ALIAS __attribute__((may_alias))
|
||||
#else
|
||||
#define G_GNUC_MAY_ALIAS
|
||||
#endif
|
||||
|
||||
/**
|
||||
* G_GNUC_WARN_UNUSED_RESULT:
|
||||
*
|
||||
* Expands to the GNU C `warn_unused_result` function attribute if the compiler
|
||||
* is gcc. This function attribute makes the compiler emit a warning if the
|
||||
* result of a function call is ignored.
|
||||
*
|
||||
* Place the attribute after the declaration, just before the semicolon.
|
||||
*
|
||||
* See the [GNU C documentation](https://gcc.gnu.org/onlinedocs/gcc/Common-Function-Attributes.html#index-warn_005funused_005fresult-function-attribute) for more details.
|
||||
*
|
||||
* Since: 2.10
|
||||
*/
|
||||
#if __GNUC__ > 3 || (__GNUC__ == 3 && __GNUC_MINOR__ >= 4)
|
||||
#define G_GNUC_WARN_UNUSED_RESULT __attribute__((warn_unused_result))
|
||||
#else
|
||||
|
||||
Loading…
Reference in New Issue
Block a user