1libtracefs(3) 2============= 3 4NAME 5---- 6tracefs_event_get_file, tracefs_event_file_read, tracefs_event_file_write, tracefs_event_file_append, 7tracefs_event_file_clear, tracefs_event_file_exists - Work with trace event files. 8 9SYNOPSIS 10-------- 11[verse] 12-- 13*#include <tracefs.h>* 14 15char pass:[*]*tracefs_event_get_file*(struct tracefs_instance pass:[*]_instance_, const char pass:[*]_system_, const char pass:[*]_event_, 16 const char pass:[*]_file_); 17char pass:[*]*tracefs_event_file_read*(struct tracefs_instance pass:[*]_instance_, const char pass:[*]_system_, const char pass:[*]_event_, 18 const char pass:[*]_file_, int pass:[*]_psize_); 19int *tracefs_event_file_write*(struct tracefs_instance pass:[*]_instance_, const char pass:[*]_system_, const char pass:[*]_event_, 20 const char pass:[*]_file_, const char pass:[*]_str_); 21int *tracefs_event_file_append*(struct tracefs_instance pass:[*]_instance_, const char pass:[*]_system_, const char pass:[*]_event_, 22 const char pass:[*]_file_, const char pass:[*]_str_); 23int *tracefs_event_file_clear*(struct tracefs_instance pass:[*]_instance_, const char pass:[*]_system_, const char pass:[*]_event_, 24 const char pass:[*]_file_); 25bool *tracefs_event_file_exists*(struct tracefs_instance pass:[*]_instance_, const char pass:[*]_system_, const char pass:[*]_event_, 26 const char pass:[*]_file_); 27-- 28 29DESCRIPTION 30----------- 31These are functions for accessing tracefs event specific files. 32These functions act similar to the tracefs instance file functions 33but are easier to get to if the system and events are known before hand. 34 35The *tracefs_event_get_file()* returns the full path of the _file_ for 36the given _system_ and _event_ that is within the given _instance_. 37If _instance_ is NULL, then the file for the _event_ for the top level 38instance is returned. Note, there is no check to see if the file actually 39exists or even if the system and event exist. It only creates the path 40name for such an event if it did exist. This acts similar to the 41*tracefs_instance_get_file*(3), but is to be used to get to event files 42if the _system_ and _event_ are already known. 43 44The *tracefs_event_file_read()* reads the content for the _event_ _file_ 45for the given _instance_ or the top level instance if _instance_ is 46NULL. The content of the file is returned and _psize_ is set to the amount 47of data that was read. The returned content must be freed with *free*(3). 48This acts similar to the *tracefs_instance_file_read*(3), but is 49to be used to read the event file if the _system_ and _event_ are already 50known. 51 52The *tracefs_event_file_write()* writes _str_ to the _event_ _file_. 53It will truncate anything that is already in that file. 54This acts similar to the *tracefs_instance_file_write*(3), but is 55to be used to read the event file if the _system_ and _event_ are already 56known. 57 58The *tracefs_event_file_append()* appends _str_ to the _event_ _file_. 59It will not clear out the file as it writes _sting_. 60This acts similar to the *tracefs_instance_file_append*(3), but is 61to be used to read the event file if the _system_ and _event_ are already 62known. 63 64The *tracefs_event_file_clear()* clears the content of the _event_ _file_. 65This acts similar to the *tracefs_instance_file_clear*(3), but is 66to be used to read the event file if the _system_ and _event_ are already 67known. 68 69The *tracefs_event_file_exists()* returns true if the _event_ _file_ 70exists, and false otherwise. This acts similar to the *tracefs_instance_file_exists*(3), 71but is to be used to read the event file if the _system_ and _event_ are already 72known. 73 74RETURN VALUE 75------------ 76*tracefs_event_get_file()* returns the path of the given _system_/_event_ _file_ on 77success and NULL on error. The return value must be freed with *tracefs_put_tracing_file*(3). 78 79*tracefs_event_file_read()* reads the content of the _system_/_event_ _file_ or 80NULL on error. The return pointer must be freed with *free*(3). 81 82*tracefs_event_file_write()* and *tracefs_event_file_append()* returns the number of 83bytes written to the _system_/_event_ _file_ or negative on error. 84 85*tracefs_event_file_clear()* returns zero on success and -1 on error. 86 87*tracefs_event_file_exists()* returns true if the _system_/_event_ _file_ exists for 88the given _instance_ (or top level if _instance_ is NULL) or false otherwise. 89 90EXAMPLE 91------- 92[source,c] 93-- 94#include <stdio.h> 95#include <stdlib.h> 96#include <unistd.h> 97#include <tracefs.h> 98 99int main(int argc, char **argv) 100{ 101 char *system; 102 char *event; 103 char *file; 104 char *cmd = NULL; 105 char *buf; 106 char *str; 107 char ch = 'r'; 108 int size; 109 110 if (argc < 4) { 111 printf("usage: %s sytem event file [(-a|-w) write | -c]\n" 112 " reads the system/event file or writes if [write is supplied]\n", 113 argv[0]); 114 exit(0); 115 } 116 117 system = argv[1]; 118 event = argv[2]; 119 file = argv[3]; 120 if (argc > 4) 121 cmd = argv[4]; 122 123 if (!tracefs_event_file_exists(NULL, system, event, file)) { 124 fprintf(stderr, "File %s/%s/%s does not exist\n", 125 system, event, file); 126 exit(-1); 127 } 128 129 if (cmd) { 130 if (cmd[0] != '-') 131 ch = cmd[0]; 132 else 133 ch = cmd[1]; 134 if (!ch) 135 ch = 'c'; 136 } 137 138 switch (ch) { 139 case 'r': 140 buf = tracefs_event_file_read(NULL, system, event, file, &size); 141 if (buf) 142 printf("%s", buf); 143 else 144 fprintf(stderr, "Failed to read %s/%s/%s\n", 145 system, event, file); 146 free(buf); 147 break; 148 case 'w': 149 case 'a': 150 if (argc < 6) { 151 fprintf(stderr, "%s command requires something to write\n", 152 ch == 'w' ? "write" : "append"); 153 exit(-1); 154 } 155 if (ch == 'w') 156 size = tracefs_event_file_write(NULL, system, event, file, argv[5]); 157 else 158 size = tracefs_event_file_append(NULL, system, event, file, argv[5]); 159 if (size < 0) { 160 fprintf(stderr, "Failed to write '%s' to %s/%s/%s\n", 161 argv[5], system, event, file); 162 exit(-1); 163 } 164 break; 165 case 'c': 166 if (tracefs_event_file_clear(NULL, system, event, file) < 0) { 167 fprintf(stderr, "Failed to clear %s/%s/%s\n", 168 system, event, file); 169 exit(-1); 170 } 171 break; 172 default: 173 fprintf(stderr, "Unknown command '%c'\n", ch); 174 exit(-1); 175 } 176 exit(0); 177} 178-- 179FILES 180----- 181[verse] 182-- 183*tracefs.h* 184 Header file to include in order to have access to the library APIs. 185*-ltracefs* 186 Linker switch to add when building a program that uses the library. 187-- 188 189SEE ALSO 190-------- 191*libtracefs*(3), 192*libtraceevent*(3), 193*trace-cmd*(1) 194 195AUTHOR 196------ 197[verse] 198-- 199*Steven Rostedt* <rostedt@goodmis.org> 200-- 201REPORTING BUGS 202-------------- 203Report bugs to <linux-trace-devel@vger.kernel.org> 204 205LICENSE 206------- 207libtracefs is Free Software licensed under the GNU LGPL 2.1 208 209RESOURCES 210--------- 211https://git.kernel.org/pub/scm/libs/libtrace/libtracefs.git/ 212 213COPYING 214------- 215Copyright \(C) 2022 Google, Inc. Free use of this software is granted under 216the terms of the GNU Public License (GPL). 217