Detailed Description

Plugin loading functions.

A plugin is a package of component classes:

A plugin is a package of component classes.

Attention: The plugin loading API offers functions to find and load existing plugins and use the packaged component classes. To write a plugin, see Plugin development.

There are three types of plugins:

Shared object plugin

.so file on Unix systems; .dll file on Windows systems.

Python 3 plugin

.py file which starts with the bt_plugin_ prefix.

Static plugin

A plugin built directly into libbabeltrace2 or into the user application.

libbabeltrace2 loads shared object and Python plugins. Those plugins need libbabeltrace2 in turn to create and use Babeltrace 2 objects:

libbabeltrace2 loads plugins which need libbabeltrace2.

A plugin is a shared object: get a new reference with bt_plugin_get_ref() and put an existing reference with bt_plugin_put_ref().

Get the number of component class in a plugin with bt_plugin_get_source_component_class_count(), bt_plugin_get_filter_component_class_count(), and bt_plugin_get_sink_component_class_count().

Borrow a component class by index from a plugin with bt_plugin_borrow_source_component_class_by_index_const(), bt_plugin_borrow_filter_component_class_by_index_const(), and bt_plugin_borrow_sink_component_class_by_index_const().

Borrow a component class by name from a plugin with bt_plugin_borrow_source_component_class_by_name_const(), bt_plugin_borrow_filter_component_class_by_name_const(), and bt_plugin_borrow_sink_component_class_by_name_const().

The bt_plugin_find_all(), bt_plugin_find_all_from_file(), bt_plugin_find_all_from_dir(), and bt_plugin_find_all_from_static() functions return a plugin set, that is, a shared object containing one or more plugins.

Find and load plugins

The bt_plugin_find() and bt_plugin_find_all() functions find and load plugins from the default plugin search directories and from the static plugins.

The plugin search order is:

The colon-separated (or semicolon-separated on Windows) list of directories in the BABELTRACE_PLUGIN_PATH environment variable, if it's set.

The function searches each directory in this list, without recursing.
$HOME/.local/lib/babeltrace2/plugins, without recursing.
The system Babeltrace 2 plugin directory, typically /usr/lib/babeltrace2/plugins or /usr/local/lib/babeltrace2/plugins on Linux, without recursing.
The static plugins.

Both bt_plugin_find() and bt_plugin_find_all() functions have dedicated boolean parameters to include or exclude each of the four locations above.

Find and load a plugin by name

Find and load a plugin by name with bt_plugin_find().

bt_plugin_find() tries to find a plugin with a specific name within the default plugin search directories and static plugins.

Find and load all the plugins from the default directories

Load all the plugins found in the default plugin search directories and static plugins with bt_plugin_find_all().

Find and load plugins from a specific file or directory

Find and load plugins from a specific file (.so, .dll, or .py) with bt_plugin_find_all_from_file().

A single shared object file can contain multiple plugins, although it's not common practice to do so.

Find and load plugins from a specific directory with bt_plugin_find_all_from_dir(). This function can search for plugins within the given directory recursively or not.

Find and load static plugins

Find and load static plugins with bt_plugin_find_all_from_static().

A static plugin is built directly into the application or library instead of being a separate shared object file.

Plugin properties

A plugin has the following properties:

Name

Name of the plugin.

The plugin's name is not related to its file name. For example, a plugin found in the file patente.so can be named Dan.

Use bt_plugin_get_name().

Optional: Description

Description of the plugin.

Use bt_plugin_get_description().

Optional: Author name(s)

Name(s) of the plugin's author(s).

Use bt_plugin_get_author().

Optional: License

License or license name of the plugin.

Use bt_plugin_get_license().

Optional: Path

Path of the file which contains the plugin.

A static plugin has no path property.

Get bt_plugin_get_path().

Optional: Version

Version of the plugin (major, minor, patch, and extra information).

The plugin's version is completely user-defined: the library does not use this property in any way to verify the plugin's compatibility.

Use bt_plugin_get_version().

Type
typedef struct bt_plugin	bt_plugin
	Plugin.

typedef struct bt_plugin_set	bt_plugin_set
	Set of plugins.

Find and load plugins
enum	bt_plugin_find_status { BT_PLUGIN_FIND_STATUS_OK, BT_PLUGIN_FIND_STATUS_NOT_FOUND, BT_PLUGIN_FIND_STATUS_MEMORY_ERROR, BT_PLUGIN_FIND_STATUS_ERROR }
	Status codes for bt_plugin_find(). More...

enum	bt_plugin_find_all_status { BT_PLUGIN_FIND_ALL_STATUS_OK, BT_PLUGIN_FIND_ALL_STATUS_NOT_FOUND, BT_PLUGIN_FIND_ALL_STATUS_MEMORY_ERROR, BT_PLUGIN_FIND_ALL_STATUS_ERROR }
	Status codes for bt_plugin_find_all(). More...

enum	bt_plugin_find_all_from_file_status { BT_PLUGIN_FIND_ALL_FROM_FILE_STATUS_OK, BT_PLUGIN_FIND_ALL_FROM_FILE_STATUS_NOT_FOUND, BT_PLUGIN_FIND_ALL_FROM_FILE_STATUS_MEMORY_ERROR, BT_PLUGIN_FIND_ALL_FROM_FILE_STATUS_ERROR }
	Status codes for bt_plugin_find_all_from_file(). More...

