1libtracefs(3) 2============= 3 4NAME 5---- 6 7tracefs_instance_file_open, 8tracefs_instance_file_write, tracefs_instance_file_write_number, tracefs_instance_file_append, tracefs_instance_file_clear, 9tracefs_instance_file_read, tracefs_instance_file_read_number - Work with files in tracing instances. 10 11SYNOPSIS 12-------- 13[verse] 14-- 15*#include <tracefs.h>* 16 17int *tracefs_instance_file_open*(struct tracefs_instance pass:[*]_instance_, const char pass:[*]_file_, int _mode_); 18int *tracefs_instance_file_write*(struct tracefs_instance pass:[*]_instance_, const char pass:[*]_file_, const char pass:[*]_str_); 19int *tracefs_instance_file_write_number*(struct tracefs_instance pass:[*]_instance_, const char pass:[*]_file_, size_t _val_); 20int *tracefs_instance_file_append*(struct tracefs_instance pass:[*]_instance_, const char pass:[*]_file_, const char pass:[*]_str_); 21int *tracefs_instance_file_clear*(struct tracefs_instance pass:[*]_instance_, const char pass:[*]_file_); 22char pass:[*]*tracefs_instance_file_read*(struct tracefs_instance pass:[*]_instance_, const char pass:[*]_file_, int pass:[*]_psize_); 23int *tracefs_instance_file_read_number*(struct tracefs_instance pass:[*]_instance_, const char pass:[*]_file_, long long int pass:[*]_res_); 24 25-- 26 27DESCRIPTION 28----------- 29This set of APIs can be used to work with trace files in all trace instances. 30Each of these APIs take an _instance_ argument, that can be NULL to act 31on the top level instance. Otherwise, it acts on an instance created with 32*tracefs_insance_create*(3) 33 34The *tracefs_instance_file_open()* function opens trace _file_ from given _instance_ and returns 35a file descriptor to it. The file access _mode_ can be specified, see *open*(3) for more details. 36If -1 is passed as _mode_, default O_RDWR is used. 37 38The *tracefs_instance_file_write()* function writes a string _str_ in a _file_ from 39the given _instance_, without the terminating NULL character. When opening the file, this function 40tries to truncates the size of the file to zero, which clears all previously existing settings. 41 42The *tracefs_instance_file_write_number()* function converts _val_ into a string 43and then writes it to the given file. This is a helper function that does the number 44conversion to string and then calls *tracefs_instance_file_write()*. 45 46The *tracefs_instance_file_append()* function writes a string _str_ in a _file_ from 47the given _instance_, without the terminating NULL character. This function is similar to 48*tracefs_instance_file_write()*, but the existing content of the is not cleared. Thus the 49new settings are appended to the existing ones (if any). 50 51The *tracefs_instance_file_clear()* function tries to truncates the size of the file to zero, 52which clears all previously existing settings. If the file has content that does not get 53cleared in this way, this will not have any effect. 54 55The *tracefs_instance_file_read()* function reads the content of a _file_ from 56the given _instance_. 57 58The *tracefs_instance_file_read_number()* function reads the content of a _file_ from 59the given _instance_ and converts it to a long long integer, which is stored in _res_. 60 61RETURN VALUE 62------------ 63The *tracefs_instance_file_open()* function returns a file descriptor to the opened file. It must be 64closed with *close*(3). In case of an error, -1 is returned. 65 66The *tracefs_instance_file_write()* function returns the number of written bytes, 67or -1 in case of an error. 68 69The *tracefs_instance_file_write_number()* function returns 0 on success and -1 on error. 70 71The *tracefs_instance_file_append()* function returns the number of written bytes, 72or -1 in case of an error. 73 74The *tracefs_instance_file_clear()* function returns 0 on success, or -1 in case of an error. 75 76The *tracefs_instance_file_read()* function returns a pointer to a NULL terminated 77string, read from the file, or NULL in case of an error. The returned string must 78be freed with free(). 79 80The *tracefs_instance_file_read_number()* function returns 0 if a valid integer is read from 81the file and stored in _res_ or -1 in case of an error. 82 83EXAMPLE 84------- 85[source,c] 86-- 87#include <tracefs.h> 88 89struct tracefs_instance *inst = tracefs_instance_create("foo"); 90 if (!inst) { 91 /* Error creating a new trace instance */ 92 ... 93 } 94 95 if (tracefs_file_exists(inst,"trace_clock")) { 96 /* The instance foo supports trace clock */ 97 char *path, *clock; 98 int size; 99 100 path = = tracefs_instance_get_file(inst, "trace_clock") 101 if (!path) { 102 /* Error getting the path to trace_clock file in instance foo */ 103 ... 104 } 105 ... 106 tracefs_put_tracing_file(path); 107 108 clock = tracefs_instance_file_read(inst, "trace_clock", &size); 109 if (!clock) { 110 /* Failed to read trace_clock file in instance foo */ 111 ... 112 } 113 ... 114 free(clock); 115 116 if (tracefs_instance_file_write(inst, "trace_clock", "global") != strlen("global")) { 117 /* Failed to set gloabl trace clock in instance foo */ 118 ... 119 } 120 } else { 121 /* The instance foo does not support trace clock */ 122 } 123 124 if (tracefs_dir_exists(inst,"options")) { 125 /* The instance foo supports trace options */ 126 char *path = tracefs_instance_get_file(inst, "options"); 127 if (!path) { 128 /* Error getting the path to options directory in instance foo */ 129 ... 130 } 131 132 tracefs_put_tracing_file(path); 133 } else { 134 /* The instance foo does not support trace options */ 135 } 136 137 ... 138 139 if (tracefs_instance_is_new(inst)) 140 tracefs_instance_destroy(inst); 141 else 142 tracefs_instance_free(inst); 143 ... 144 145 long long int res; 146 if (tracefs_instance_file_read_number(NULL, "tracing_on", &res) == 0) { 147 if (res == 0) { 148 /* tracing is disabled in the top instance */ 149 } else if (res == 1) { 150 /* tracing is enabled in the top instance */ 151 } else { 152 /* Unknown tracing state of the top instance */ 153 } 154 } else { 155 /* Failed to read integer from tracing_on file */ 156 } 157 158 ... 159 160 int fd; 161 fd = tracefs_instance_file_open(NULL, "tracing_on", O_WRONLY); 162 if (fd >= 0) { 163 /* Got file descriptor to the tracing_on file from the top instance for writing */ 164 ... 165 close(fd); 166 } 167-- 168FILES 169----- 170[verse] 171-- 172*tracefs.h* 173 Header file to include in order to have access to the library APIs. 174*-ltracefs* 175 Linker switch to add when building a program that uses the library. 176-- 177 178SEE ALSO 179-------- 180*libtracefs*(3), 181*libtraceevent*(3), 182*trace-cmd*(1) 183 184AUTHOR 185------ 186[verse] 187-- 188*Steven Rostedt* <rostedt@goodmis.org> 189*Tzvetomir Stoyanov* <tz.stoyanov@gmail.com> 190-- 191REPORTING BUGS 192-------------- 193Report bugs to <linux-trace-devel@vger.kernel.org> 194 195LICENSE 196------- 197libtracefs is Free Software licensed under the GNU LGPL 2.1 198 199RESOURCES 200--------- 201https://git.kernel.org/pub/scm/libs/libtrace/libtracefs.git/ 202 203COPYING 204------- 205Copyright \(C) 2020 VMware, Inc. Free use of this software is granted under 206the terms of the GNU Public License (GPL). 207