VLC  4.0.0-dev
Modules | Macros
C programming language extensions

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
 
 In-memory byte streams
 In-memory byte stream are a portable wrapper for in-memory formatted output 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.

Referenced by aout_ChannelReorder(), aout_New(), aout_ReplayGainSelect(), AppendAttachment(), block_FifoNew(), 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(), InputSourceInit(), IsUTF8(), module_InitBank(), module_InitStaticModules(), ModuleThread_PlayVideo(), picture_Clone(), picture_InternalClone(), 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_Log(), vlc_ngettext(), vlc_obj_calloc(), vlc_obj_malloc(), vlc_obj_memdup(), vlc_object_init(), vlc_poll_i11e(), vlc_seekpoint_Duplicate(), vlc_sem_timedwait(), 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(), GenerateCnonce(), 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_pool_Get(), picture_pool_New(), 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_timedwait_daytime(), vlc_CPU(), vlc_custom_create(), vlc_demux_chained_New(), vlc_dictionary_all_keys(), vlc_dlopen(), vlc_encoder_GetDecoderDevice(), 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_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_trylock(), vlc_mutex_unlock(), vlc_obj_calloc(), vlc_object_init(), vlc_objres_new(), vlc_once(), vlc_once_inline(), 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_post(), vlc_statEx(), 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.

See also vlc_assert_unreachable.

◆ 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(), es_out_vaPrivControl(), picture_Release(), picture_SwapUV(), vlc_atomic_rc_dec(), vlc_atomic_rc_inc(), vlc_encoder_GetDecoderDevice(), 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(), CmdExecutePrivControl(), CmdInitControl(), CmdInitPrivControl(), CompareMetaByKey(), config_GetShellDir(), config_GetSysPath(), config_GetUserDir(), ControlLocked(), ControlNav(), DecoderThread_ChangeDelay(), DecoderThread_ChangePause(), DecoderThread_ChangeRate(), DecoderThread_DecodeBlock(), DeleteDecoder(), EsOutUpdateInfo(), EsOutVaControlLocked(), EsOutVaPrivControlLocked(), getAppDependentDir(), httpd_ClientRecv(), input_SlaveSourceAdd(), player_on_state_changed(), PrivControlLocked(), 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_atomic_timedwait(), vlc_atomic_timedwait_daytime(), vlc_control_cancel(), vlc_event_detach(), vlc_http_msg_get_file_size(), vlc_mutex_unlock(), 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_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_FifoPut(), block_FifoSize(), 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.

See also VLC_DEPRECATED.

◆ VLC_EXPORT

#define VLC_EXPORT

◆ VLC_EXTERN

#define VLC_EXTERN

◆ VLC_FORMAT

#define VLC_FORMAT (   x,
 
)

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
xthe position (starting from 1) of the format string argument
ythe 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(), vlc_align(), 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().