This section defines a number of macros and inline functions extending the C language. More...

Collaboration diagram for C programming language extensions:

Modules
	Integer operations
	Common integer functions.

	Linked lists

	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.

Referenced by aout_ChannelReorder(), aout_New(), aout_ReplayGainSelect(), AppendAttachment(), config_GetLibDirOnce(), decoder_NewAudioBuffer(), DecoderThread(), encode_URI_bytes(), EnsureUTF8(), es_format_Copy(), EsOutDeleteInfoEs(), filter_chain_AppendInner(), ImageWrite(), input_ExtractAttachmentAndCacheArt(), input_item_Copy(), input_item_CopyOptions(), input_preparser_New(), InputSourceNew(), IsUTF8(), module_InitBank(), module_InitStaticModules(), ModuleThread_PlayVideo(), picture_Clone(), picture_pool_ClonePicture(), psz_md5_hash(), ThreadChangeFilters(), utf8_vfprintf(), var_GetCoords(), var_LocationParse(), vlc_array_remove(), vlc_cancel_self(), vlc_dup(), vlc_epg_event_Duplicate(), vlc_gettext(), vlc_h2_frame_data(), vlc_h2_frame_goaway(), vlc_h2_frame_headers(), vlc_h2_frame_ping(), vlc_h2_frame_pong(), vlc_h2_frame_rst_stream(), vlc_h2_frame_window_update(), vlc_http_proxy_find(), vlc_http_res_get_redirect(), vlc_input_attachment_New(), vlc_input_title_Duplicate(), vlc_interrupt_create(), vlc_loaddir(), vlc_lock_unmark(), vlc_Log(), vlc_mutex_marked(), vlc_ngettext(), vlc_obj_calloc(), vlc_obj_malloc(), vlc_obj_memdup(), vlc_object_init(), vlc_poll_i11e(), vlc_seekpoint_Duplicate(), vlc_sem_destroy(), vlc_sem_post(), vlc_sem_wait(), vlc_stream_CopyBlock(), vlc_stream_fifo_Queue(), vlc_timer_thread(), vlc_uri_encode(), vlm_New(), vout_ChangeSpuChannelMargin(), vout_ControlChangeSubFilters(), vout_ControlChangeSubSources(), vout_GetPicture(), and vout_InitInterlacingSupport().

◆ 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.

