Collaboration diagram for C programming language extensions:

Modules
	Integer operations

	Linked lists

	In-memory byte streams

	Thread-safe queues (FIFO)

	String helpers

	Vector

Macros
#define	VLC_GCC_VERSION(maj, min) (0)
	GCC version check. More...

#define	VLC_DEPRECATED
	Deprecated functions or compound members annotation. More...

#define	VLC_DEPRECATED_ENUM
	Deprecated enum member annotation. More...

#define	VLC_FORMAT(x, y)
	String format function annotation. More...

#define	VLC_FORMAT_ARG(x)
	Format string translation function annotation. More...

#define	VLC_MALLOC
	Heap allocated result function annotation. More...

#define	VLC_USED
	Used result function annotation. More...

#define	VLC_WEAK
	Weak symbol annotation. More...

#define	likely(p) (!!(p))
	Predicted true condition. More...

#define	unlikely(p) (!!(p))
	Predicted false condition. More...

#define	unreachable() ((void)0)
	Impossible branch. More...

#define	vlc_assert_unreachable() (vlc_assert(!"unreachable"), unreachable())
	Impossible branch assertion. More...

#define	vlc_assert(pred) ((void)0)
	Run-time assertion. More...

#define	VLC_EXTERN

#define	VLC_EXPORT

#define	VLC_API VLC_EXTERN VLC_EXPORT
	Exported API call annotation. More...

Detailed Description

This section defines a number of macros and inline functions extending the C language. Most extensions are implemented by GCC and LLVM/Clang, and have unoptimized fallbacks for other C11/C++11 conforming compilers.

Macro Definition Documentation

◆ likely

#define likely ( p ) (!!(p))

Predicted true condition.

This macro indicates that the condition is expected most often true. The compiler may optimize the code assuming that this condition is usually met.

◆ unlikely

#define unlikely ( p ) (!!(p))

Predicted false condition.

This macro indicates that the condition is expected most often false. The compiler may optimize the code assuming that this condition is rarely met.

◆ unreachable

#define unreachable ( ) ((void)0)

Impossible branch.

This macro indicates that the branch cannot be reached at run-time, and represents undefined behaviour. The compiler may optimize the code assuming that the call flow will never logically reach the point where this macro is expanded.

◆ VLC_API

#define VLC_API VLC_EXTERN VLC_EXPORT

Exported API call annotation.

This macro is placed before a function declaration to indicate that the function is an API call of the LibVLC plugin API.

◆ vlc_assert

#define vlc_assert ( pred ) ((void)0)

Run-time assertion.

This macro performs a run-time assertion if C assertions are enabled and the following preprocessor symbol is defined:

__LIBVLC__

That restriction ensures that assertions in public header files are not unwittingly leaked to externally-compiled plug-ins including those header files.

Within the LibVLC code base, this is exactly the same as assert(), which can and probably should be used directly instead.

◆ vlc_assert_unreachable

#define vlc_assert_unreachable ( ) (vlc_assert(!"unreachable"), unreachable())

Impossible branch assertion.

This macro asserts that the branch cannot be reached at run-time.

If the branch is reached in a debug build, it will trigger an assertion failure and abnormal program termination.

If the branch is reached in a non-debug build, this macro is equivalent to unreachable and the behaviour is undefined.

◆ VLC_DEPRECATED

#define VLC_DEPRECATED

Deprecated functions or compound members annotation.

Use this macro in front of a function declaration or compound member within a compound type declaration. The compiler may emit a warning every time the function or member is used.

Use VLC_DEPRECATED_ENUM instead for enumeration members.

◆ VLC_DEPRECATED_ENUM

#define VLC_DEPRECATED_ENUM

Deprecated enum member annotation.

Use this macro after an enumerated type member declaration. The compiler may emit a warning every time the enumeration member is used.

◆ VLC_EXPORT

#define VLC_EXPORT

◆ VLC_EXTERN

#define VLC_EXTERN

◆ VLC_FORMAT

#define VLC_FORMAT	(	x,
		y
	)

String format function annotation.

Use this macro after a function prototype/declaration if the function expects a standard C format string. This helps compiler diagnostics.

Parameters

x	the position (starting from 1) of the format string argument
y	the first position (also starting from 1) of the variable arguments following the format string (usually but not always `x+1`).

◆ VLC_FORMAT_ARG

#define VLC_FORMAT_ARG ( x )

Format string translation function annotation.

Use this macro after a function prototype/declaration if the function expects a format string as input and returns another format string as output to another function.

This is primarily intended for localization functions such as gettext().

◆ VLC_GCC_VERSION

#define VLC_GCC_VERSION	(	maj,
		min
	)	(0)

GCC version check.

◆ VLC_MALLOC

#define VLC_MALLOC

Heap allocated result function annotation.

Use this macro to annotate a function that returns a pointer to memory that cannot alias any other valid pointer.

This is primarily used for functions that return a pointer to heap-allocated memory, but it can be used for other applicable purposes.

Warning: Do not use this annotation if the returned pointer can in any way alias a valid pointer at the time the function exits. This could lead to very weird memory corruption bugs.

◆ VLC_USED

#define VLC_USED

Used result function annotation.

Use this macro to annotate a function whose result must be used.

There are several cases where this is useful:

If a function has no side effects (or no useful side effects), such that the only useful purpose of calling said function is to obtain its return value.
If ignoring the function return value would lead to a resource leak (including but not limited to a memory leak).
If a function cannot be used correctly without checking its return value. For instance, if the function can fail at any time.

The compiler may warn if the return value of a function call is ignored.

◆ VLC_WEAK

#define VLC_WEAK

Weak symbol annotation.

Use this macro before an external identifier definition to mark it as a weak symbol. A weak symbol can be overriden by another symbol of the same name at the link time.

Modules

Macros