# tracefs_instance_get_name

## 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 <tracefs.h>**
    
           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_buffered_read(3),
           tracefs_cpu_write(3) and tracefs_cpu_pipe(3) 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 <tracefs.h>
    
               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.
    


## 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
    


* * *