LIBTRACEFS(3)

📦
version 1.8.4 · 12 versions
, in arch rolling

💖 LIBTRACEFS(3) — the libtracefs manual, bestie edition 💖

okay so this is the libtracefs manual page, and today we're doing the cute little helper functions for poking at the trace file system. no cap, these are the glue functions you'll reach for constantly. let's go 🫶

✨ NAME ✨

tracefs_tracers, tracefs_tracer_available, tracefs_get_clock, tracefs_list_free, tracefs_list_add, tracefs_list_size — literally the helper functions for working with the trace file system. that's the whole vibe. 💅

🌸 SYNOPSIS 🌸

#include <tracefs.h>

char **tracefs_tracers(const char *tracing_dir);
bool tracefs_tracer_available(const char *tracing_dir, const char *tracer);
char *tracefs_get_clock(struct tracefs_instance *instance);
void tracefs_list_free(char **list);
char **tracefs_list_add(char *list, const char *string);
int *tracefs_list_size(char **list);

copy these exactly, they're iconic and we don't edit icons ✨

🦋 DESCRIPTION 🦋

so basically: various useful functions for working with the trace file system. that's the summary. now the tea, one function at a time ☕

  • tracefs_tracers() — returns an array of strings with the names of all the supported tracer plugins, pulled from whatever tracing_dir directory you hand it. and bestie, tracing_dir has range: it can be NULL, or it can be the location of the tracefs mount point for your local machine's trace systems, or it can even be a path to a copy of a tracefs directory from another machine. so flexible, we love her 💖 the last entry in the array is a NULL pointer (classic terminator behavior, periodt). and the array must be freed with the tracefs_list_free() API. don't forget, or it's giving leak energy 😭
  • tracefs_tracer_available() — returns true if the tracer is available in the given tracing_dir directory, and false otherwise. simple, clean, no notes 👑
  • tracefs_get_clock() — returns the name of the current trace clock used in the given instance. if instance is NULL, you get the clock of the main trace instance instead. the returned string must be freed with free(). yes, plain free(), not the list one. iykyk 🎀
  • tracefs_list_free() — frees an array of strings, specifically the ones returned by the tracefs_event_systems(), tracefs_system_events() and tracefs_tracers() APIs. this is your cleanup bestie, be nice to her 🧹
  • tracefs_list_add() — adds string to the string list. here's the mechanics, listen up:
    • if list is NULL, then a new list is created with the first element being a copy of string, and the second element being a NULL pointer. brand new list, fresh start, main character energy ✨
    • if list is not NULL, then it is reallocated to include a new element and a NULL terminator, and the new allocated array is returned.
    • ⚠️ the list you passed in should be ignored, because it will be freed if a new one was allocated. do not touch it. do not look at it. it's gone, girl 💀
  • tracefs_list_size() — a fast way to find out the number of elements in a string array that is to be freed with tracefs_list_free(). but real talk: this depends on meta data that is created for these lists, and it will not work on normal string arrays like argv. so don't try it on argv. i'm serious. it will not slay. 🙈

🔥 RETURN VALUE 🔥

  • tracefs_tracers() returns an array of strings. the last element in that array is a NULL pointer. the array must be freed with tracefs_list_free() API. in case of an error, NULL is returned. 😔
  • tracefs_tracer_available() returns true if the tracer is available, and false otherwise. short and sweet 💜
  • tracefs_get_clock() returns a string — which you must free with free() — or NULL in case of an error.
  • tracefs_list_add() returns an allocated string array that must be freed with tracefs_list_free() on success, or NULL on error. and here's the important bit: if NULL is returned, then the passed-in list is untouched. so you should treat tracefs_list_add() similarly to realloc(3). same energy, same rules, no cap ⭐
  • tracefs_list_size() returns the number of strings in the list. the passed-in list must be one that is to be freed with tracefs_list_free(), because the list has meta data that's used to determine the size — and this does not work on any normal string array like argv. saying it twice because it matters, bestie 🫶

🌈 EXAMPLE 🌈

#include <tracefs.h>

char **tracers = tracefs_tracers(NULL);

    if (tracers) {
        /* Got tracer plugins from the top trace instance */
        ...
        tracefs_list_free(tracers);
    }
....
char *clock = tracefs_get_clock(NULL);

    if (clock) {
        /* Got current trace clock of the top trace instance */
        ...
        free(clock);
    }

see how each one gets cleaned up with the right free function? that's the whole lesson. she's consistent, she's tidy, she ate 💅

🎀 FILES 🎀

  • tracefs.h — the header file to include in order to have access to the library APIs. include her or nothing works, bestie.
  • -ltracefs — the linker switch to add when building a program that uses the library. don't forget it or you'll be staring at undefined references like 😭

👑 SEE ALSO 👑

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

go read those too, they're the supporting cast and they're all icons in their own right 🌸

🌟 AUTHOR 🌟

  • Steven Rostedt <rostedt@goodmis.org<sup>1</sup>>
  • Tzvetomir Stoyanov <tz.stoyanov@gmail.com<sup>2</sup>>

absolute legends, we stan 🫶

💀 REPORTING BUGS 💀

report bugs to <linux-trace-devel@vger.kernel.org<sup>3</sup>>

found a bug? tell the mailing list, don't just suffer in silence 🙈

🍓 LICENSE 🍓

libtracefs is Free Software licensed under the GNU LGPL 2.1. free as in freedom, protected as in license 💜

🧚 RESOURCES 🧚

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

that's the repo. go look at it. touch grass after, but look at it first ✨

⭐ COPYING ⭐

Copyright (C) 2020 VMware, Inc. Free use of this software is granted under the terms of the GNU Public License (GPL).

💖 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 page!! 🎉 this whole thing is libtracefs 1.8.4, dated 10/21/2026 — so go forth, free your lists, free your strings with the correct free, and remember: tracefs_list_size() does not work on argv. love u, bye 💅💖🦋

📦 where this page comes from