util_attributes.h File Reference

Convenience macros for GCC function, variable, and type attributes. More...

Macros
#define	ATTRIBUTE(X)
	General-purpose attribute wrapper.
#define	ACCESS(mode, ref_idx)
	Specifies pointer access mode for function arguments.
#define	ALIAS(target)
	Creates a symbol alias to another function or variable.
#define	ALIGNED   __attribute__((aligned))
	Specifies a minimum alignment (in bytes) for a variable or struct.
#define	ALWAYS_INLINE   __attribute__((always_inline))
	Forces a function to always be inlined.
#define	CONST   __attribute__((const))
	Marks a function as having no side effects and not depending on global memory.
#define	CONSTRUCTOR   __attribute__((constructor))
	Marks a function to be called automatically before main().
#define	DESTRUCTOR   __attribute__((destructor))
	Marks a function to be called automatically after main() returns.
#define	DEPRECATED   __attribute__((deprecated))
	Marks a function or variable as deprecated.
#define	DEPRECATED_MSG(msg)
	Marks a function or variable as deprecated, with a custom message.
#define	ERROR(msg)
	Triggers a compile-time error if the function is used.
#define	WARNING(msg)
	Triggers a compile-time warning if the function is used.
#define	FD_ARG(n)
	Indicates a function parameter is a file descriptor.
#define	FD_ARG_READ(n)
	Indicates a file descriptor parameter is used for reading.
#define	FD_ARG_WRITE(n)
	Indicates a file descriptor parameter is used for writing.
#define	FORMAT(archetype, string_index, first_to_check)
	Specifies printf/scanf-style format checking.
#define	FORMAT_ARG(string_index)
	Applies format checking to a string-returning function.
#define	MALLOC(deallocator)
	Marks function as returning freshly allocated memory.
#define	NONNULL   __attribute__((nonnull))
	Marks all pointer arguments as non-null.
#define	NONNULL_POSITIONS(...)
	Marks specific pointer arguments as non-null.
#define	NORETURN   __attribute__((noreturn))
	Indicates a function never returns.
#define	NOTHROW   __attribute__((nothrow))
	Indicates the function does not throw exceptions.
#define	NULL_TERMINATED_STRING_ARG(n)
	Marks a string argument as null-terminated.
#define	PURE   __attribute__((pure))
	Marks a function as having no side effects except return value.
#define	RETURN_NONNULL   __attribute__((return_nonnull))
	Declares that the function never returns a null pointer.
#define	SENTINEL   __attribute__((sentinel))
	Marks the last argument in a variadic function as a sentinel (e.g., NULL).
#define	UNAVAILABLE   __attribute__((unavailable))
	Marks a function or variable as unavailable.
#define	UNAVAILABLE_MSG(msg)
	Marks a function or variable as unavailable, with a message.
#define	UNUSED   __attribute__((unused))
	Marks a variable or function as possibly unused to suppress warnings.
#define	USED   __attribute__((used))
	Marks a symbol to be emitted even if it appears unused.
#define	WARN_UNUSED_RESULT   __attribute__((warn_unused_result))
	Warns if the result of a function is ignored.
#define	UNREACHABLE   __builtin_unreachable()
	Hints to the compiler that the following code is unreachable.

Detailed Description

Convenience macros for GCC function, variable, and type attributes.

This header provides wrappers for various GCC __attribute__ extensions.

See also

GCC attribute reference: https://gcc.gnu.org/onlinedocs/gcc/Function-Attributes.html

In particular: https://gcc.gnu.org/onlinedocs/gcc/Common-Function-Attributes.html

Macro Definition Documentation

ACCESS

#define ACCESS	(		mode,
			ref_idx )

Value:

__attribute__((access(mode, ref_idx)))

Specifies pointer access mode for function arguments.

Parameters

mode	Access mode: "read_only", "write_only", or "read_write".
ref_idx	Index of the pointer argument being accessed.

ALIAS

#define ALIAS

(

target

)

Value:

