# tracefs_instance_file_open

## NAME



           tracefs_instance_file_open, tracefs_instance_file_write,
           tracefs_instance_file_write_number, tracefs_instance_file_append,
           tracefs_instance_file_clear, tracefs_instance_file_read,
           tracefs_instance_file_read_number - Work with files in tracing
           instances.
    


## SYNOPSIS



           **#include <tracefs.h>**
    
           int **tracefs_instance_file_open**(struct tracefs_instance *_instance_ , const char *_file_ , int _mode_);
           int **tracefs_instance_file_write**(struct tracefs_instance *_instance_ , const char *_file_ , const char *_str_);
           int **tracefs_instance_file_write_number**(struct tracefs_instance *_instance_ , const char *_file_ , size_t _val_);
           int **tracefs_instance_file_append**(struct tracefs_instance *_instance_ , const char *_file_ , const char *_str_);
           int **tracefs_instance_file_clear**(struct tracefs_instance *_instance_ , const char *_file_);
           char * **tracefs_instance_file_read**(struct tracefs_instance *_instance_ , const char *_file_ , int *_psize_);
           int **tracefs_instance_file_read_number**(struct tracefs_instance *_instance_ , const char *_file_ , long long int *_res_);
    


## DESCRIPTION



           This set of APIs can be used to work with trace files in all trace
           instances. Each of these APIs take an _instance_ argument, that can
           be NULL to act on the top level instance. Otherwise, it acts on an
           instance created with **tracefs_insance_create**(3)
    
           The **tracefs_instance_file_open()** function opens trace _file_ from
           given _instance_ and returns a file descriptor to it. The file
           access _mode_ can be specified, see **open**(3) for more details. If -1
           is passed as _mode_ , default O_RDWR is used.
    
           The **tracefs_instance_file_write()** function writes a string _str_ in
           a _file_ from the given _instance_ , without the terminating NULL
           character. When opening the file, this function tries to truncates
           the size of the file to zero, which clears all previously existing
           settings.
    
           The **tracefs_instance_file_write_number()** function converts _val_
           into a string and then writes it to the given file. This is a
           helper function that does the number conversion to string and then
           calls **tracefs_instance_file_write()**.
    
           The **tracefs_instance_file_append()** function writes a string _str_ in
           a _file_ from the given _instance_ , without the terminating NULL
           character. This function is similar to
           **tracefs_instance_file_write()** , but the existing content of the is
           not cleared. Thus the new settings are appended to the existing
           ones (if any).
    
           The **tracefs_instance_file_clear()** function tries to truncates the
           size of the file to zero, which clears all previously existing
           settings. If the file has content that does not get cleared in
           this way, this will not have any effect.
    
           The **tracefs_instance_file_read()** function reads the content of a
           _file_ from the given _instance_.
    
           The **tracefs_instance_file_read_number()** function reads the content
           of a _file_ from the given _instance_ and converts it to a long long
           integer, which is stored in _res_.
    


## RETURN VALUE



           The **tracefs_instance_file_open()** function returns a file
           descriptor to the opened file. It must be closed with **close**(3). In
           case of an error, -1 is returned.
    
           The **tracefs_instance_file_write()** function returns the number of
           written bytes, or -1 in case of an error.
    
           The **tracefs_instance_file_write_number()** function returns 0 on
           success and -1 on error.
    
           The **tracefs_instance_file_append()** function returns the number of
           written bytes, or -1 in case of an error.
    
           The **tracefs_instance_file_clear()** function returns 0 on success,
           or -1 in case of an error.
    
           The **tracefs_instance_file_read()** function returns a pointer to a
           NULL terminated string, read from the file, or NULL in case of an
           error. The returned string must be freed with free().
    
           The **tracefs_instance_file_read_number()** function returns 0 if a
           valid integer is read from the file and stored in _res_ or -1 in
           case of an error.
    


## EXAMPLE



               #include <tracefs.h>
    
               struct tracefs_instance *inst = tracefs_instance_create("foo");
                       if (!inst) {
                               /* Error creating a new trace instance */
                               ...
                       }
    
                       if (tracefs_file_exists(inst,"trace_clock")) {
                               /* The instance foo supports trace clock */
                               char *path, *clock;
                               int size;
    
                               path =  = tracefs_instance_get_file(inst, "trace_clock")
                               if (!path) {
                                       /* Error getting the path to trace_clock file in instance foo */
                                       ...
                               }
                               ...
                               tracefs_put_tracing_file(path);
    
                               clock = tracefs_instance_file_read(inst, "trace_clock", &size);
                               if (!clock) {
                                       /* Failed to read trace_clock file in instance foo */
                                       ...
                               }
                               ...
                               free(clock);
    
                               if (tracefs_instance_file_write(inst, "trace_clock", "global") != strlen("global")) {
                                       /* Failed to set gloabl trace clock in instance foo */
                                       ...
                               }
                       } else {
                               /* The instance foo does not support trace clock */
                       }
    
                       if (tracefs_dir_exists(inst,"options")) {
                               /* The instance foo supports trace options */
                               char *path = tracefs_instance_get_file(inst, "options");
                               if (!path) {
                                       /* Error getting the path to options directory in instance foo */
                                       ...
                               }
    
                               tracefs_put_tracing_file(path);
                       } else {
                               /* The instance foo does not support trace options */
                       }
    
                       ...
    
                       if (tracefs_instance_is_new(inst))
                               tracefs_instance_destroy(inst);
                       else
                               tracefs_instance_free(inst);
                       ...
    
                       long long int res;
                       if (tracefs_instance_file_read_number(NULL, "tracing_on", &res) == 0) {
                               if (res == 0) {
                                       /* tracing is disabled in the top instance */
                               } else if (res == 1) {
                                       /* tracing is enabled in the top instance */
                               } else {
                                       /* Unknown tracing state of the top instance */
                               }
                       } else {
                               /* Failed to read integer from tracing_on file */
                       }
    
                       ...
    
                       int fd;
                       fd = tracefs_instance_file_open(NULL, "tracing_on", O_WRONLY);
                       if (fd >= 0) {
                               /* Got file descriptor to the tracing_on file from the top instance for writing */
                               ...
                               close(fd);
                       }
    


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


* * *