enum	bt_plugin_find_all_from_dir_status { BT_PLUGIN_FIND_ALL_FROM_DIR_STATUS_OK, BT_PLUGIN_FIND_ALL_FROM_DIR_STATUS_NOT_FOUND, BT_PLUGIN_FIND_ALL_FROM_DIR_STATUS_MEMORY_ERROR, BT_PLUGIN_FIND_ALL_FROM_DIR_STATUS_ERROR }
	Status codes for bt_plugin_find_all_from_dir(). More...

enum	bt_plugin_find_all_from_static_status { BT_PLUGIN_FIND_ALL_FROM_STATIC_STATUS_OK, BT_PLUGIN_FIND_ALL_FROM_STATIC_STATUS_NOT_FOUND, BT_PLUGIN_FIND_ALL_FROM_STATIC_STATUS_MEMORY_ERROR, BT_PLUGIN_FIND_ALL_FROM_STATIC_STATUS_ERROR }
	Status codes for bt_plugin_find_all_from_static(). More...

typedef enum bt_plugin_find_status	bt_plugin_find_status
	Status codes for bt_plugin_find().

typedef enum bt_plugin_find_all_status	bt_plugin_find_all_status
	Status codes for bt_plugin_find_all().

typedef enum bt_plugin_find_all_from_file_status	bt_plugin_find_all_from_file_status
	Status codes for bt_plugin_find_all_from_file().

typedef enum bt_plugin_find_all_from_dir_status	bt_plugin_find_all_from_dir_status
	Status codes for bt_plugin_find_all_from_dir().

typedef enum bt_plugin_find_all_from_static_status	bt_plugin_find_all_from_static_status
	Status codes for bt_plugin_find_all_from_static().

bt_plugin_find_status	bt_plugin_find (const char plugin_name, bt_bool find_in_std_env_var, bt_bool find_in_user_dir, bt_bool find_in_sys_dir, bt_bool find_in_static, bt_bool fail_on_load_error, const bt_plugin *plugin)
	Finds and loads a single plugin which has the name plugin_name from the default plugin search directories and static plugins, setting *plugin to the result. More...

bt_plugin_find_all_status	bt_plugin_find_all (bt_bool find_in_std_env_var, bt_bool find_in_user_dir, bt_bool find_in_sys_dir, bt_bool find_in_static, bt_bool fail_on_load_error, const bt_plugin_set **plugins)
	Finds and loads all the plugins from the default plugin search directories and static plugins, setting *plugins to the result. More...

bt_plugin_find_all_from_file_status	bt_plugin_find_all_from_file (const char path, bt_bool fail_on_load_error, const bt_plugin_set *plugins)
	Finds and loads all the plugins from the file with path path, setting *plugins to the result. More...

bt_plugin_find_all_from_dir_status	bt_plugin_find_all_from_dir (const char path, bt_bool recurse, bt_bool fail_on_load_error, const bt_plugin_set *plugins)
	Finds and loads all the plugins from the directory with path path, setting *plugins to the result. More...

bt_plugin_find_all_from_static_status	bt_plugin_find_all_from_static (bt_bool fail_on_load_error, const bt_plugin_set **plugins)
	Finds and loads all the static plugins, setting *plugins to the result. More...

Plugin properties
const char *	bt_plugin_get_name (const bt_plugin *plugin)
	Returns the name of the plugin plugin. More...

const char *	bt_plugin_get_description (const bt_plugin *plugin)
	Returns the description of the plugin plugin. More...

const char *	bt_plugin_get_author (const bt_plugin *plugin)
	Returns the name(s) of the author(s) of the plugin plugin. More...

const char *	bt_plugin_get_license (const bt_plugin *plugin)
	Returns the license text or the license name of the plugin plugin. More...

const char *	bt_plugin_get_path (const bt_plugin *plugin)
	Returns the path of the file which contains the plugin plugin. More...

bt_property_availability	bt_plugin_get_version (const bt_plugin plugin, unsigned int major, unsigned int minor, unsigned int patch, const char **extra)
	Returns the version of the plugin plugin. More...

Plugin component class access
uint64_t	bt_plugin_get_source_component_class_count (const bt_plugin *plugin)
	Returns the number of source component classes contained in the plugin plugin. More...

uint64_t	bt_plugin_get_filter_component_class_count (const bt_plugin *plugin)
	Returns the number of filter component classes contained in the plugin plugin. More...

uint64_t	bt_plugin_get_sink_component_class_count (const bt_plugin *plugin)
	Returns the number of sink component classes contained in the plugin plugin. More...

const bt_component_class_source *	bt_plugin_borrow_source_component_class_by_index_const (const bt_plugin *plugin, uint64_t index)
	Borrows the source component class at index index from the plugin plugin. More...

const bt_component_class_filter *	bt_plugin_borrow_filter_component_class_by_index_const (const bt_plugin *plugin, uint64_t index)
	Borrows the filter component class at index index from the plugin plugin. More...

const bt_component_class_sink *	bt_plugin_borrow_sink_component_class_by_index_const (const bt_plugin *plugin, uint64_t index)
	Borrows the sink component class at index index from the plugin plugin. More...

const bt_component_class_source *	bt_plugin_borrow_source_component_class_by_name_const (const bt_plugin plugin, const char name)
	Borrows the source component class named name from the plugin plugin. More...

const bt_component_class_filter *	bt_plugin_borrow_filter_component_class_by_name_const (const bt_plugin plugin, const char name)
	Borrows the filter component class named name from the plugin plugin. More...

