1LIBTRACEEVENT(3)             libtraceevent Manual             LIBTRACEEVENT(3)
2
3
4

NAME

6       tep_load_plugins, tep_unload_plugins, tep_load_plugins_hook,
7       tep_add_plugin_path - Load / unload traceevent plugins.
8

SYNOPSIS

10       #include <event-parse.h>
11
12       struct tep_plugin_list *tep_load_plugins(struct tep_handle *tep);
13       void tep_unload_plugins(struct tep_plugin_list *plugin_list, struct tep_handle *tep);
14       void tep_load_plugins_hook(struct tep_handle *tep, const char *suffix,
15                                  void (*load_plugin)(struct tep_handle *tep,
16                                                      const char *path,
17                                                      const char *name,
18                                                      void *data),
19                                  void *data);
20       int tep_add_plugin_path(struct tep_handle *tep, char *path,
21                                 enum tep_plugin_load_priority prio);
22

DESCRIPTION

24       The tep_load_plugins() function loads all plugins, located in the
25       plugin directories. The tep argument is trace event parser context. The
26       plugin directories are :
27
28                   - Directories, specified in tep→plugins_dir with priority TEP_PLUGIN_FIRST
29                   - System’s plugin directory, defined at the library compile time. It
30                     depends on the library installation prefix and usually is
31                     (install_preffix)/lib/traceevent/plugins
32                   - Directory, defined by the environment variable TRACEEVENT_PLUGIN_DIR
33                   - User’s plugin directory, located at ~/.local/lib/traceevent/plugins
34                   - Directories, specified in tep→plugins_dir with priority TEP_PLUGIN_LAST
35
36       Loading of plugins can be controlled by the tep_flags, using the
37       tep_set_flag() API:
38
39                   TEP_DISABLE_SYS_PLUGINS       - do not load plugins, located in
40                                                   the system’s plugin directory.
41                   TEP_DISABLE_PLUGINS           - do not load any plugins.
42
43       The tep_set_flag() API needs to be called before tep_load_plugins(), if
44       loading of all plugins is not the desired case.
45
46       The tep_unload_plugins() function unloads the plugins, previously
47       loaded by tep_load_plugins(). The tep argument is trace event parser
48       context. The plugin_list is the list of loaded plugins, returned by the
49       tep_load_plugins() function.
50
51       The tep_load_plugins_hook() function walks through all directories with
52       plugins and calls user specified load_plugin() hook for each plugin
53       file. Only files with given suffix are considered to be plugins. The
54       data is a user specified context, passed to load_plugin(). Directories
55       and the walk order are the same as in tep_load_plugins() API.
56
57       The tep_add_plugin_path() functions adds additional directories with
58       plugins in the tep→plugins_dir list. It must be called before
59       tep_load_plugins() in order for the plugins from the new directories to
60       be loaded. The tep argument is the trace event parser context. The path
61       is the full path to the new plugin directory. The prio argument
62       specifies the loading priority order for the new directory of plugins.
63       The loading priority is important in case of different versions of the
64       same plugin located in multiple plugin directories.The last loaded
65       plugin wins. The priority can be:
66
67                   TEP_PLUGIN_FIRST      - Load plugins from this directory first
68                   TEP_PLUGIN_LAST       - Load plugins from this directory last
69
70       Where the plugins in TEP_PLUGIN_LAST" will take precedence over the
71       plugins in the other directories.
72

RETURN VALUE

74       The tep_load_plugins() function returns a list of successfully loaded
75       plugins, or NULL in case no plugins are loaded. The
76       tep_add_plugin_path() function returns -1 in case of an error, 0
77       otherwise.
78

EXAMPLE

80           #include <event-parse.h>
81           ...
82           struct tep_handle *tep = tep_alloc();
83           ...
84           tep_add_plugin_path(tep, "~/dev_plugins", TEP_PLUGIN_LAST);
85           ...
86           struct tep_plugin_list *plugins = tep_load_plugins(tep);
87           if (plugins == NULL) {
88                   /* no plugins are loaded */
89           }
90           ...
91           tep_unload_plugins(plugins, tep);
92           ...
93           void print_plugin(struct tep_handle *tep, const char *path,
94                             const char *name, void *data)
95           {
96                   pritnf("Found libtraceevent plugin %s/%s\n", path, name);
97           }
98           ...
99           tep_load_plugins_hook(tep, ".so", print_plugin, NULL);
100           ...
101

FILES

103           event-parse.h
104                   Header file to include in order to have access to the library APIs.
105           -ltraceevent
106                   Linker switch to add when building a program that uses the library.
107

SEE ALSO

109       libtraceevent(3), trace-cmd(1), tep_set_flag(3)
110

AUTHOR

112           Steven Rostedt <rostedt@goodmis.org[1]>, author of libtraceevent.
113           Tzvetomir Stoyanov <tz.stoyanov@gmail.com[2]>, author of this man page.
114

REPORTING BUGS

116       Report bugs to <linux-trace-devel@vger.kernel.org[3]>
117

LICENSE

119       libtraceevent is Free Software licensed under the GNU LGPL 2.1
120

RESOURCES

122       https://git.kernel.org/pub/scm/libs/libtrace/libtraceevent.git/
123

NOTES

125        1. rostedt@goodmis.org
126           mailto:rostedt@goodmis.org
127
128        2. tz.stoyanov@gmail.com
129           mailto:tz.stoyanov@gmail.com
130
131        3. linux-trace-devel@vger.kernel.org
132           mailto:linux-trace-devel@vger.kernel.org
133
134
135
136libtraceevent 1.1.1               02/08/2021                  LIBTRACEEVENT(3)
Impressum