LIBTRACEEVENT(3)

💖 LIBTRACEEVENT 💖

okay bestie, gather round, because this is your girl's guide to the libtraceevent manual page — specifically the plugin-loading era of your life. This one covers tep_load_plugins, tep_unload_plugins, tep_load_plugins_hook, tep_add_plugin_path and tep_plugin_add_option, aka the whole "load / unload traceevent plugins" situation. 🔌✨

---

🌸 NAME 🌸

tep_load_plugins, tep_unload_plugins, tep_load_plugins_hook, tep_add_plugin_path, tep_plugin_add_option — load and unload traceevent plugins. that's the whole job description, no cap. 💅

---

✨ SYNOPSIS ✨

#include <event-parse.h>

struct tep_plugin_list *tep_load_plugins(struct tep_handle *tep);
void tep_unload_plugins(struct tep_plugin_list *plugin_list, struct tep_handle *tep);
void tep_load_plugins_hook(struct tep_handle *tep, const char *suffix,
                           void (*load_plugin)(struct tep_handle *tep,
                                               const char *path,
                                               const char *name,
                                               void *data),
                           void *data);
int tep_add_plugin_path(struct tep_handle *tep, char *path,
                          enum tep_plugin_load_priority prio);
int tep_plugin_add_option(const char *name, const char *val);

---

🎀 DESCRIPTION 🎀

so. tep_load_plugins() loads all the plugins hanging out in the plugin directories. the tep argument is your trace event parser context, obviously. 🫶

and the plugin directories, in order, are literally these:

• Directories, specified in tep→plugins_dir with priority TEP_PLUGIN_FIRST
• System's plugin directory, defined at the library compile time. It depends on the library installation prefix and usually is (install_preffix)/lib/traceevent/plugins
• Directory, defined by the environment variable TRACEEVENT_PLUGIN_DIR
• User's plugin directory, located at ~/.local/lib/traceevent/plugins
• Directories, specified in tep→plugins_dir with priority TEP_PLUGIN_LAST

now, whether all of that actually happens is a whole vibe check you can control with the tep_flags, using the tep_set_flag() API:

• TEP_DISABLE_SYS_PLUGINS — do not load plugins, located in the system's plugin directory.
• TEP_DISABLE_PLUGINS — do not load any plugins.

bestie listen — you have to call the tep_set_flag() API before tep_load_plugins(), otherwise you get all the plugins whether you wanted them or not. if loading all plugins is not the desired case, this is your moment. ⚠️

tep_unload_plugins() unloads the plugins, previously loaded by tep_load_plugins(). the tep argument is the trace event parser context, and plugin_list is the list of loaded plugins, returned by the tep_load_plugins() function. bye girl 👋

tep_load_plugins_hook() walks through all directories with plugins and calls your user specified load_plugin() hook for each plugin file. only files with the given suffix are considered to be plugins, so don't come for me when your .txt files get ignored. the data is a user specified context, passed to load_plugin(). and the directories and the walk order are the same as in the tep_load_plugins() API — no surprises, we keep it consistent. 💯

tep_add_plugin_path() adds additional directories with plugins into the tep→plugins_dir list. and like… it must be called before tep_load_plugins() in order for the plugins from the new directories to be loaded. the tep argument is the trace event parser context. the path is the full path to the new plugin directory. the prio argument specifies the loading priority order for the new directory of plugins. and why do we care about priority? because different versions of the same plugin can be sitting in multiple plugin directories, and the last loaded plugin wins. periodt. so the priority can be:

• TEP_PLUGIN_FIRST — Load plugins from this directory first
• TEP_PLUGIN_LAST — Load plugins from this directory last

where the plugins in TEP_PLUGIN_LAST will take precedence over the plugins in the other directories. 👑

tep_plugin_add_option() sets options defined by a plugin. the name is the name of the option to set to val. plugins can add options to change its behavior, and tep_plugin_add_option() is used by the application to make those modifications. character customization, but for plugins. 💅

---

👑 RETURN VALUE 👑

tep_load_plugins() returns a list of successfully loaded plugins, or NULL in case no plugins are loaded. tep_add_plugin_path() returns -1 in case of an error, 0 otherwise. simple as. ✨

---

🦋 EXAMPLE 🦋

#include <event-parse.h>
...
struct tep_handle *tep = tep_alloc();
...
tep_add_plugin_path(tep, "~/dev_plugins", TEP_PLUGIN_LAST);
...
struct tep_plugin_list *plugins = tep_load_plugins(tep);
if (plugins == NULL) {
        /* no plugins are loaded */
}
...
tep_unload_plugins(plugins, tep);
...
void print_plugin(struct tep_handle *tep, const char *path,
                  const char *name, void *data)
{
        pritnf("Found libtraceevent plugin %s/%s\n", path, name);
}
...
tep_load_plugins_hook(tep, ".so", print_plugin, NULL);
...

not me pointing out that yes, it's spelled pritnf in there, and yes we're keeping it exactly as written. copy the example at your own risk, bestie 😭

---

🌈 FILES 🌈

• event-parse.h — Header file to include in order to have access to the library APIs.
• -ltraceevent — Linker switch to add when building a program that uses the library.

---

💜 SEE ALSO 💜

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

---

🍓 AUTHOR 🍓

• Steven Rostedt <rostedt@goodmis.org>, author of libtraceevent.
• Tzvetomir Stoyanov <tz.stoyanov@gmail.com>, author of this man page.

---

🧚 REPORTING BUGS 🧚

Report bugs to <linux-trace-devel@vger.kernel.org>

---

💖 LICENSE 💖

libtraceevent is Free Software licensed under the GNU LGPL 2.1

---

⭐ RESOURCES ⭐

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

---

🌸 NOTES 🌸

1. rostedt@goodmis.org mailto:rostedt@goodmis.org
2. tz.stoyanov@gmail.com mailto:tz.stoyanov@gmail.com
3. linux-trace-devel@vger.kernel.org mailto:linux-trace-devel@vger.kernel.org

---

and that's the whole page, bestie!! this was libtraceevent 1.9.0, dated 06/15/2026, and yes it lives in section LIBTRACEEVENT(3). go load some plugins, you absolute icon 🎀✨💅