const bt_component_class_sink *	bt_plugin_borrow_sink_component_class_by_name_const (const bt_plugin plugin, const char name)
	Borrows the sink component class named name from the plugin plugin. More...

Plugin reference count
void	bt_plugin_get_ref (const bt_plugin *plugin)
	Increments the reference count of the plugin plugin. More...

void	bt_plugin_put_ref (const bt_plugin *plugin)
	Decrements the reference count of the plugin plugin. More...

#define	BT_PLUGIN_PUT_REF_AND_RESET(_plugin)
	Decrements the reference count of the plugin _plugin, and then sets _plugin to `NULL`. More...

#define	BT_PLUGIN_MOVE_REF(_dst, _src)
	Decrements the reference count of the plugin _dst, sets _dst to _src, and then sets _src to `NULL`. More...

Plugin set plugin access
uint64_t	bt_plugin_set_get_plugin_count (const bt_plugin_set *plugin_set)
	Returns the number of plugins contained in the plugin set plugin_set. More...

const bt_plugin *	bt_plugin_set_borrow_plugin_by_index_const (const bt_plugin_set *plugin_set, uint64_t index)
	Borrows the plugin at index index from the plugin set plugin_set. More...

Plugin set reference count
void	bt_plugin_set_get_ref (const bt_plugin_set *plugin_set)
	Increments the reference count of the plugin set plugin_set. More...

void	bt_plugin_set_put_ref (const bt_plugin_set *plugin_set)
	Decrements the reference count of the plugin set plugin_set. More...

#define	BT_PLUGIN_SET_PUT_REF_AND_RESET(_plugin_set)
	Decrements the reference count of the plugin set _plugin_set, and then sets _plugin_set to `NULL`. More...

#define	BT_PLUGIN_SET_MOVE_REF(_dst, _src)
	Decrements the reference count of the plugin set _dst, sets _dst to _src, and then sets _src to `NULL`. More...

Enumeration Type Documentation

◆ bt_plugin_find_status

enum bt_plugin_find_status

Status codes for bt_plugin_find().

Enumerator
BT_PLUGIN_FIND_STATUS_OK	Success.
BT_PLUGIN_FIND_STATUS_NOT_FOUND	Plugin not found.
BT_PLUGIN_FIND_STATUS_MEMORY_ERROR	Out of memory.
BT_PLUGIN_FIND_STATUS_ERROR	Error.

◆ bt_plugin_find_all_status

enum bt_plugin_find_all_status

Status codes for bt_plugin_find_all().

Enumerator
BT_PLUGIN_FIND_ALL_STATUS_OK	Success.
BT_PLUGIN_FIND_ALL_STATUS_NOT_FOUND	No plugins found.
BT_PLUGIN_FIND_ALL_STATUS_MEMORY_ERROR	Out of memory.
BT_PLUGIN_FIND_ALL_STATUS_ERROR	Error.

◆ bt_plugin_find_all_from_file_status

enum bt_plugin_find_all_from_file_status

Status codes for bt_plugin_find_all_from_file().

Enumerator
BT_PLUGIN_FIND_ALL_FROM_FILE_STATUS_OK	Success.
BT_PLUGIN_FIND_ALL_FROM_FILE_STATUS_NOT_FOUND	No plugins found.
BT_PLUGIN_FIND_ALL_FROM_FILE_STATUS_MEMORY_ERROR	Out of memory.
BT_PLUGIN_FIND_ALL_FROM_FILE_STATUS_ERROR	Error.

◆ bt_plugin_find_all_from_dir_status

enum bt_plugin_find_all_from_dir_status

Status codes for bt_plugin_find_all_from_dir().

Enumerator
BT_PLUGIN_FIND_ALL_FROM_DIR_STATUS_OK	Success.
BT_PLUGIN_FIND_ALL_FROM_DIR_STATUS_NOT_FOUND	No plugins found.
BT_PLUGIN_FIND_ALL_FROM_DIR_STATUS_MEMORY_ERROR	Out of memory.
BT_PLUGIN_FIND_ALL_FROM_DIR_STATUS_ERROR	Error.

◆ bt_plugin_find_all_from_static_status

enum bt_plugin_find_all_from_static_status

Status codes for bt_plugin_find_all_from_static().

Enumerator
BT_PLUGIN_FIND_ALL_FROM_STATIC_STATUS_OK	Success.
BT_PLUGIN_FIND_ALL_FROM_STATIC_STATUS_NOT_FOUND	No static plugins found.
BT_PLUGIN_FIND_ALL_FROM_STATIC_STATUS_MEMORY_ERROR	Out of memory.
BT_PLUGIN_FIND_ALL_FROM_STATIC_STATUS_ERROR	Error.

Macro Definition Documentation

◆ BT_PLUGIN_PUT_REF_AND_RESET

#define BT_PLUGIN_PUT_REF_AND_RESET ( _plugin )

Decrements the reference count of the plugin _plugin, and then sets _plugin to NULL.

Parameters

_plugin

Plugin of which to decrement the reference count.

Can contain NULL.

Precondition: _plugin is an assignable expression.

◆ BT_PLUGIN_MOVE_REF

#define BT_PLUGIN_MOVE_REF	(	_dst,
		_src
	)

Decrements the reference count of the plugin _dst, sets _dst to _src, and then sets _src to NULL.

