LIBTRACEFS(3)

📦
version 1.8.4 · 13 versions
, in arch rolling

💅 LIBTRACEFS(3) — libtracefs Manual, bestie edition 🎀

okay so this is the libtracefs manual page, and today we're talking about the little squad of functions that turn tracing on and off. six functions, one job: flipping the switch on your ring buffer. let's get into it ✨

✨ NAME ✨

tracefs_trace_is_on, tracefs_trace_on, tracefs_trace_off, tracefs_trace_on_get_fd, tracefs_trace_on_fd, tracefs_trace_off_fd — literally the functions that enable or disable tracing. that's the whole vibe 🦋

🌸 SYNOPSIS 🌸

#include <tracefs.h>

int tracefs_trace_is_on(struct tracefs_instance *instance);
int tracefs_trace_on(struct tracefs_instance *instance);
int tracefs_trace_off(struct tracefs_instance *instance);
int tracefs_trace_on_get_fd(struct tracefs_instance *instance);
int tracefs_trace_on_fd(int fd);
int tracefs_trace_off_fd(int fd);

💖 DESCRIPTION 💖

this whole little set of functions is your ring-buffer remote control 📺 — you use them to check, enable, or disable writing to the ring buffer in whatever trace instance you're messing with. and like, the rule is simple: tracing is enabled when writing to the ring buffer is enabled. that's it. iykyk.

  • tracefs_trace_is_on() — checks whether tracing is enabled for the instance you gave it. if instance is NULL, it just uses the top instance. king of defaults 👑
  • tracefs_trace_on() and tracefs_trace_off() — set the tracing in that instance to enabled or disabled. and yeah, if instance is NULL, top instance again. iconic consistency.
  • tracefs_trace_on_get_fd() — hands you a file descriptor to the "tracing_on" file of the given instance. instance is NULL? top trace instance, obviously 💁‍♀️. the descriptor it gives back is the fast path for enabling or disabling tracing on that instance — keep it around, it's your shortcut.
  • tracefs_trace_on_fd() and tracefs_trace_off_fd() — enable or disable tracing using that fd. heads up though: this descriptor must be opened for writing with tracefs_trace_on_get_fd(3) on the trace instance you actually want. and bestie, these two are faster than tracefs_trace_on and tracefs_trace_off. speed. 🏎️

🔥 RETURN VALUE 🔥

  • tracefs_trace_is_on() — returns 0 if tracing is disabled, 1 if it's enabled, or -1 if something went wrong 😭.
  • tracefs_trace_on_get_fd() — returns a file descriptor to the "tracing_on" file, open for reading and writing, and you must close it with close(). if there's an error, you get -1. no cap.
  • tracefs_trace_on(), tracefs_trace_off(), tracefs_trace_on_fd() and tracefs_trace_off_fd() — return -1 on an error, or 0 otherwise. clean. simple. slay.

🦋 EXAMPLE 🦋

    #include <tracefs.h>

            int ret;

            ret = tracefs_trace_is_on(NULL);
            if (ret == 0) {
                    /* Tracing is disabled in the top instance */
            } else if (ret == 1) {
                    /* Tracing is enabled in the top instance */
            } else {
                    /* Error getting tracing state of the top instance */
            }

            ...

            if (!tracefs_trace_on(NULL)) {
                /* Enabled tracing in the top instance */

                ...

                if (!tracefs_trace_off(NULL)) {
                    /* Disabled tracing in the top instance */
                } else {
                    /* Error disabling tracing in the top instance */
                }
            } else {
                /* Error enabling tracing in the top instance */
            }

            ...

            int fd = tracefs_trace_on_get_fd(NULL);

            if (fd < 0) {
                    /* Error opening tracing_on file */
            }
            ...
            if (!tracefs_trace_on_fd(fd)) {
                /* Enabled tracing in the top instance */

                ...

                if (!tracefs_trace_off_fd(fd)) {
                    /* Disabled tracing in the top instance */
                } else {
                    /* Error disabling tracing in the top instance */
                }
            } else {
                /* Error enabling tracing in the top instance */
            }

            ...

            close(fd);

see? open it, flip it, flip it back, close it. the whole character arc 🫶

🎀 FILES 🎀

  • tracefs.h — the header file you include so you actually get access to the library APIs. don't forget it, bestie, it's kind of important.
  • -ltracefs — the linker switch you add when building a program that uses the library. link it or it simply won't work 💀

🌈 SEE ALSO 🌈

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

go read those too, they're all in the same friend group 💜

👑 AUTHOR 👑

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

🙈 REPORTING BUGS 🙈

found a bug? report it to <linux-trace-devel@vger.kernel.org>. they're nice, i promise 🍓

⭐ LICENSE ⭐

libtracefs is Free Software licensed under the GNU LGPL 2.1. periodt.

🧚 RESOURCES 🧚

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

that's the repo, go wild ✨

💜 COPYING 💜

Copyright (C) 2021 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 was libtracefs version 1.8.4, dated 10/21/2026 — shoutout to the libtracefs girlies, go enable some tracing for me, ily, bye 💅💖🦋

📦 where this page comes from