200 lines
6.1 KiB
Plaintext
200 lines
6.1 KiB
Plaintext
libtracefs(3)
|
|
=============
|
|
|
|
NAME
|
|
----
|
|
|
|
tracefs_instance_file_open,
|
|
tracefs_instance_file_write, tracefs_instance_file_append, tracefs_instance_file_clear,
|
|
tracefs_instance_file_read, tracefs_instance_file_read_number - Work with files in tracing instances.
|
|
|
|
SYNOPSIS
|
|
--------
|
|
[verse]
|
|
--
|
|
*#include <tracefs.h>*
|
|
|
|
int *tracefs_instance_file_open*(struct tracefs_instance pass:[*]_instance_, const char pass:[*]_file_, int _mode_);
|
|
int *tracefs_instance_file_write*(struct tracefs_instance pass:[*]_instance_, const char pass:[*]_file_, const char pass:[*]_str_);
|
|
int *tracefs_instance_file_append*(struct tracefs_instance pass:[*]_instance_, const char pass:[*]_file_, const char pass:[*]_str_);
|
|
int *tracefs_instance_file_clear*(struct tracefs_instance pass:[*]_instance_, const char pass:[*]_file_);
|
|
char pass:[*]*tracefs_instance_file_read*(struct tracefs_instance pass:[*]_instance_, const char pass:[*]_file_, int pass:[*]_psize_);
|
|
int *tracefs_instance_file_read_number*(struct tracefs_instance pass:[*]_instance_, const char pass:[*]_file_, long long int pass:[*]_res_);
|
|
|
|
--
|
|
|
|
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_instance_file_open()* function opens trace _file_ from given _instance_ and returns
|
|
a file descriptor to it. The file access _mode_ can be specified, see *open*(3) for more details.
|
|
If -1 is passed as _mode_, default O_RDWR is used.
|
|
|
|
The *tracefs_instance_file_write()* function writes a string _str_ in a _file_ from
|
|
the given _instance_, without the terminating NULL character. When opening the file, this function
|
|
tries to truncates the size of the file to zero, which clears all previously existing settings.
|
|
|
|
The *tracefs_instance_file_append()* function writes a string _str_ in a _file_ from
|
|
the given _instance_, without the terminating NULL character. This function is similar to
|
|
*tracefs_instance_file_write()*, but the existing content of the is not cleared. Thus the
|
|
new settings are appended to the existing ones (if any).
|
|
|
|
The *tracefs_instance_file_clear()* function tries to truncates the size of the file to zero,
|
|
which clears all previously existing settings. If the file has content that does not get
|
|
cleared in this way, this will not have any effect.
|
|
|
|
The *tracefs_instance_file_read()* function reads the content of a _file_ from
|
|
the given _instance_.
|
|
|
|
The *tracefs_instance_file_read_number()* function reads the content of a _file_ from
|
|
the given _instance_ and converts it to a long long integer, which is stored in _res_.
|
|
|
|
RETURN VALUE
|
|
------------
|
|
The *tracefs_instance_file_open()* function returns a file descriptor to the opened file. It must be
|
|
closed with *close*(3). In case of an error, -1 is returned.
|
|
|
|
The *tracefs_instance_file_write()* function returns the number of written bytes,
|
|
or -1 in case of an error.
|
|
|
|
The *tracefs_instance_file_append()* function returns the number of written bytes,
|
|
or -1 in case of an error.
|
|
|
|
The *tracefs_instance_file_clear()* function returns 0 on success, or -1 in case of an error.
|
|
|
|
The *tracefs_instance_file_read()* function returns a pointer to a NULL terminated
|
|
string, read from the file, or NULL in case of an error. The returned string must
|
|
be freed with free().
|
|
|
|
The *tracefs_instance_file_read_number()* function returns 0 if a valid integer is read from
|
|
the file and stored in _res_ or -1 in case of an error.
|
|
|
|
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).
|