This macro effectively moves a plugin reference from the expression _src to the expression _dst, putting the existing _dst reference.

Parameters

_dst

Destination expression.

Can contain NULL.

_src

Source expression.

Can contain NULL.

Precondition: _dst is an assignable expression.; _src is an assignable expression.

◆ BT_PLUGIN_SET_PUT_REF_AND_RESET

#define BT_PLUGIN_SET_PUT_REF_AND_RESET ( _plugin_set )

Decrements the reference count of the plugin set _plugin_set, and then sets _plugin_set to NULL.

Parameters

_plugin_set

Plugin set of which to decrement the reference count.

Can contain NULL.

Precondition: _plugin_set is an assignable expression.

◆ BT_PLUGIN_SET_MOVE_REF

#define BT_PLUGIN_SET_MOVE_REF	(	_dst,
		_src
	)

Decrements the reference count of the plugin set _dst, sets _dst to _src, and then sets _src to NULL.

This macro effectively moves a plugin set reference from the expression _src to the expression _dst, putting the existing _dst reference.

Parameters

_dst

Destination expression.

Can contain NULL.

_src

Source expression.

Can contain NULL.

Precondition: _dst is an assignable expression.; _src is an assignable expression.

Function Documentation

◆ bt_plugin_find()

bt_plugin_find_status bt_plugin_find	(	const char *	plugin_name,
		bt_bool	find_in_std_env_var,
		bt_bool	find_in_user_dir,
		bt_bool	find_in_sys_dir,
		bt_bool	find_in_static,
		bt_bool	fail_on_load_error,
		const bt_plugin **	plugin
	)

Finds and loads a single plugin which has the name plugin_name from the default plugin search directories and static plugins, setting *plugin to the result.

This function returns the first plugin which has the name plugin_name within, in order:

If the find_in_std_env_var parameter is BT_TRUE, the colon-separated (or semicolon-separated on Windows) list of directories in the BABELTRACE_PLUGIN_PATH environment variable, if it's set.

The function searches each directory in this list, without recursing.
If the find_in_user_dir parameter is BT_TRUE, $HOME/.local/lib/babeltrace2/plugins, without recursing.
If the find_in_sys_dir is BT_TRUE, the system Babeltrace 2 plugin directory, typically /usr/lib/babeltrace2/plugins or /usr/local/lib/babeltrace2/plugins on Linux, without recursing.
If the find_in_static is BT_TRUE, the static plugins.

Note: A plugin's name is not related to the name of its file (shared object or Python file). For example, a plugin found in the file patente.so can be named Dan.

If this function finds a file which looks like a plugin (shared object file or Python file with the bt_plugin_ prefix), but it fails to load it for any reason, the function:

If fail_on_load_error is BT_TRUE

Returns BT_PLUGIN_FIND_STATUS_ERROR.

If fail_on_load_error is BT_FALSE

Ignores the loading error and continues searching.

If this function doesn't find any plugin, it returns BT_PLUGIN_FIND_STATUS_NOT_FOUND and does not set *plugin.

Parameters

[in]	plugin_name	Name of the plugin to find and load.
[in]	find_in_std_env_var	BT_TRUE to try to find the plugin named plugin_name in the colon-separated (or semicolon-separated on Windows) list of directories in the `BABELTRACE_PLUGIN_PATH` environment variable.
[in]	find_in_user_dir	BT_TRUE to try to find the plugin named plugin_name in the `$HOME/.local/lib/babeltrace2/plugins` directory, without recursing.
[in]	find_in_sys_dir	BT_TRUE to try to find the plugin named plugin_name in the system Babeltrace 2 plugin directory.
[in]	find_in_static	BT_TRUE to try to find the plugin named plugin_name in the static plugins.
[in]	fail_on_load_error	BT_TRUE to make this function return BT_PLUGIN_FIND_STATUS_ERROR on any plugin loading error instead of ignoring it.
[out]	plugin	On success, *plugin is a new plugin reference of named plugin_name.

Return values

BT_PLUGIN_FIND_STATUS_OK	Success.
BT_PLUGIN_FIND_STATUS_NOT_FOUND	Plugin not found.
BT_PLUGIN_FIND_STATUS_MEMORY_ERROR	Out of memory.
BT_PLUGIN_FIND_STATUS_ERROR	Error.

Precondition: plugin_name is not NULL.; At least one of the find_in_std_env_var, find_in_user_dir, find_in_sys_dir, and find_in_static parameters is BT_TRUE.; plugin is not NULL.

See also: bt_plugin_find_all() — Finds and loads all plugins from the default plugin search directories and static plugins.

◆ bt_plugin_find_all()

bt_plugin_find_all_status bt_plugin_find_all	(	bt_bool	find_in_std_env_var,
		bt_bool	find_in_user_dir,
		bt_bool	find_in_sys_dir,
		bt_bool	find_in_static,
		bt_bool	fail_on_load_error,
		const bt_plugin_set **	plugins
	)

Finds and loads all the plugins from the default plugin search directories and static plugins, setting *plugins to the result.

This function returns all the plugins within, in order:

If the find_in_std_env_var parameter is BT_TRUE, the colon-separated (or semicolon-separated on Windows) list of directories in the BABELTRACE_PLUGIN_PATH environment variable, if it's set.

