diff options
Diffstat (limited to 'Documentation/libtracefs-instances-files.txt')
| -rw-r--r-- | Documentation/libtracefs-instances-files.txt | 173 |
1 files changed, 173 insertions, 0 deletions
diff --git a/Documentation/libtracefs-instances-files.txt b/Documentation/libtracefs-instances-files.txt new file mode 100644 index 0000000..e298557 --- /dev/null +++ b/Documentation/libtracefs-instances-files.txt @@ -0,0 +1,173 @@ +libtracefs(3) +============= + +NAME +---- +tracefs_file_exists, tracefs_dir_exists, +tracefs_instance_get_file, tracefs_instance_get_dir - Work with files directories in tracing instances. + +SYNOPSIS +-------- +[verse] +-- +*#include <tracefs.h>* + +bool *tracefs_file_exists*(struct tracefs_instance pass:[*]_instance_, char pass:[*]_name_); +bool *tracefs_dir_exists*(struct tracefs_instance pass:[*]_instance_, char pass:[*]_name_); +char pass:[*]*tracefs_instance_get_file*(struct tracefs_instance pass:[*]_instance_, const char pass:[*]_file_); +char pass:[*]*tracefs_instance_get_dir*(struct tracefs_instance pass:[*]_instance_); + +-- + +DESCRIPTION +----------- +This set of APIs can be used to work with trace files in all trace instances. +Each of these APIs take an _instance_ argument, that can be NULL to act +on the top level instance. Otherwise, it acts on an instance created with +*tracefs_insance_create*(3) + +The *tracefs_file_exists()* function checks if a file with _name_ exists in _instance_. + +The *tracefs_dir_exists()* function checks if a directory with _name_ exists in _instance_. + +The *tracefs_instance_get_file()* function returns the full path of the file +with given _name_ in _instance_. Note, it does not check if the file exists in +the instance. + +The *tracefs_instance_get_dir()* function returns the full path of the directory +with given _name_ in _instance_. Note, it does not check if the directory exists +in the instance. + +RETURN VALUE +------------ +The *tracefs_file_exists()* and *tracefs_dir_exists()* functions return true if the +file / directory exist in the given instance or false if it does not exist. + +The *tracefs_instance_get_file()* and *tracefs_instance_get_dir()* functions return +a string or NULL in case of an error. The returned string must be freed with +*tracefs_put_tracing_file()*. + +EXAMPLE +------- +[source,c] +-- +#include <tracefs.h> + +struct tracefs_instance *inst = tracefs_instance_create("foo"); + if (!inst) { + /* Error creating a new trace instance */ + ... + } + + if (tracefs_file_exists(inst,"trace_clock")) { + /* The instance foo supports trace clock */ + char *path, *clock; + int size; + + path = = tracefs_instance_get_file(inst, "trace_clock") + if (!path) { + /* Error getting the path to trace_clock file in instance foo */ + ... + } + ... + tracefs_put_tracing_file(path); + + clock = tracefs_instance_file_read(inst, "trace_clock", &size); + if (!clock) { + /* Failed to read trace_clock file in instance foo */ + ... + } + ... + free(clock); + + if (tracefs_instance_file_write(inst, "trace_clock", "global") != strlen("global")) { + /* Failed to set gloabl trace clock in instance foo */ + ... + } + } else { + /* The instance foo does not support trace clock */ + } + + if (tracefs_dir_exists(inst,"options")) { + /* The instance foo supports trace options */ + char *path = tracefs_instance_get_file(inst, "options"); + if (!path) { + /* Error getting the path to options directory in instance foo */ + ... + } + + tracefs_put_tracing_file(path); + } else { + /* The instance foo does not support trace options */ + } + + ... + + if (tracefs_instance_is_new(inst)) + tracefs_instance_destroy(inst); + else + tracefs_instance_free(inst); + ... + + long long int res; + if (tracefs_instance_file_read_number(NULL, "tracing_on", &res) == 0) { + if (res == 0) { + /* tracing is disabled in the top instance */ + } else if (res == 1) { + /* tracing is enabled in the top instance */ + } else { + /* Unknown tracing state of the top instance */ + } + } else { + /* Failed to read integer from tracing_on file */ + } + + ... + + int fd; + fd = tracefs_instance_file_open(NULL, "tracing_on", O_WRONLY); + if (fd >= 0) { + /* Got file descriptor to the tracing_on file from the top instance for writing */ + ... + close(fd); + } +-- +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> +*Tzvetomir Stoyanov* <tz.stoyanov@gmail.com> +-- +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) 2020 VMware, Inc. Free use of this software is granted under +the terms of the GNU Public License (GPL). |