Referenced by access_New(), add_mapping(), addon_entry_New(), aout_ChannelReorder(), aout_CheckReady(), aout_DecPlay(), aout_DecSilence(), aout_DevicesList(), aout_EnableFilter(), aout_filter_GetVout(), aout_FiltersNewWithClock(), aout_HotplugNotify(), aout_New(), aout_RequestRetiming(), aout_volume_Amplify(), aout_volume_New(), aout_volume_SetFormat(), aout_volume_SetVolume(), ArtCacheName(), background_worker_Create(), background_worker_Push(), block_Alloc(), block_BytestreamPop(), block_FindStartcodeFromOffset(), block_mmap_Alloc(), config_FindConfig(), config_GetIntChoices(), config_GetSysPath(), config_ListModules(), config_SortConfig(), config_StringEscape(), cookie_parse(), Create(), CreateDecoder(), CreateFilter(), date_Decrement(), date_Increment(), decoder_GetDecoderDevice(), decoder_UpdateVideoOutput(), DecoderThread_DecodeBlock(), DecoderThread_ProcessInput(), demux_FilterNew(), demux_NewAdvanced(), Destroy(), DllMain(), encode_URI_bytes(), es_format_Copy(), EsOutUpdateInfo(), filter_chain_AppendInner(), filter_chain_NewInner(), filter_chain_NewVideo(), GetTmpFile(), GetVarSlaves(), httpd_FileNew(), httpd_RedirectNew(), httpd_StreamSetHTTPHeaders(), httpd_UrlNew(), httpdLoop(), input_fetcher_New(), input_fetcher_Push(), input_item_AddOpaque(), input_item_AddOption(), input_item_Copy(), input_item_CopyOptions(), input_item_CreateFilename(), input_item_NewExt(), input_preparser_New(), input_stats_Create(), InputSourceMeta(), InputSourceNew(), InputUpdateMeta(), intf_Create(), intf_InsertItem(), InvokeModule(), keystore_create(), libvlc_ArtRequest(), libvlc_InternalActionsClean(), libvlc_InternalActionsInit(), libvlc_InternalInit(), libvlc_MetadataCancel(), libvlc_MetadataRequest(), libvlc_MlCreate(), mdate_interrupt(), module_find(), module_get_object(), module_gettext(), module_InitStatic(), module_InitStaticModules(), module_list_cap(), module_list_get(), ModuleThread_PlayAudio(), ModuleThread_PlayVideo(), ModuleThread_QueueCc(), mrl_FragmentSplit(), Open(), picture_NewFromFormat(), picture_NewFromResource(), picture_NewPrivate(), picture_pool_Get(), picture_pool_NewExtended(), picture_Setup(), PreparserOpenInput(), print_desc(), ReqCreate(), se_AttachWrapper(), se_InitDirectory(), se_InitStream(), secstotimestr(), services_discovery_item_added(), services_discovery_item_removed(), sout_AccessOutNew(), sout_AnnounceRegisterSDP(), spu_GetFreeChannelId(), StartWorker(), stream_AccessNew(), stream_FilterChainNew(), StreamExtractorAttach(), subpicture_region_Copy(), SubSourceInit(), system_ConfigureDbus(), task_Create(), text_segment_Copy(), text_segment_NewInheritStyle(), ThreadDisplayPicture(), ThreadDisplayRenderPicture(), thumbnailer_request_Start(), thumbnailer_RequestCommon(), ToCharset(), TsStorageNew(), update_DownloadReal(), utf8_vfprintf(), var_Create(), vlc_actions_get_keycodes(), vlc_array_append(), vlc_array_insert(), vlc_b64_encode_binary(), vlc_bindtextdomain(), vlc_chunked_open(), vlc_chunked_read(), vlc_clock_master_update(), vlc_clock_setup_once(), vlc_clone_attr(), vlc_close(), vlc_cond_init(), vlc_cond_init_daytime(), vlc_custom_create(), vlc_demux_chained_New(), vlc_dictionary_all_keys(), vlc_dlopen(), vlc_GetCPUCount(), vlc_getcwd(), vlc_gl_Create(), vlc_gl_surface_Create(), vlc_h1_conn_create(), vlc_h1_request(), vlc_h1_stream_open(), vlc_h1_stream_read(), vlc_h1_stream_wait(), vlc_h2_conn_create(), vlc_h2_frame_alloc(), vlc_h2_frame_headers(), vlc_h2_frame_recv(), vlc_h2_frame_settings(), vlc_h2_output_create(), vlc_h2_output_dequeue(), vlc_h2_output_queue(), vlc_h2_parse_headers_append(), vlc_h2_parse_init(), vlc_h2_recv_thread(), vlc_h2_stream_headers(), vlc_h2_stream_open(), vlc_h2_stream_read(), vlc_http_authority(), vlc_http_cookies_new(), vlc_http_file_create(), vlc_http_get_token_value(), vlc_http_live_create(), vlc_http_mgr_create(), vlc_http_msg_add_cookies(), vlc_http_msg_add_creds_basic(), vlc_http_msg_get_file_size(), vlc_http_msg_h2_frame(), vlc_http_msg_h2_headers(), vlc_http_msg_headers(), vlc_http_msg_vadd_header(), vlc_http_req_create(), vlc_http_res_get_redirect(), vlc_http_res_init(), vlc_http_res_open(), vlc_http_res_req(), vlc_http_res_set_login(), vlc_http_resp_create(), vlc_http_tunnel_open(), vlc_https_connect_proxy(), vlc_https_headers_recv(), vlc_https_request(), vlc_idna_to_ascii(), vlc_input_attachment_New(), vlc_interrupt_prepare(), vlc_iri2uri(), vlc_loaddir(), vlc_lock_mark(), vlc_LogEarlyOpen(), vlc_LogExternalCreate(), vlc_LogHeaderCreate(), vlc_LogModuleCreate(), vlc_LogPreinit(), vlc_LogSwitchCreate(), vlc_media_source_New(), vlc_media_source_provider_Add(), vlc_media_source_provider_List(), vlc_media_source_provider_New(), vlc_media_tree_Add(), vlc_media_tree_AddChild(), vlc_media_tree_AddListener(), vlc_media_tree_AddSubtree(), vlc_media_tree_New(), vlc_memstream_open(), vlc_memstream_vprintf(), vlc_memstream_write(), vlc_MetadataRequest(), vlc_mkdir(), vlc_ml_event_register_callback(), vlc_module_store(), vlc_mta_acquire(), vlc_mutex_init(), vlc_mutex_init_recursive(), vlc_mutex_marked(), vlc_obj_calloc(), vlc_object_init(), vlc_objres_new(), vlc_opendir(), vlc_path2uri(), vlc_player_timer_point_Interpolate(), vlc_playlist_AddListener(), vlc_playlist_item_meta_CopyString(), vlc_playlist_item_meta_InitFields(), vlc_playlist_item_meta_New(), vlc_playlist_item_New(), vlc_playlist_MediaToItems(), vlc_playlist_New(), vlc_playlist_NewMetaArray(), vlc_playlist_PlayerInit(), vlc_playlist_Sort(), vlc_plugin_create(), vlc_plugin_desc_cb(), vlc_plugin_describe(), vlc_plugin_gpa_cb(), vlc_poll_i11e(), vlc_probe(), vlc_probe_add(), vlc_rd_get_names(), vlc_rd_probe_add(), vlc_readdir(), vlc_renderer_item_new(), vlc_restorecancel(), vlc_rwlock_init(), vlc_sd_Create(), vlc_sd_GetNames(), vlc_sd_probe_Add(), vlc_sem_init(), vlc_sem_post(), vlc_statEx(), vlc_static_cond_init(), vlc_strcasestr(), vlc_stream_AttachmentNew(), vlc_stream_Block(), vlc_stream_CustomNew(), vlc_stream_fifo_New(), vlc_stream_fifo_Queue(), vlc_stream_fifo_Write(), vlc_stream_FilterNew(), vlc_stream_MemoryNew(), vlc_stream_Peek(), vlc_stream_ReadBlock(), vlc_stream_ReadLine(), vlc_stream_ReadRaw(), vlc_strerror_l(), vlc_thread_id(), vlc_threadvar_create(), vlc_thumbnailer_Create(), vlc_tick_now(), vlc_tick_wait(), vlc_timer_create(), vlc_tls_ClientCreate(), vlc_tls_GetLine(), vlc_tls_ServerCreate(), vlc_tls_SocketAddrInfo(), vlc_tls_SocketAlloc(), vlc_tls_SocketPair(), vlc_towc(), vlc_unlink(), vlc_uri2path(), vlc_uri_compose(), vlc_uri_merge_paths(), vlc_uri_resolve(), vlc_UrlParseInner(), vlc_vaLogEarly(), vlc_video_context_Create(), vlc_xlib_init(), vlc_xml_encode(), vout_display_New(), vout_OSDSegment(), vout_snapshot_New(), VoutDisplayCreateRender(), xmalloc(), xml_ReaderCreate(), xrealloc(), and xstrdup().