The function searches each directory in this list, without recursing.
If the find_in_user_dir parameter is BT_TRUE, $HOME/.local/lib/babeltrace2/plugins, without recursing.
If the find_in_sys_dir is BT_TRUE, the system Babeltrace 2 plugin directory, typically /usr/lib/babeltrace2/plugins or /usr/local/lib/babeltrace2/plugins on Linux, without recursing.
If the find_in_static is BT_TRUE, the static plugins.

During the search process, if a found plugin shares the name of an already loaded plugin, this function ignores it and continues.

If this function finds a file which looks like a plugin (shared object file or Python file with the bt_plugin_ prefix), but it fails to load it for any reason, the function:

If fail_on_load_error is BT_TRUE

Returns BT_PLUGIN_FIND_ALL_STATUS_ERROR.

If fail_on_load_error is BT_FALSE

Ignores the loading error and continues searching.

If this function doesn't find any plugin, it returns BT_PLUGIN_FIND_ALL_STATUS_NOT_FOUND and does not set *plugins.

Parameters

[in]	find_in_std_env_var	BT_TRUE to try to find all the plugins in the colon-separated (or semicolon-separated on Windows) list of directories in the `BABELTRACE_PLUGIN_PATH` environment variable.
[in]	find_in_user_dir	BT_TRUE to try to find all the plugins in the `$HOME/.local/lib/babeltrace2/plugins` directory, without recursing.
[in]	find_in_sys_dir	BT_TRUE to try to find all the plugins in the system Babeltrace 2 plugin directory.
[in]	find_in_static	BT_TRUE to try to find all the plugins in the static plugins.
[in]	fail_on_load_error	BT_TRUE to make this function return BT_PLUGIN_FIND_ALL_STATUS_ERROR on any plugin loading error instead of ignoring it.
[out]	plugins	On success, *plugins is a new plugin set reference which contains all the plugins found from the default plugin search directories and static plugins.

Return values

BT_PLUGIN_FIND_ALL_STATUS_OK	Success.
BT_PLUGIN_FIND_ALL_STATUS_NOT_FOUND	No plugins found.
BT_PLUGIN_FIND_ALL_STATUS_MEMORY_ERROR	Out of memory.
BT_PLUGIN_FIND_ALL_STATUS_ERROR	Error.

Precondition: At least one of the find_in_std_env_var, find_in_user_dir, find_in_sys_dir, and find_in_static parameters is BT_TRUE.; plugins is not NULL.

See also: bt_plugin_find() — Finds and loads a single plugin by name from the default plugin search directories and static plugins.

◆ bt_plugin_find_all_from_file()

bt_plugin_find_all_from_file_status bt_plugin_find_all_from_file	(	const char *	path,
		bt_bool	fail_on_load_error,
		const bt_plugin_set **	plugins
	)

Finds and loads all the plugins from the file with path path, setting *plugins to the result.

Note: A plugin's name is not related to the name of its file (shared object or Python file). For example, a plugin found in the file patente.so can be named Dan.

If any plugin loading error occurs during this function's execution, the function:

If fail_on_load_error is BT_TRUE

Returns BT_PLUGIN_FIND_ALL_FROM_FILE_STATUS_ERROR.

If fail_on_load_error is BT_FALSE

Ignores the loading error and continues.

If this function doesn't find any plugin, it returns BT_PLUGIN_FIND_ALL_FROM_FILE_STATUS_NOT_FOUND and does not set *plugins.

Parameters

[in]	path	Path of the file in which to find and load all the plugins.
[in]	fail_on_load_error	BT_TRUE to make this function return BT_PLUGIN_FIND_ALL_FROM_FILE_STATUS_ERROR on any plugin loading error instead of ignoring it.
[out]	plugins	On success, *plugins is a new plugin set reference which contains all the plugins found in the file with path path.

Return values

BT_PLUGIN_FIND_ALL_FROM_FILE_STATUS_OK	Success.
BT_PLUGIN_FIND_ALL_FROM_FILE_STATUS_NOT_FOUND	No plugins found.
BT_PLUGIN_FIND_ALL_FROM_FILE_STATUS_MEMORY_ERROR	Out of memory.
BT_PLUGIN_FIND_ALL_FROM_FILE_STATUS_ERROR	Error.

Precondition: path is not NULL.; path is the path of a regular file.; plugins is not NULL.

See also: bt_plugin_find_all_from_dir() — Finds and loads all plugins from a given directory.

◆ bt_plugin_find_all_from_dir()

bt_plugin_find_all_from_dir_status bt_plugin_find_all_from_dir	(	const char *	path,
		bt_bool	recurse,
		bt_bool	fail_on_load_error,
		const bt_plugin_set **	plugins
	)

Finds and loads all the plugins from the directory with path path, setting *plugins to the result.

If recurse is BT_TRUE, this function recurses into the subdirectories of path to find plugins.

During the search process, if a found plugin shares the name of an already loaded plugin, this function ignores it and continues.

Attention: As of Babeltrace 2.0, the file and directory traversal order is undefined.

If any plugin loading error occurs during this function's execution, the function:

If fail_on_load_error is BT_TRUE

Returns BT_PLUGIN_FIND_ALL_FROM_DIR_STATUS_ERROR.

If fail_on_load_error is BT_FALSE

Ignores the loading error and continues.

If this function doesn't find any plugin, it returns BT_PLUGIN_FIND_ALL_FROM_DIR_STATUS_NOT_FOUND and does not set *plugins.

Parameters

