| libtracefs(3) |
| ============= |
| |
| NAME |
| ---- |
| tracefs_event_get_file, tracefs_event_file_read, tracefs_event_file_write, tracefs_event_file_append, |
| tracefs_event_file_clear, tracefs_event_file_exists - Work with trace event files. |
| |
| SYNOPSIS |
| -------- |
| [verse] |
| -- |
| *#include <tracefs.h>* |
| |
| char pass:[*]*tracefs_event_get_file*(struct tracefs_instance pass:[*]_instance_, const char pass:[*]_system_, const char pass:[*]_event_, |
| const char pass:[*]_file_); |
| char pass:[*]*tracefs_event_file_read*(struct tracefs_instance pass:[*]_instance_, const char pass:[*]_system_, const char pass:[*]_event_, |
| const char pass:[*]_file_, int pass:[*]_psize_); |
| int *tracefs_event_file_write*(struct tracefs_instance pass:[*]_instance_, const char pass:[*]_system_, const char pass:[*]_event_, |
| const char pass:[*]_file_, const char pass:[*]_str_); |
| int *tracefs_event_file_append*(struct tracefs_instance pass:[*]_instance_, const char pass:[*]_system_, const char pass:[*]_event_, |
| const char pass:[*]_file_, const char pass:[*]_str_); |
| int *tracefs_event_file_clear*(struct tracefs_instance pass:[*]_instance_, const char pass:[*]_system_, const char pass:[*]_event_, |
| const char pass:[*]_file_); |
| bool *tracefs_event_file_exists*(struct tracefs_instance pass:[*]_instance_, const char pass:[*]_system_, const char pass:[*]_event_, |
| const char pass:[*]_file_) |
| |
| -- |
| |
| DESCRIPTION |
| ----------- |
| These are functions for accessing tracefs event specific files. |
| These functions act similar to the tracefs instance file functions |
| but are easier to get to if the system and events are known before hand. |
| |
| The *tracefs_event_get_file()* returns the full path of the _file_ for |
| the given _system_ and _event_ that is within the given _instance_. |
| If _instance_ is NULL, then the file for the _event_ for the top level |
| instance is returned. Note, there is no check to see if the file actually |
| exists or even if the system and event exist. It only creates the path |
| name for such an event if it did exist. This acts similar to the |
| *tracefs_instance_get_file*(3), but is to be used to get to event files |
| if the _system_ and _event_ are already known. |
| |
| The *tracefs_event_file_read()* reads the content for the _event_ _file_ |
| for the given _instance_ or the top level instance if _instance_ is |
| NULL. The content of the file is returned and _psize_ is set to the amount |
| of data that was read. The returned content must be freed with *free*(3). |
| This acts similar to the *tracefs_instance_file_read*(3), but is |
| to be used to read the event file if the _system_ and _event_ are already |
| known. |
| |
| The *tracefs_event_file_write()* writes _str_ to the _event_ _file_. |
| It will truncate anything that is already in that file. |
| This acts similar to the *tracefs_instance_file_write*(3), but is |
| to be used to read the event file if the _system_ and _event_ are already |
| known. |
| |
| The *tracefs_event_file_append()* appends _str_ to the _event_ _file_. |
| It will not clear out the file as it writes _sting_. |
| This acts similar to the *tracefs_instance_file_append*(3), but is |
| to be used to read the event file if the _system_ and _event_ are already |
| known. |
| |
| The *tracefs_event_file_clear()* clears the content of the _event_ _file_. |
| This acts similar to the *tracefs_instance_file_clear*(3), but is |
| to be used to read the event file if the _system_ and _event_ are already |
| known. |
| |
| The *tracefs_event_file_exists()* returns true if the _event_ _file_ |
| exists, and false otherwise. This acts similar to the *tracefs_instance_file_exists*(3), |
| but is to be used to read the event file if the _system_ and _event_ are already |
| known. |
| |
| RETURN VALUE |
| ------------ |
| *tracefs_event_get_file()* returns the path of the given _system_/_event_ _file_ on |
| success and NULL on error. The return value must be freed with *tracefs_put_tracing_file*(3). |
| |
| *tracefs_event_file_read()* reads the content of the _system_/_event_ _file_ or |
| NULL on error. The return pointer must be freed with *free*(3). |
| |
| *tracefs_event_file_write()* and *tracefs_event_file_append()* returns the number of |
| bytes written to the _system_/_event_ _file_ or negative on error. |
| |
| *tracefs_event_file_clear()* returns zero on success and -1 on error. |
| |
| *tracefs_event_file_exists()* returns true if the _system_/_event_ _file_ exists for |
| the given _instance_ (or top level if _instance_ is NULL) or false otherwise. |
| |
| EXAMPLE |
| ------- |
| [source,c] |
| -- |
| #include <stdio.h> |
| #include <stdlib.h> |
| #include <unistd.h> |
| #include <tracefs.h> |
| |
| int main(int argc, char **argv) |
| { |
| char *system; |
| char *event; |
| char *file; |
| char *cmd = NULL; |
| char *buf; |
| char *str; |
| char ch = 'r'; |
| int size; |
| |
| if (argc < 4) { |
| printf("usage: %s sytem event file [(-a|-w) write | -c]\n" |
| " reads the system/event file or writes if [write is supplied]\n", |
| argv[0]); |
| exit(0); |
| } |
| |
| system = argv[1]; |
| event = argv[2]; |
| file = argv[3]; |
| if (argc > 4) |
| cmd = argv[4]; |
| |
| if (!tracefs_event_file_exists(NULL, system, event, file)) { |
| fprintf(stderr, "File %s/%s/%s does not exist\n", |
| system, event, file); |
| exit(-1); |
| } |
| |
| if (cmd) { |
| if (cmd[0] != '-') |
| ch = cmd[0]; |
| else |
| ch = cmd[1]; |
| if (!ch) |
| ch = 'c'; |
| } |
| |
| switch (ch) { |
| case 'r': |
| buf = tracefs_event_file_read(NULL, system, event, file, &size); |
| if (buf) |
| printf("%s", buf); |
| else |
| fprintf(stderr, "Failed to read %s/%s/%s\n", |
| system, event, file); |
| free(buf); |
| break; |
| case 'w': |
| case 'a': |
| if (argc < 6) { |
| fprintf(stderr, "%s command requires something to write\n", |
| ch == 'w' ? "write" : "append"); |
| exit(-1); |
| } |
| if (ch == 'w') |
| size = tracefs_event_file_write(NULL, system, event, file, argv[5]); |
| else |
| size = tracefs_event_file_append(NULL, system, event, file, argv[5]); |
| if (size < 0) { |
| fprintf(stderr, "Failed to write '%s' to %s/%s/%s\n", |
| argv[5], system, event, file); |
| exit(-1); |
| } |
| break; |
| case 'c': |
| if (tracefs_event_file_clear(NULL, system, event, file) < 0) { |
| fprintf(stderr, "Failed to clear %s/%s/%s\n", |
| system, event, file); |
| exit(-1); |
| } |
| break; |
| default: |
| fprintf(stderr, "Unknown command '%c'\n", ch); |
| exit(-1); |
| } |
| exit(0); |
| } |
| -- |
| FILES |
| ----- |
| [verse] |
| -- |
| *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. |
| -- |
| |
| SEE ALSO |
| -------- |
| *libtracefs*(3), |
| *libtraceevent*(3), |
| *trace-cmd*(1) |
| |
| AUTHOR |
| ------ |
| [verse] |
| -- |
| *Steven Rostedt* <rostedt@goodmis.org> |
| -- |
| REPORTING BUGS |
| -------------- |
| Report bugs to <linux-trace-devel@vger.kernel.org> |
| |
| 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) 2022 Google, Inc. Free use of this software is granted under |
| the terms of the GNU Public License (GPL). |