__attribute__((alias(#target)))

Creates a symbol alias to another function or variable.

Parameters

target

The target symbol name (as a token).

ALIGNED

#define ALIGNED   __attribute__((aligned))

Specifies a minimum alignment (in bytes) for a variable or struct.

ALWAYS_INLINE

#define ALWAYS_INLINE   __attribute__((always_inline))

Forces a function to always be inlined.

ATTRIBUTE

#define ATTRIBUTE

(

X

)

Value:

__attribute__(X)

General-purpose attribute wrapper.

CONST

#define CONST   __attribute__((const))

Marks a function as having no side effects and not depending on global memory.

CONSTRUCTOR

#define CONSTRUCTOR   __attribute__((constructor))

Marks a function to be called automatically before main().

DEPRECATED

#define DEPRECATED   __attribute__((deprecated))

Marks a function or variable as deprecated.

DEPRECATED_MSG

#define DEPRECATED_MSG

(

msg

)

Value:

__attribute__((deprecated(msg)))

Marks a function or variable as deprecated, with a custom message.

Parameters

msg	Message explaining why it's deprecated.

DESTRUCTOR

#define DESTRUCTOR   __attribute__((destructor))

Marks a function to be called automatically after main() returns.

ERROR

#define ERROR

(

msg

)

Value:

__attribute__((error(msg)))

Triggers a compile-time error if the function is used.

Parameters

msg	Error message to display.

FD_ARG

#define FD_ARG

(

n

)

Value:

__attribute__((fd_arg(n)))

Indicates a function parameter is a file descriptor.

Parameters

n	1-based index of the parameter.

FD_ARG_READ

#define FD_ARG_READ

(

n

)

Value:

__attribute__((fd_arg_read(n)))

Indicates a file descriptor parameter is used for reading.

Parameters

n	1-based index of the parameter.

FD_ARG_WRITE

#define FD_ARG_WRITE

(

n

)

Value:

__attribute__((fd_arg_write(n)))

Indicates a file descriptor parameter is used for writing.

Parameters

n	1-based index of the parameter.

FORMAT

#define FORMAT	(		archetype,
			string_index,
			first_to_check )

Value:

    __attribute__((format(archetype, string_index, first_to_check)))

Specifies printf/scanf-style format checking.

Parameters

archetype	"printf", "scanf", etc.
string_index	1-based index of the format string.
first_to_check	1-based index of first format argument.

FORMAT_ARG

#define FORMAT_ARG

(

string_index

)

Value:

__attribute__((format_arg(string_index)))

Applies format checking to a string-returning function.

Parameters

string_index

1-based index of the format string argument.

MALLOC

#define MALLOC

(

deallocator

)

Value:

__attribute__((malloc(deallocator)))

Marks function as returning freshly allocated memory.

Parameters

deallocator

Optional deallocation function name.

NONNULL

#define NONNULL   __attribute__((nonnull))

Marks all pointer arguments as non-null.

NONNULL_POSITIONS

#define NONNULL_POSITIONS

(

...

)

Value:

__attribute__((nonnull(__VA_ARGS__)))

Marks specific pointer arguments as non-null.

Parameters

...	List of 1-based parameter indices.

NORETURN

#define NORETURN   __attribute__((noreturn))

Indicates a function never returns.

NOTHROW

#define NOTHROW   __attribute__((nothrow))

Indicates the function does not throw exceptions.

NULL_TERMINATED_STRING_ARG

#define NULL_TERMINATED_STRING_ARG

(

n

)

Value:

    __attribute__((null_terminated_string_arg(n)))

Marks a string argument as null-terminated.

Parameters

n	1-based index of the parameter.

PURE

#define PURE   __attribute__((pure))

Marks a function as having no side effects except return value.

RETURN_NONNULL

#define RETURN_NONNULL   __attribute__((return_nonnull))

Declares that the function never returns a null pointer.

SENTINEL

#define SENTINEL   __attribute__((sentinel))

Marks the last argument in a variadic function as a sentinel (e.g., NULL).

UNAVAILABLE

#define UNAVAILABLE   __attribute__((unavailable))

Marks a function or variable as unavailable.

UNAVAILABLE_MSG

#define UNAVAILABLE_MSG

(

msg

)

Value:

__attribute__((unavailable(msg)))

Marks a function or variable as unavailable, with a message.

Parameters

msg	Message shown on use.

UNREACHABLE

#define UNREACHABLE   __builtin_unreachable()

Hints to the compiler that the following code is unreachable.

Used for optimization and to silence warnings about missing return paths.

UNUSED

#define UNUSED   __attribute__((unused))

Marks a variable or function as possibly unused to suppress warnings.

USED

#define USED   __attribute__((used))

Marks a symbol to be emitted even if it appears unused.

WARN_UNUSED_RESULT

#define WARN_UNUSED_RESULT   __attribute__((warn_unused_result))

Warns if the result of a function is ignored.

WARNING

#define WARNING

(

msg

)

Value:

__attribute__((warning(msg)))

Triggers a compile-time warning if the function is used.

Parameters

msg	Warning message to display.