[in]	path	Path of the directory in which to find and load all the plugins.
[in]	recurse	BT_TRUE to make this function recurse into the subdirectories of path.
[in]	fail_on_load_error	BT_TRUE to make this function return BT_PLUGIN_FIND_ALL_FROM_DIR_STATUS_ERROR on any plugin loading error instead of ignoring it.
[out]	plugins	On success, *plugins is a new plugin set reference which contains all the plugins found in the directory with path path.

Return values

BT_PLUGIN_FIND_ALL_FROM_DIR_STATUS_OK	Success.
BT_PLUGIN_FIND_ALL_FROM_DIR_STATUS_NOT_FOUND	No plugins found.
BT_PLUGIN_FIND_ALL_FROM_DIR_STATUS_MEMORY_ERROR	Out of memory.
BT_PLUGIN_FIND_ALL_FROM_DIR_STATUS_ERROR	Error.

Precondition: path is not NULL.; path is the path of a directory.; plugins is not NULL.

See also: bt_plugin_find_all_from_file() — Finds and loads all plugins from a given file.

◆ bt_plugin_find_all_from_static()

bt_plugin_find_all_from_static_status bt_plugin_find_all_from_static	(	bt_bool	fail_on_load_error,
		const bt_plugin_set **	plugins
	)

Finds and loads all the static plugins, setting *plugins to the result.

A static plugin is built directly into the application or library instead of being a separate shared object file.

If any plugin loading error occurs during this function's execution, the function:

If fail_on_load_error is BT_TRUE

Returns BT_PLUGIN_FIND_ALL_FROM_STATIC_STATUS_ERROR.

If fail_on_load_error is BT_FALSE

Ignores the loading error and continues.

If this function doesn't find any plugin, it returns BT_PLUGIN_FIND_ALL_FROM_STATIC_STATUS_NOT_FOUND and does not set *plugins.

Parameters

[in]	fail_on_load_error	BT_TRUE to make this function return BT_PLUGIN_FIND_ALL_FROM_STATIC_STATUS_ERROR on any plugin loading error instead of ignoring it.
[out]	plugins	On success, *plugins is a new plugin set reference which contains all the static plugins.

Return values

BT_PLUGIN_FIND_ALL_FROM_STATIC_STATUS_OK	Success.
BT_PLUGIN_FIND_ALL_FROM_STATIC_STATUS_NOT_FOUND	No static plugins found.
BT_PLUGIN_FIND_ALL_FROM_STATIC_STATUS_MEMORY_ERROR	Out of memory.
BT_PLUGIN_FIND_ALL_FROM_STATIC_STATUS_ERROR	Error.

Precondition: path is not NULL.; plugins is not NULL.

◆ bt_plugin_get_name()

const char* bt_plugin_get_name ( const bt_plugin * plugin )

Returns the name of the plugin plugin.

See the name property.

Parameters

[in] plugin Plugin of which to get the name.

Returns

Name of plugin.

The returned pointer remains valid as long as plugin exists.

Precondition: plugin is not NULL.

◆ bt_plugin_get_description()

const char* bt_plugin_get_description ( const bt_plugin * plugin )

Returns the description of the plugin plugin.

See the description property.

Parameters

[in] plugin Plugin of which to get description.

Returns

Description of plugin, or NULL if not available.

The returned pointer remains valid as long as plugin exists.

Precondition: plugin is not NULL.

◆ bt_plugin_get_author()

const char* bt_plugin_get_author ( const bt_plugin * plugin )

Returns the name(s) of the author(s) of the plugin plugin.

See the author name(s) property.

Parameters

[in] plugin Plugin of which to get the author name(s).

Returns

Author name(s) of plugin, or NULL if not available.

The returned pointer remains valid as long as plugin exists.

Precondition: plugin is not NULL.

◆ bt_plugin_get_license()

const char* bt_plugin_get_license ( const bt_plugin * plugin )

Returns the license text or the license name of the plugin plugin.

See the license property.

Parameters

[in] plugin Plugin of which to get the license.

Returns

License of plugin, or NULL if not available.

The returned pointer remains valid as long as plugin exists.

Precondition: plugin is not NULL.

◆ bt_plugin_get_path()

const char* bt_plugin_get_path ( const bt_plugin * plugin )

Returns the path of the file which contains the plugin plugin.

See the path property.

This function returns NULL if plugin is a static plugin because a static plugin has no path property.

Parameters

[in] plugin Plugin of which to get the containing file's path.

Returns

Path of the file which contains plugin, or NULL if not available.

The returned pointer remains valid as long as plugin exists.

Precondition: plugin is not NULL.

◆ bt_plugin_get_version()

bt_property_availability bt_plugin_get_version	(	const bt_plugin *	plugin,
		unsigned int *	major,
		unsigned int *	minor,
		unsigned int *	patch,
		const char **	extra
	)

Returns the version of the plugin plugin.

See the version property.

Parameters

[in]	plugin	Plugin of which to get the version.
[out]	major	If not `NULL` and this function returns BT_PROPERTY_AVAILABILITY_AVAILABLE, *major is the major version of plugin.
[out]	minor	If not `NULL` and this function returns BT_PROPERTY_AVAILABILITY_AVAILABLE, *minor is the minor version of plugin.
[out]	patch	If not `NULL` and this function returns BT_PROPERTY_AVAILABILITY_AVAILABLE, *patch is the patch version of plugin.
[out]	extra	If not `NULL` and this function returns BT_PROPERTY_AVAILABILITY_AVAILABLE, extra is the version's extra information of plugin. extra can be `NULL` if the plugin's version has no extra information. *extra remains valid as long as plugin exists.

