1libtraceevent(3) 2================ 3 4NAME 5---- 6tep_load_plugins, tep_unload_plugins, tep_load_plugins_hook, tep_add_plugin_path, 7tep_plugin_add_option - Load / unload traceevent plugins. 8 9SYNOPSIS 10-------- 11[verse] 12-- 13*#include <event-parse.h>* 14 15struct tep_plugin_list pass:[*]*tep_load_plugins*(struct tep_handle pass:[*]_tep_); 16void *tep_unload_plugins*(struct tep_plugin_list pass:[*]_plugin_list_, struct tep_handle pass:[*]_tep_); 17void *tep_load_plugins_hook*(struct tep_handle pass:[*]_tep_, const char pass:[*]_suffix_, 18 void (pass:[*]_load_plugin_)(struct tep_handle pass:[*]tep, 19 const char pass:[*]path, 20 const char pass:[*]name, 21 void pass:[*]data), 22 void pass:[*]_data_); 23int *tep_add_plugin_path*(struct tep_handle pass:[*]tep, char pass:[*]path, 24 enum tep_plugin_load_priority prio); 25int *tep_plugin_add_option*(const char pass:[*]_name_, const char pass:[*]_val_); 26-- 27 28DESCRIPTION 29----------- 30The *tep_load_plugins()* function loads all plugins, located in the plugin 31directories. The _tep_ argument is trace event parser context. 32The plugin directories are : 33[verse] 34-- 35 - Directories, specified in _tep_->plugins_dir with priority TEP_PLUGIN_FIRST 36 - System's plugin directory, defined at the library compile time. It 37 depends on the library installation prefix and usually is 38 _(install_preffix)/lib/traceevent/plugins_ 39 - Directory, defined by the environment variable _TRACEEVENT_PLUGIN_DIR_ 40 - User's plugin directory, located at _~/.local/lib/traceevent/plugins_ 41 - Directories, specified in _tep_->plugins_dir with priority TEP_PLUGIN_LAST 42-- 43Loading of plugins can be controlled by the _tep_flags_, using the 44*tep_set_flag()* API: 45[verse] 46-- 47 _TEP_DISABLE_SYS_PLUGINS_ - do not load plugins, located in 48 the system's plugin directory. 49 _TEP_DISABLE_PLUGINS_ - do not load any plugins. 50-- 51The *tep_set_flag()* API needs to be called before *tep_load_plugins()*, if 52loading of all plugins is not the desired case. 53 54The *tep_unload_plugins()* function unloads the plugins, previously loaded by 55*tep_load_plugins()*. The _tep_ argument is trace event parser context. The 56_plugin_list_ is the list of loaded plugins, returned by 57the *tep_load_plugins()* function. 58 59The *tep_load_plugins_hook()* function walks through all directories with plugins 60and calls user specified *load_plugin()* hook for each plugin file. Only files 61with given _suffix_ are considered to be plugins. The _data_ is a user specified 62context, passed to *load_plugin()*. Directories and the walk order are the same 63as in *tep_load_plugins()* API. 64 65The *tep_add_plugin_path()* functions adds additional directories with plugins in 66the _tep_->plugins_dir list. It must be called before *tep_load_plugins()* in order 67for the plugins from the new directories to be loaded. The _tep_ argument is 68the trace event parser context. The _path_ is the full path to the new plugin 69directory. The _prio_ argument specifies the loading priority order for the 70new directory of plugins. The loading priority is important in case of different 71versions of the same plugin located in multiple plugin directories.The last loaded 72plugin wins. The priority can be: 73[verse] 74-- 75 _TEP_PLUGIN_FIRST_ - Load plugins from this directory first 76 _TEP_PLUGIN_LAST_ - Load plugins from this directory last 77-- 78Where the plugins in TEP_PLUGIN_LAST" will take precedence over the 79plugins in the other directories. 80 81The *tep_plugin_add_option()* sets options defined by a plugin. The _name_ is the 82name of the option to set to _val_. Plugins can add options to change its behavior 83and *tep_plugin_add_option()* is used by the application to make those modifications. 84 85 86RETURN VALUE 87------------ 88The *tep_load_plugins()* function returns a list of successfully loaded plugins, 89or NULL in case no plugins are loaded. 90The *tep_add_plugin_path()* function returns -1 in case of an error, 0 otherwise. 91 92EXAMPLE 93------- 94[source,c] 95-- 96#include <event-parse.h> 97... 98struct tep_handle *tep = tep_alloc(); 99... 100tep_add_plugin_path(tep, "~/dev_plugins", TEP_PLUGIN_LAST); 101... 102struct tep_plugin_list *plugins = tep_load_plugins(tep); 103if (plugins == NULL) { 104 /* no plugins are loaded */ 105} 106... 107tep_unload_plugins(plugins, tep); 108... 109void print_plugin(struct tep_handle *tep, const char *path, 110 const char *name, void *data) 111{ 112 pritnf("Found libtraceevent plugin %s/%s\n", path, name); 113} 114... 115tep_load_plugins_hook(tep, ".so", print_plugin, NULL); 116... 117-- 118 119FILES 120----- 121[verse] 122-- 123*event-parse.h* 124 Header file to include in order to have access to the library APIs. 125*-ltraceevent* 126 Linker switch to add when building a program that uses the library. 127-- 128 129SEE ALSO 130-------- 131*libtraceevent*(3), *trace-cmd*(1), *tep_set_flag*(3) 132 133AUTHOR 134------ 135[verse] 136-- 137*Steven Rostedt* <[email protected]>, author of *libtraceevent*. 138*Tzvetomir Stoyanov* <[email protected]>, author of this man page. 139-- 140REPORTING BUGS 141-------------- 142Report bugs to <[email protected]> 143 144LICENSE 145------- 146libtraceevent is Free Software licensed under the GNU LGPL 2.1 147 148RESOURCES 149--------- 150https://git.kernel.org/pub/scm/libs/libtrace/libtraceevent.git/ 151