tools/lib/traceevent/Documentation/libtraceevent-plugins.txt

   1 libtraceevent(3)
   2 ================
   3
   4 NAME
   5 ----
   6 tep_load_plugins, tep_unload_plugins, tep_load_plugins_hook - Load / unload traceevent plugins.
   7
   8 SYNOPSIS
   9 --------
  10 [verse]
  11 --
  12 *#include <event-parse.h>*
  13
  14 struct tep_plugin_list pass:[*]*tep_load_plugins*(struct tep_handle pass:[*]_tep_);
  15 void *tep_unload_plugins*(struct tep_plugin_list pass:[*]_plugin_list_, struct tep_handle pass:[*]_tep_);
  16 void *tep_load_plugins_hook*(struct tep_handle pass:[*]_tep_, const char pass:[*]_suffix_,
  17                            void (pass:[*]_load_plugin_)(struct tep_handle pass:[*]tep,
  18                                                const char pass:[*]path,
  19                                                const char pass:[*]name,
  20                                                void pass:[*]data),
  21                            void pass:[*]_data_);
  22 --
  23
  24 DESCRIPTION
  25 -----------
  26 The _tep_load_plugins()_ function loads all plugins, located in the plugin
  27 directories. The _tep_ argument is trace event parser context.
  28 The plugin directories are :
  29 [verse]
  30 --
  31         - Directories, specified in _tep_->plugins_dir with priority TEP_PLUGIN_FIRST
  32         - System's plugin directory, defined at the library compile time. It
  33           depends on the library installation prefix and usually is
  34           _(install_preffix)/lib/traceevent/plugins_
  35         - Directory, defined by the environment variable _TRACEEVENT_PLUGIN_DIR_
  36         - User's plugin directory, located at _~/.local/lib/traceevent/plugins_
  37         - Directories, specified in _tep_->plugins_dir with priority TEP_PLUGIN_LAST
  38 --
  39 Loading of plugins can be controlled by the _tep_flags_, using the
  40 _tep_set_flag()_ API:
  41 [verse]
  42 --
  43         _TEP_DISABLE_SYS_PLUGINS_       - do not load plugins, located in
  44                                         the system's plugin directory.
  45         _TEP_DISABLE_PLUGINS_           - do not load any plugins.
  46 --
  47 The _tep_set_flag()_ API needs to be called before _tep_load_plugins()_, if
  48 loading of all plugins is not the desired case.
  49
  50 The _tep_unload_plugins()_ function unloads the plugins, previously loaded by
  51 _tep_load_plugins()_. The _tep_ argument is trace event parser context. The
  52 _plugin_list_ is the list of loaded plugins, returned by
  53 the _tep_load_plugins()_ function.
  54
  55 The _tep_load_plugins_hook_ function walks through all directories with plugins
  56 and calls user specified _load_plugin()_ hook for each plugin file. Only files
  57 with given _suffix_ are considered to be plugins. The _data_ is a user specified
  58 context, passed to _load_plugin()_. Directories and the walk order are the same
  59 as in _tep_load_plugins()_ API.
  60
  61 RETURN VALUE
  62 ------------
  63 The _tep_load_plugins()_ function returns a list of successfully loaded plugins,
  64 or NULL in case no plugins are loaded.
  65
  66 EXAMPLE
  67 -------
  68 [source,c]
  69 --
  70 #include <event-parse.h>
  71 ...
  72 struct tep_handle *tep = tep_alloc();
  73 ...
  74 struct tep_plugin_list *plugins = tep_load_plugins(tep);
  75 if (plugins == NULL) {
  76         /* no plugins are loaded */
  77 }
  78 ...
  79 tep_unload_plugins(plugins, tep);
  80 ...
  81 void print_plugin(struct tep_handle *tep, const char *path,
  82                   const char *name, void *data)
  83 {
  84         pritnf("Found libtraceevent plugin %s/%s\n", path, name);
  85 }
  86 ...
  87 tep_load_plugins_hook(tep, ".so", print_plugin, NULL);
  88 ...
  89 --
  90
  91 FILES
  92 -----
  93 [verse]
  94 --
  95 *event-parse.h*
  96         Header file to include in order to have access to the library APIs.
  97 *-ltraceevent*
  98         Linker switch to add when building a program that uses the library.
  99 --
 100
 101 SEE ALSO
 102 --------
 103 _libtraceevent(3)_, _trace-cmd(1)_, _tep_set_flag(3)_
 104
 105 AUTHOR
 106 ------
 107 [verse]
 108 --
 109 *Steven Rostedt* <rostedt@goodmis.org>, author of *libtraceevent*.
 110 *Tzvetomir Stoyanov* <tz.stoyanov@gmail.com>, author of this man page.
 111 --
 112 REPORTING BUGS
 113 --------------
 114 Report bugs to  <linux-trace-devel@vger.kernel.org>
 115
 116 LICENSE
 117 -------
 118 libtraceevent is Free Software licensed under the GNU LGPL 2.1
 119
 120 RESOURCES
 121 ---------
 122 https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git