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