Return values

BT_PROPERTY_AVAILABILITY_AVAILABLE	The version of plugin is available.
BT_PROPERTY_AVAILABILITY_NOT_AVAILABLE	The version of plugin is not available.

Precondition: plugin is not NULL.

◆ bt_plugin_get_source_component_class_count()

uint64_t bt_plugin_get_source_component_class_count ( const bt_plugin * plugin )

Returns the number of source component classes contained in the plugin plugin.

Parameters

[in] plugin Plugin of which to get the number of contained source component classes.

Returns: Number of contained source component classes in plugin.

Precondition: plugin is not NULL.

◆ bt_plugin_get_filter_component_class_count()

uint64_t bt_plugin_get_filter_component_class_count ( const bt_plugin * plugin )

Returns the number of filter component classes contained in the plugin plugin.

Parameters

[in] plugin Plugin of which to get the number of contained filter component classes.

Returns: Number of contained filter component classes in plugin.

Precondition: plugin is not NULL.

◆ bt_plugin_get_sink_component_class_count()

uint64_t bt_plugin_get_sink_component_class_count ( const bt_plugin * plugin )

Returns the number of sink component classes contained in the plugin plugin.

Parameters

[in] plugin Plugin of which to get the number of contained sink component classes.

Returns: Number of contained sink component classes in plugin.

Precondition: plugin is not NULL.

◆ bt_plugin_borrow_source_component_class_by_index_const()

const bt_component_class_source* bt_plugin_borrow_source_component_class_by_index_const	(	const bt_plugin *	plugin,
		uint64_t	index
	)

Borrows the source component class at index index from the plugin plugin.

Parameters

[in]	plugin	Plugin from which to borrow the source component class at index index.
[in]	index	Index of the source component class to borrow from plugin.

Returns

Borrowed reference of the source component class of plugin at index index.

The returned pointer remains valid as long as plugin exists.

Precondition: plugin is not NULL.; index is less than the number of source component classes in plugin (as returned by bt_plugin_get_source_component_class_count()).

See also: bt_plugin_borrow_source_component_class_by_name_const() — Borrows a source component class by name from a plugin.

◆ bt_plugin_borrow_filter_component_class_by_index_const()

const bt_component_class_filter* bt_plugin_borrow_filter_component_class_by_index_const	(	const bt_plugin *	plugin,
		uint64_t	index
	)

Borrows the filter component class at index index from the plugin plugin.

Parameters

[in]	plugin	Plugin from which to borrow the filter component class at index index.
[in]	index	Index of the filter component class to borrow from plugin.

Returns

Borrowed reference of the filter component class of plugin at index index.

The returned pointer remains valid as long as plugin exists.

Precondition: plugin is not NULL.; index is less than the number of filter component classes in plugin (as returned by bt_plugin_get_source_component_class_count()).

See also: bt_plugin_borrow_source_component_class_by_name_const() — Borrows a filter component class by name from a plugin.

◆ bt_plugin_borrow_sink_component_class_by_index_const()

const bt_component_class_sink* bt_plugin_borrow_sink_component_class_by_index_const	(	const bt_plugin *	plugin,
		uint64_t	index
	)

Borrows the sink component class at index index from the plugin plugin.

Parameters

[in]	plugin	Plugin from which to borrow the sink component class at index index.
[in]	index	Index of the sink component class to borrow from plugin.

Returns

Borrowed reference of the sink component class of plugin at index index.

The returned pointer remains valid as long as plugin exists.

Precondition: plugin is not NULL.; index is less than the number of sink component classes in plugin (as returned by bt_plugin_get_source_component_class_count()).

See also: bt_plugin_borrow_source_component_class_by_name_const() — Borrows a sink component class by name from a plugin.

◆ bt_plugin_borrow_source_component_class_by_name_const()

const bt_component_class_source* bt_plugin_borrow_source_component_class_by_name_const	(	const bt_plugin *	plugin,
		const char *	name
	)

Borrows the source component class named name from the plugin plugin.

If no source component class has the name name within plugin, this function returns NULL.

Parameters

[in]	plugin	Plugin from which to borrow the source component class named name.
[in]	name	Name of the source component class to borrow from plugin.

Returns

Borrowed reference of the source component class of plugin named name, or NULL if no source component class is named name within plugin.

The returned pointer remains valid as long as plugin exists.

Precondition: plugin is not NULL.; name is not NULL.

See also: bt_plugin_borrow_source_component_class_by_index_const() — Borrows a source component class by index from a plugin.

◆ bt_plugin_borrow_filter_component_class_by_name_const()

const bt_component_class_filter* bt_plugin_borrow_filter_component_class_by_name_const	(	const bt_plugin *	plugin,
		const char *	name
	)

Borrows the filter component class named name from the plugin plugin.

If no filter component class has the name name within plugin, this function returns NULL.

Parameters

[in]	plugin	Plugin from which to borrow the filter component class named name.
[in]	name	Name of the filter component class to borrow from plugin.

Returns

Borrowed reference of the filter component class of plugin named name, or NULL if no filter component class is named name within plugin.

The returned pointer remains valid as long as plugin exists.

Precondition: plugin is not NULL.; name is not NULL.

See also: bt_plugin_borrow_filter_component_class_by_index_const() — Borrows a filter component class by index from a plugin.

