summaryrefslogtreecommitdiffstats
path: root/Documentation/libtracefs-stream.txt
diff options
context:
space:
mode:
Diffstat (limited to '')
-rw-r--r--Documentation/libtracefs-stream.txt126
1 files changed, 126 insertions, 0 deletions
diff --git a/Documentation/libtracefs-stream.txt b/Documentation/libtracefs-stream.txt
new file mode 100644
index 0000000..8008be8
--- /dev/null
+++ b/Documentation/libtracefs-stream.txt
@@ -0,0 +1,126 @@
+libtracefs(3)
+=============
+
+NAME
+----
+tracefs_trace_pipe_stream, tracefs_trace_pipe_print, tracefs_trace_pipe_stop -
+redirect the stream of trace data to an output or stdout.
+
+SYNOPSIS
+--------
+[verse]
+--
+*#include <tracefs.h>*
+
+ssize_t *tracefs_trace_pipe_stream*(int _fd_, struct tracefs_instance pass:[*]_instance_, int _flags_);
+ssize_t *tracefs_trace_pipe_print*(struct tracefs_instance pass:[*]_instance_, int _flags_);
+void *tracefs_trace_pipe_stop*(struct tracefs_instance pass:[*]_instance_);
+
+
+--
+
+DESCRIPTION
+-----------
+If NULL is passed as _instance_, the top trace instance is used.
+
+The reading of the trace_pipe file can be stopped by calling *tracefs_trace_pipe_stop()*
+which could be placed in a signal handler in case the application wants to stop the
+reading, for example, with the user pressing Ctrl-C.
+
+The *tracefs_trace_pipe_stream()* function redirects the stream of trace data to an output
+file. The "splice" system call is used to moves the data without copying between kernel
+address space and user address space. The _fd_ is the file descriptor of the output file
+and _flags_ is a bit mask of flags to be passed to the open system call of the trace_pipe
+file (see ). If flags contain O_NONBLOCK, then that is also passed to the splice calls
+that may read the file to the output stream file descriptor.
+
+The *tracefs_trace_pipe_print()* function is similar to *tracefs_trace_pipe_stream()*, but
+the stream of trace data is redirected to stdout.
+
+
+RETURN VALUE
+------------
+The *tracefs_trace_pipe_stream()*, and *tracefs_trace_pipe_print()* functions return the
+number of bytes transfered if the operation is successful, or -1 in case of an error.
+
+EXAMPLE
+-------
+[source,c]
+--
+#include <stdio.h>
+#include <stdlib.h>
+#include <unistd.h>
+#include <signal.h>
+#include <fcntl.h>
+
+#include <tracefs.h>
+
+void stop(int sig)
+{
+ tracefs_trace_pipe_stop(NULL);
+}
+
+int main(int argc, char **argv)
+{
+ mode_t mode = S_IRUSR | S_IWUSR | S_IRGRP | S_IROTH;
+ const char *filename;
+ int fd;
+ int ret;
+
+ if (argc < 2) {
+ fprintf(stderr, "usage: %s output_file\n", argv[0]);
+ exit(-1);
+ }
+ filename = argv[1];
+ fd = creat(filename, mode);
+ if (fd < 0) {
+ perror(filename);
+ exit(-1);
+ }
+ signal(SIGINT, stop);
+ ret = tracefs_trace_pipe_stream(fd, NULL, SPLICE_F_NONBLOCK);
+ close(fd);
+
+ return ret;
+}
+--
+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),
+Documentation/trace/ftrace.rst from the Linux kernel tree
+
+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) 2021 VMware, Inc. Free use of this software is granted under
+the terms of the GNU Public License (GPL).