Provided by: libtracefs-doc_1.8.0-1ubuntu1_all 
NAME
tracefs_instance_file_open, tracefs_instance_file_write,
tracefs_instance_file_write_number, tracefs_instance_file_append,
tracefs_instance_file_clear, tracefs_instance_file_read, tracefs_instance_file_read_number
- Work with files in tracing instances.
SYNOPSIS
#include <tracefs.h>
int tracefs_instance_file_open(struct tracefs_instance *instance, const char *file, int mode);
int tracefs_instance_file_write(struct tracefs_instance *instance, const char *file, const char *str);
int tracefs_instance_file_write_number(struct tracefs_instance *instance, const char *file, size_t val);
int tracefs_instance_file_append(struct tracefs_instance *instance, const char *file, const char *str);
int tracefs_instance_file_clear(struct tracefs_instance *instance, const char *file);
char *tracefs_instance_file_read(struct tracefs_instance *instance, const char *file, int *psize);
int tracefs_instance_file_read_number(struct tracefs_instance *instance, const char *file, long long int *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_write_number() function converts val into a string and then
writes it to the given file. This is a helper function that does the number conversion to
string and then calls tracefs_instance_file_write().
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_write_number() function returns 0 on success and -1 on 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
#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
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
Steven Rostedt <rostedt@goodmis.org[1]>
Tzvetomir Stoyanov <tz.stoyanov@gmail.com[2]>
REPORTING BUGS
Report bugs to <linux-trace-devel@vger.kernel.org[3]>
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).
NOTES
1. rostedt@goodmis.org
mailto:rostedt@goodmis.org
2. tz.stoyanov@gmail.com
mailto:tz.stoyanov@gmail.com
3. linux-trace-devel@vger.kernel.org
mailto:linux-trace-devel@vger.kernel.org