LIBTRACEFS(3)

📦
version 1.8.4 · 12 versions
, in arch rolling

💅 LIBTRACEFS(3) — the libtracefs girlies' guide to CPU affinity 🎀

okay so this is a page from the libtracefs manual (yes, that libtracefs, the libtracefs library, we're doing this) and today's topic is: which CPUs are even allowed to trace. buckle up bestie 🦋

✨ NAME ✨

tracefs_instance_set_affinity, tracefs_instance_set_affinity_set, tracefs_instance_set_affinity_raw, tracefs_instance_get_affinity, tracefs_instance_get_affinity_set, tracefs_instance_get_affinity_raw — these ones set or retrieve the affinity for an instance, or for the top level, and affinity here means which CPUs get tracing enabled. periodt 💅

🌸 SYNOPSIS 🌸

#include <tracefs.h>

int tracefs_instance_set_affinity(struct tracefs_instance *instance, const char *cpu_str);
int tracefs_instance_set_affinity_set(struct tracefs_instance *instance, cpu_set_t *set, size_t set_size);
int tracefs_instance_set_affinity_raw(struct tracefs_instance *instance, const char *mask);

char *tracefs_instance_get_affinity(struct tracefs_instance *instance);
int tracefs_instance_get_affinity_set(struct tracefs_instance *instance, cpu_set_t *set, size_t set_size);
char *tracefs_instance_get_affinity_raw(struct tracefs_instance *instance);

💖 DESCRIPTION 💖

so these functions lowkey set or retrieve the CPU affinity that limits what CPUs will have tracing enabled for a given instance, and that instance is the one defined by the instance parameter. and listen — if instance is NULL, then it's the top level instance that gets affected. main character energy ✨

🧚 tracefs_instance_set_affinity()

this one takes a string cpu_str that is a list of CPUs to set the affinity for. if cpu_str is NULL, then literally all the CPUs in the system will be set. no cap.

the format of cpu_str is a comma delimited string of decimal numbers, no spaces, and you can specify a range with a hyphen. it's giving:

"1,4,6-8"

the numbers do not need to be in order — except for ranges, where the second number must be equal to or greater than the first. so 6-8 is iconic, 8-6 is not 🙈

🎀 tracefs_instance_set_affinity_set()

takes a CPU set defined by CPU_SET(3). the size of the set defined by set_size is the size in bytes of set. and if set is NULL then all the CPUs on the system will be set, and set_size is just… ignored, she's not needed 💀

🦋 tracefs_instance_set_affinity_raw()

takes a string that holds a hexidecimal bitmask, where each 32 bits is separated by a comma. for a machine with more than 32 CPUs, to set CPUS 1-10 and CPU 40:

"100,000007fe"

where the above is a hex representation of bits 1-10 and bit 40 being set. math ate, honestly 🔥

⭐ tracefs_instance_get_affinity()

retrieves the affinity in a human readable form. like:

"1,4,6-8"

the string returned must be freed with free(3). don't forget, bestie, that's a memory leak waiting to happen 😭

💜 tracefs_instance_get_affinity_set()

will set all the bits in the passed in cpu set (from CPU_SET(3)). note — it will not clear any bits that are already set in the set but the CPUs are not. so if you only want the bits for the CPUs that are enabled to be set, you should do a CPU_ZERO_S() on the set before calling this function. consider this your vibe check ✅

🌈 tracefs_instance_get_affinity_raw()

will simply read the instance tracing_cpumask and return that string. the returned string must be freed with free(3). again. free her. 🫶

👑 RETURN VALUE 👑

  • all the set functions return 0 on success and -1 on error.
  • tracefs_instance_get_affinity() and tracefs_instance_get_affinity_raw() return an allocated string that must be freed with free(3), or NULL on error.
  • tracefs_instance_get_affinity_set() returns the number of CPUs that were found set, or -1 on error.

💀 ERRORS 💀

the following errors are for all the above calls:

  • EFBIG — if a CPU is set that is greater than what is in the system. she's out of range, bestie, that CPU does not exist 🙈
  • EINVAL — one of the parameters was invalid.

the following errors are for tracefs_instance_set_affinity() and tracefs_instance_set_affinity_set():

  • ENOMEM — memory allocation error. rip 🪦
  • ENODEV — dynamic events of requested type are not configured for the running kernel.

the following errors are just for tracefs_instance_set_affinity():

  • EACCES — the cpu_str was modified by another thread when processing it. yes, another thread really said "not on my watch" 😭

🔥 EXAMPLE 🔥

#include <sched.h>
#include <stdio.h>
#include <stdlib.h>
#include <tracefs.h>

int main (int argc, char **argv)
{
        struct trace_seq seq;
        cpu_set_t *set;
        size_t set_size;
        char *c;
        int cpu1;
        int cpu2;
        int i;

        c = tracefs_instance_get_affinity(NULL);
        printf("The affinity was %s\n", c);
        free(c);

        if (argc < 2) {
                tracefs_instance_set_affinity(NULL, NULL);
                exit(0);
        }
        /* Show example using a set */
        if (argc == 2 && !strchr(argv[1],',')) {
                cpu1 = atoi(argv[1]);
                c = strchr(argv[1], '-');
                if (c++)
                        cpu2 = atoi(c);
                else
                        cpu2 = cpu1;
                if (cpu2 < cpu1) {
                        fprintf(stderr, "Invalid CPU range\n");
                        exit(-1);
                }
                set = CPU_ALLOC(cpu2 + 1);
                set_size = CPU_ALLOC_SIZE(cpu2 + 1);
                CPU_ZERO_S(set_size, set);
                for ( ; cpu1 <= cpu2; cpu1++)
                        CPU_SET(cpu1, set);
                tracefs_instance_set_affinity_set(NULL, set, set_size);
                CPU_FREE(set);
                exit(0);
        }

        trace_seq_init(&seq);
        for (i = 1; i < argc; i++) {
                if (i > 1)
                        trace_seq_putc(&seq, ',');
                trace_seq_puts(&seq, argv[i]);
        }
        trace_seq_terminate(&seq);
        tracefs_instance_set_affinity(NULL, seq.buffer);
        trace_seq_destroy(&seq);
        exit(0);

        return 0;
}

like, she does it all — get it, print it, set it from a set, set it from a string. multi-talented 💅✨

🍓 FILES 🍓

  • tracefs.h — header file to include in order to have access to the library APIs. yes, you gotta #include her.
  • -ltracefs — linker switch to add when building a program that uses the library. don't forget her at link time or it's giving undefined reference 😭

🌸 SEE ALSO 🌸

libtracefs(3), libtraceevent(3), trace-cmd(1) — go read those too, iykyk 🦋

🎀 AUTHOR 🎀

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

legends, honestly 👑

🫶 REPORTING BUGS 🫶

report bugs to <linux-trace-devel@vger.kernel.org[3]>. they wanna hear from you, bestie, fr fr 💌

⭐ LICENSE ⭐

libtracefs is Free Software licensed under the GNU LGPL 2.1.

🌈 RESOURCES 🌈

https://git.kernel.org/pub/scm/libs/libtrace/libtracefs.git/ — the source, the whole vibe, go look ✨

💜 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 whole page, babes 💖 this was libtracefs 1.8.4, dated 10/21/2026 — go forth and set your affinity responsibly, mwah 🎀✨💅

📦 where this page comes from