◆ 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.

Referenced by vlc_reallocarray(), and xstrdup().

◆ 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.

Referenced by decoder_AbortPictures(), decoder_GetDecoderDevice(), decoder_GetDisplayDate(), decoder_GetDisplayRate(), decoder_GetInputAttachments(), decoder_NewPicture(), decoder_NewSubpicture(), decoder_QueueAudio(), decoder_QueueCc(), decoder_QueueSub(), decoder_QueueVideo(), decoder_UpdateAudioFormat(), decoder_UpdateVideoOutput(), picture_Release(), picture_SwapUV(), vlc_atomic_rc_dec(), vlc_atomic_rc_inc(), vlc_ml_count_album_artists(), vlc_ml_count_album_tracks(), vlc_ml_count_albums(), vlc_ml_count_albums_of(), vlc_ml_count_artist_albums(), vlc_ml_count_artist_tracks(), vlc_ml_count_artists(), vlc_ml_count_artists_of(), vlc_ml_count_audio_media(), vlc_ml_count_genre_albums(), vlc_ml_count_genre_artists(), vlc_ml_count_genre_tracks(), vlc_ml_count_genres(), vlc_ml_count_media_labels(), vlc_ml_count_media_of(), vlc_ml_count_playlist_media(), vlc_ml_count_playlists(), vlc_ml_count_show_episodes(), vlc_ml_count_shows(), vlc_ml_count_video_media(), vlc_ml_list_album_artists(), vlc_ml_list_album_tracks(), vlc_ml_list_albums(), vlc_ml_list_albums_of(), vlc_ml_list_artist_albums(), vlc_ml_list_artist_of(), vlc_ml_list_artist_tracks(), vlc_ml_list_artists(), vlc_ml_list_audio_media(), vlc_ml_list_genre_albums(), vlc_ml_list_genre_artists(), vlc_ml_list_genre_tracks(), vlc_ml_list_genres(), vlc_ml_list_history(), vlc_ml_list_media_labels(), vlc_ml_list_media_of(), vlc_ml_list_playlist_media(), vlc_ml_list_playlists(), vlc_ml_list_show_episodes(), vlc_ml_list_shows(), vlc_ml_list_stream_history(), and vlc_ml_list_video_media().

