SYNOPSIS
#include <tracefs.h>
struct tracefs_cpu *tracefs_cpu_open(struct tracefs_instance *instance,
int cpu, bool nonblock);
void tracefs_cpu_close(struct tracefs_cpu *tcpu);
struct tracefs_cpu *tracefs_cpu_alloc_fd(int fd, int subbuf_size, bool nonblock);
void tracefs_cpu_free_fd(struct tracefs_cpu *tcpu);
struct tracefs_cpu *tracefs_cpu_snapshot_open(struct tracefs_instance *instance,
int cpu, bool nonblock);
DESCRIPTION
This set of APIs can be used to open the raw data from the trace_pipe_raw files in the tracefs file system in oder to read them with the tracefs_cpu_read(3) functions.
The tracefs_cpu_open() creates a descriptor that can read the tracefs trace_pipe_raw file for a given cpu in a given instance. If instance is NULL than the toplevel trace_pipe_raw file is used.
The tracefs_cpu_close() closes all the file descriptors associated to the trace_pipe_raw opened by tracefs_cpu_open().
The tracefs_cpu_alloc_fd() will create a tracefs_cpu descriptor from an existing file descriptor fd. This is useful to use when connecting to a socket or pipe where the other end is feeding raw tracing data in the same format as the trace_pipe_raw file would (like in guest to host tracing). The caller is responsible for determining the subbuf_size that will be used to break up the sub-buffers being read by the file descriptor. The nonblock is treated the same as the same parameter in tracefs_cpu_open().
The tracefs_cpu_free_fd() is used to free the descriptor returned by tracefs_cpu_alloc_fd(). It does all the clean up that tracefs_cpu_close() performs, and that could also be used to free up the descriptor created by tracefs_cpu_alloc_fd() but will also close the file descriptor passed in. Note that tracefs_cpu_free_fd() should not be used on the descriptor returned by tracefs_cpu_open() as it will not close the file descriptor created by it.
The tracefs_cpu_snapshot_open() is similar to tracefs_cpu_open() except that it opens the snapshot buffer (see tracefs_snapshot_snap(3)). The snapshot buffer does not have a writer to it, it is only created by a snapshot action that swaps the current ring buffer with the snapshot buffer. The nonblock, when false, acts a little differently here too. Reads are not affected by the "buffer_percent" file. If the snapshot buffer is empty, it will block until a new snapshot happens.
RETURN VALUE
The tracefs_cpu_open() and *tracefs_cpu_snapshot_open() both return a struct tracefs_cpu descriptor that can be used by the other functions or NULL on error.
The tracefs_cpu_alloc_fd() returns a struct tracefs_cpu descriptor that can be used by the tracefs_cpu_read(3) related functions, where the descriptor will be reading the passed in fd file descriptor.
EXAMPLE
See tracefs_cpu_read(3) for an example.
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>
REPORTING BUGS
Report bugs to <linux-trace-devel@vger.kernel.org>
LICENSE
libtracefs is Free Software licensed under the GNU LGPL 2.1
COPYING
Copyright (C) 2022 Google, Inc. Free use of this software is granted under the terms of the GNU Public License (GPL).