◆ bt_plugin_borrow_sink_component_class_by_name_const()

const bt_component_class_sink* bt_plugin_borrow_sink_component_class_by_name_const	(	const bt_plugin *	plugin,
		const char *	name
	)

Borrows the sink component class named name from the plugin plugin.

If no sink component class has the name name within plugin, this function returns NULL.

Parameters

[in]	plugin	Plugin from which to borrow the sink component class named name.
[in]	name	Name of the sink component class to borrow from plugin.

Returns

Borrowed reference of the sink component class of plugin named name, or NULL if no sink component class is named name within plugin.

The returned pointer remains valid as long as plugin exists.

Precondition: plugin is not NULL.; name is not NULL.

See also: bt_plugin_borrow_sink_component_class_by_index_const() — Borrows a sink component class by index from a plugin.

◆ bt_plugin_get_ref()

void bt_plugin_get_ref ( const bt_plugin * plugin )

Increments the reference count of the plugin plugin.

Parameters

[in]

plugin

Plugin of which to increment the reference count.

Can be NULL.

See also: bt_plugin_put_ref() — Decrements the reference count of a plugin.

◆ bt_plugin_put_ref()

void bt_plugin_put_ref ( const bt_plugin * plugin )

Decrements the reference count of the plugin plugin.

Parameters

[in]

plugin

Plugin of which to decrement the reference count.

Can be NULL.

See also: bt_plugin_get_ref() — Increments the reference count of a plugin.

◆ bt_plugin_set_get_plugin_count()

uint64_t bt_plugin_set_get_plugin_count ( const bt_plugin_set * plugin_set )

Returns the number of plugins contained in the plugin set plugin_set.

Parameters

[in] plugin_set Plugin set of which to get the number of contained plugins.

Returns: Number of contained plugins in plugin_set.

Precondition: plugin is not NULL.

◆ bt_plugin_set_borrow_plugin_by_index_const()

const bt_plugin* bt_plugin_set_borrow_plugin_by_index_const	(	const bt_plugin_set *	plugin_set,
		uint64_t	index
	)

Borrows the plugin at index index from the plugin set plugin_set.

Parameters

[in]	plugin_set	Plugin set from which to borrow the plugin at index index.
[in]	index	Index of the plugin to borrow from plugin_set.

Returns

Borrowed reference of the plugin of plugin_set at index index.

The returned pointer remains valid until plugin_set is modified.

Precondition: plugin_set is not NULL.; index is less than the number of plugins in plugin_set (as returned by bt_plugin_set_get_plugin_count()).

◆ bt_plugin_set_get_ref()

void bt_plugin_set_get_ref ( const bt_plugin_set * plugin_set )

Increments the reference count of the plugin set plugin_set.

Parameters

[in]

plugin_set

Plugin set of which to increment the reference count.

Can be NULL.

See also: bt_plugin_set_put_ref() — Decrements the reference count of a plugin set.

◆ bt_plugin_set_put_ref()

void bt_plugin_set_put_ref ( const bt_plugin_set * plugin_set )

Decrements the reference count of the plugin set plugin_set.

Parameters

[in]

plugin_set

Plugin set of which to decrement the reference count.

Can be NULL.

See also: bt_plugin_set_get_ref() — Increments the reference count of a plugin set.

Detailed Description

Find and load plugins

Find and load a plugin by name

Find and load all the plugins from the default directories

Find and load plugins from a specific file or directory

Find and load static plugins

Plugin properties

Type

Find and load plugins

Plugin properties

Plugin component class access

Plugin reference count

Plugin set plugin access

Plugin set reference count

Enumeration Type Documentation

◆ bt_plugin_find_status

◆ bt_plugin_find_all_status

◆ bt_plugin_find_all_from_file_status

◆ bt_plugin_find_all_from_dir_status

◆ bt_plugin_find_all_from_static_status

Macro Definition Documentation

◆ BT_PLUGIN_PUT_REF_AND_RESET

◆ BT_PLUGIN_MOVE_REF

◆ BT_PLUGIN_SET_PUT_REF_AND_RESET

◆ BT_PLUGIN_SET_MOVE_REF

Function Documentation

◆ bt_plugin_find()

◆ bt_plugin_find_all()

◆ bt_plugin_find_all_from_file()

◆ bt_plugin_find_all_from_dir()

◆ bt_plugin_find_all_from_static()

◆ bt_plugin_get_name()

◆ bt_plugin_get_description()

◆ bt_plugin_get_author()

◆ bt_plugin_get_license()

◆ bt_plugin_get_path()

◆ bt_plugin_get_version()

◆ bt_plugin_get_source_component_class_count()

◆ bt_plugin_get_filter_component_class_count()

◆ bt_plugin_get_sink_component_class_count()

◆ bt_plugin_borrow_source_component_class_by_index_const()

◆ bt_plugin_borrow_filter_component_class_by_index_const()

◆ bt_plugin_borrow_sink_component_class_by_index_const()

◆ bt_plugin_borrow_source_component_class_by_name_const()

◆ bt_plugin_borrow_filter_component_class_by_name_const()

◆ bt_plugin_borrow_sink_component_class_by_name_const()

◆ bt_plugin_get_ref()

◆ bt_plugin_put_ref()

◆ bt_plugin_set_get_plugin_count()

◆ bt_plugin_set_borrow_plugin_by_index_const()

◆ bt_plugin_set_get_ref()

◆ bt_plugin_set_put_ref()