◆ 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.

Referenced by aout_Deinterleave(), aout_Interleave(), CmdClean(), CmdExecuteControl(), CmdInitControl(), CompareMetaByKey(), config_GetSysPath(), config_GetUserDir(), ControlLocked(), ControlNav(), DecoderThread(), DecoderThread_ChangeDelay(), DecoderThread_ChangePause(), DecoderThread_ChangeRate(), DecoderThread_DecodeBlock(), DeleteDecoder(), EsOutUpdateInfo(), EsOutVaControlLocked(), getAppDependentDir(), httpd_ClientRecv(), input_SlaveSourceAdd(), player_on_state_changed(), RunThread(), sout_AccessOutControl(), sout_AccessOutDelete(), sout_AccessOutRead(), sout_AccessOutSeek(), sout_AccessOutWrite(), sout_AnnounceRegisterSDP(), sout_AnnounceUnRegister(), sout_MuxAddStream(), sout_MuxDelete(), sout_MuxDeleteStream(), sout_MuxFlush(), sout_MuxGetStream(), sout_MuxNew(), sout_MuxSendBuffer(), sout_StreamChainDelete(), sout_StreamChainNew(), spu_ChangeChannelOrderMargin(), spu_GetChannel(), transform_GetBasicOps(), TsRun(), update_Check(), update_Delete(), update_Download(), update_GetRelease(), update_NeedUpgrade(), var_Create(), var_Inherit(), vlc_accept_i11e(), vlc_control_cancel(), vlc_event_detach(), vlc_http_msg_get_file_size(), vlc_player_AoutCallback(), vlc_player_GetCategoryLanguage(), vlc_player_input_HandleEsEvent(), vlc_player_input_HandleProgramEvent(), vlc_player_input_HandleState(), vlc_player_input_HandleStateEvent(), vlc_player_input_HandleTeletextMenu(), vlc_player_input_HandleTitleEvent(), vlc_player_input_HandleVoutEvent(), vlc_player_Navigate(), vlc_player_SelectCategoryLanguage(), vlc_player_SetAtoBLoop(), vlc_player_VoutCallback(), vlc_playlist_ComputeHasNext(), vlc_playlist_ComputeHasPrev(), vlc_playlist_GetNextIndex(), vlc_playlist_GetPrevIndex(), vlc_playlist_item_meta_InitField(), vlc_playlist_NormalOrderGetNextIndex(), vlc_playlist_NormalOrderGetPrevIndex(), vlc_strftime(), vlc_threadvars_cleanup(), vlc_timer_thread(), vlc_towc(), vlc_writev(), vlm_Control(), vlm_Delete(), vlm_ExecuteCommand(), vlm_MessageAdd(), vlm_MessageDelete(), vout_display_SendEventPicturesInvalid(), vout_display_TranslateMouseState(), and vout_display_window_MouseEvent().

◆ 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.

Referenced by block_ChainGather(), services_discovery_AddSubItem(), and vlc_player_ToggleRecording().

◆ 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`).

Referenced by config_CreateDir(), and vlc_http_conn_release().

◆ 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().

Referenced by vlc_reallocarray().

◆ 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.

Referenced by block_ChainGather(), block_Duplicate(), cookie_destroy(), var_CreateGetFloat(), var_CreateGetFloatCommand(), var_CreateGetString(), var_CreateGetStringCommand(), var_GetFloat(), var_GetString(), var_InheritFloat(), vlc_ascii_strncasecmp(), and vlc_object_release().

◆ 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.

Referenced by GCD(), and xstrdup().

◆ 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.

Referenced by module_InitStatic().

Modules

Macros