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