# tracefs_instance_create

## NAME



           tracefs_instance_create, tracefs_instance_destroy,
           tracefs_instance_alloc, tracefs_instance_free,
           tracefs_instance_is_new, tracefs_instances,
           tracefs_instance_clear, tracefs_instance_reset - Manage trace
           instances.
    


## SYNOPSIS



           **#include <tracefs.h>**
    
           struct tracefs_instance * **tracefs_instance_create**(const char *_name_);
           int **tracefs_instance_destroy**(struct tracefs_instance *_instance_);
           struct tracefs_instance * **tracefs_instance_alloc**(const char *_tracing_dir_ , const char *_name_);
           void **tracefs_instance_free**(struct tracefs_instance *_instance_);
           bool **tracefs_instance_is_new**(struct tracefs_instance *_instance_);
           char ** **tracefs_instances**(const char *_regex_);
           void **tracefs_instance_clear**(struct tracefs_instance *_instance_);
           void **tracefs_instance_reset**(struct tracefs_instance *_instance_);
    


## DESCRIPTION



           This set of functions can be used to manage trace instances. A
           trace instance is a sub buffer used by the Linux tracing system.
           Given a unique name, the events enabled in an instance do not
           affect the main tracing system, nor other instances, as events
           enabled in the main tracing system or other instances do not
           affect the given instance.
    
           The **tracefs_instance_create()** function allocates and initializes a
           new tracefs_instance structure and returns it. If the instance
           with _name_ does not yet exist in the system, it will be created.
           The _name_ could be NULL, then the new tracefs_instance structure is
           initialized for the top instance. Note that the top instance
           cannot be created in the system, if it does not exist.
    
           The **tracefs_instance_destroy()** removes the instance from the
           system, but does not free the structure. **tracefs_instance_free()**
           must still be called on _instance_.
    
           The tracefs_instance_alloc()* function allocates a new
           tracefs_instance structure for existing trace instance. If the
           instance does not exist in the system, the function fails. The
           _tracing_dir_ parameter points to the system trace directory. It can
           be NULL, then default system trace directory is used. This
           parameter is useful to allocate instances to trace directories,
           copied from another machine. The _name_ is the name of the instance,
           or NULL for the top instance in the given _tracing_dir_.
    
           The **tracefs_instance_free()** function frees the tracefs_instance
           structure, without removing the trace instance from the system.
    
           The **tracefs_instance_is_new()** function checks if the given
           _instance_ is newly created by **tracefs_instance_create()** , or it has
           been in the system before that.
    
           The **tracefs_instances**() function returns a list of instances that
           exist in the system that match the regular expression _regex_. If
           _regex_ is NULL, then it will match all instances that exist. The
           returned list must be freed with tracefs_list_free(3). Note, if no
           instances are found an empty list is returned and that too needs
           to be free with tracefs_list_free(3).
    
           The **tracefs_instance_clear()** function clears the ring buffer of
           the given _instance_ or the top level ring buffer if _instance_ is
           NULL.
    
           The **tracefs_instance_reset**() function resets the given _instance_ to
           its default state.
    


## RETURN VALUE



           The **tracefs_instance_create()** and **tracefs_instance_alloc()**
           functions return a pointer to a newly allocated tracefs_instance
           structure. It must be freed with **tracefs_instance_free()**.
    
           The **tracefs_instance_destroy()** function returns 0 if it succeeds
           to remove the instance, otherwise it returns -1 if the instance
           does not exist or it fails to remove it.
    
           The **tracefs_instance_is_new()** function returns true if the
           **tracefs_instance_create()** that allocated _instance_ also created the
           trace instance in the system, or false if the trace instance
           already existed in the system when _instance_ was allocated by
           **tracefs_instance_create()** or **tracefs_instance_alloc()**.
    
           The **tracefs_instances()** returns a list of instance names that
           exist on the system. The list must be freed with
           tracefs_list_free(3). An empty list is returned if no instance
           exists that matches _regex_ , and this needs to be freed with
           tracefs_list_free(3) as well. NULL is returned on error.
    
           The **tracefs_instance_clear()** returns 0 if it successfully cleared
           the ring buffer, or -1 on error.
    


## EXAMPLE



               #include <tracefs.h>
    
               struct tracefs_instance *inst = tracefs_instance_create("foo");
                       if (!inst) {
                               /* Error creating a new trace instance */
                               ...
                       }
    
                       ...
    
                       if (tracefs_instance_is_new(inst))
                               tracefs_instance_destroy(inst);
                       tracefs_instance_free(inst);
               ...
    
               struct tracefs_instance *inst = tracefs_instance_alloc(NULL, "bar");
                       if (!inst) {
                               /* Error allocating 'bar' trace instance */
                               ...
                       }
    
                       ...
                       tracefs_instance_reset(inst);
                       tracefs_instance_free(inst);
    


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


* * *