--- name: "tracefs_instance_get_name" section: "3" platform: "linux" package: "libtracefs" version: "1.8.4-1" release: "Arch Linux 2026-11-01" platforms: ["linux"] url: "https://new.carta.tech/tracefs_instance_get_name" --- # tracefs\_instance\_get\_name(3) Helper functions for working with tracing instances. ## NAME tracefs\_instance\_get\_name, tracefs\_instance\_get\_trace\_dir, tracefs\_instances\_walk, tracefs\_instance\_exists, tracefs\_instance\_get\_buffer\_size, tracefs\_instance\_set\_buffer\_size, tracefs\_instance\_get\_buffer\_percent, tracefs\_instance\_set\_buffer\_percent - Helper functions for working with tracing instances. ## SYNOPSIS ``` #include const char *tracefs_instance_get_name(struct tracefs_instance *instance); const char *tracefs_instance_get_trace_dir(struct tracefs_instance *instance); int tracefs_instances_walk(int (*callback)(const char *, void *), void *context); bool tracefs_instance_exists(const char *name); size_t tracefs_instance_get_buffer_size(struct tracefs_instance *instance, int cpu); int tracefs_instance_set_buffer_size(struct tracefs_instance *instance, size_t size, int cpu); int tracefs_instance_get_buffer_percent(struct tracefs_instance *instance); int tracefs_instance_set_buffer_percent(struct tracefs_instance *instance, int val); ``` ## DESCRIPTION Helper functions for working with trace instances. The **tracefs\_instance\_get\_name()** function returns the name of the given *instance*. Note that the top instance has no name, the function returns NULL for it. The **tracefs\_instance\_get\_trace\_dir()** function returns the tracing directory, where the given *instance* is configured. The **tracefs\_instances\_walk()** function walks through all configured tracing instances in the system and calls *callback* for each one of them. The *context* argument is passed to the *callback*, together with the instance name. If the *callback* returns non-zero, the iteration stops. Note, the *callback* is not called for the top top instance. The **tracefs\_instance\_exists()** function checks if an instance with the given *name* exists in the system. The **tracefs\_instace\_get\_buffer\_size()** returns the size of the ring buffer. If *cpu* is negative, it returns the total size of all the per CPU ring buffers, otherwise it returns the size of the per CPU ring buffer for *cpu*. The **tracefs\_instance\_set\_buffer\_size()** function sets the size of the ring buffer. If *cpu* is negative, then it sets all the per CPU ring buffers to *size* (note the total size is the number of CPUs \* *size*). If *cpu* is specified, then it only sets the size of the per CPU ring buffer. The **tracefs\_instance\_set\_buffer\_percent()** sets the buffer percent value of the tracing ring buffer for *instance* or the top level buffer if *instance* is NULL. The buffer percent decides when readers on [**tracefs\_cpu\_read**(3)](/tracefs_cpu_read/3.md), [**tracefs\_cpu\_buffered\_read**(3)](/tracefs_cpu_buffered_read/3.md), [**tracefs\_cpu\_write**(3)](/tracefs_cpu_write/3.md) and [**tracefs\_cpu\_pipe**(3)](/tracefs_cpu_pipe/3.md) will block when O\_NONBLOCK is not set. The value of *val* must be between 0 and 100, where: ``` 0 - block until there’s any data in the ring buffer 1 - block until 1% of the ring buffer sub-buffers are filled 50 - block until 50% of the ring buffer sub-buffers are filled 100 - block until the entire ring buffer is filled ``` Note, any number from 0 to 100 can be used where it is the percentage of the ring buffer that must be filled before a blocked reader will be notified that there’s data to be retrieved. The **tracefs\_instance\_get\_buffer\_percent()** retrieves the current buffer percent setting of the tracing ring buffer for *instance* or the top level buffer if *instance* is NULL. ## RETURN VALUE The **tracefs\_instance\_get\_name()** returns a string or NULL in case of the top instance. The returned string must *not* be freed. The **tracefs\_instance\_get\_trace\_dir()** returns a string or NULL in case of an error. The returned string must *not* be freed. The **tracefs\_instances\_walk()** function returns 0, if all instances were iterated, 1 if the iteration was stopped by the *callback*, or -1 in case of an error. The **tracefs\_instance\_exists()** returns true if an instance with the given *name* exists in the system or false otherwise. The **tracefs\_instance\_get\_buffer\_size()** returns the size of the ring buffer depending on the *cpu* value passed in, or -1 on error. The **tracefs\_instance\_set\_buffer\_size()** returns zero on success and -1 on error. ## EXAMPLE ``` #include struct tracefs_instance *inst; .... char *name = tracefs_instance_get_name(inst); if(name) { /* Got name of the instance */ } char *dir = tracefs_instance_get_trace_dir(inst); if(dir) { /* Got tracing directory of the instance */ } ... static int instance_walk(char *name, void *context) { /* Got instance with name */ return 0; } ... if (tracefs_instances_walk(instance_walk, NULL) < 0) { /* Error walking through the instances */ } ... if (tracefs_instance_exists("foo")) { /* There is instance with name foo in the system */ } else { /* There is no instance with name foo in the system */ } ``` ## FILES ``` tracefs.h Header file to include in order to have access to the library APIs. -ltracefs Linker switch to add when building a program that uses the library. ``` ## SEE ALSO [**libtracefs**(3)](/libtracefs/3.md), [**libtraceevent**(3)](/libtraceevent/3.md), [**trace-cmd**(1)](/trace-cmd/1.md) ## AUTHOR ``` Steven Rostedt Tzvetomir Stoyanov ``` ## REPORTING BUGS Report bugs to \<**linux-trace-devel@vger.kernel.org**\[3\]\> ## LICENSE libtracefs is Free Software licensed under the GNU LGPL 2.1 ## RESOURCES **https://git.kernel.org/pub/scm/libs/libtrace/libtracefs.git/** ## 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