1libtracefs(3) 2============= 3 4NAME 5---- 6tracefs_trace_pipe_stream, tracefs_trace_pipe_print, tracefs_trace_pipe_stop - 7redirect the stream of trace data to an output or stdout. 8 9SYNOPSIS 10-------- 11[verse] 12-- 13*#include <tracefs.h>* 14 15ssize_t *tracefs_trace_pipe_stream*(int _fd_, struct tracefs_instance pass:[*]_instance_, int _flags_); 16ssize_t *tracefs_trace_pipe_print*(struct tracefs_instance pass:[*]_instance_, int _flags_); 17void *tracefs_trace_pipe_stop*(struct tracefs_instance pass:[*]_instance_); 18 19 20-- 21 22DESCRIPTION 23----------- 24If NULL is passed as _instance_, the top trace instance is used. 25 26The reading of the trace_pipe file can be stopped by calling *tracefs_trace_pipe_stop()* 27which could be placed in a signal handler in case the application wants to stop the 28reading, for example, with the user pressing Ctrl-C. 29 30The *tracefs_trace_pipe_stream()* function redirects the stream of trace data to an output 31file. The "splice" system call is used to moves the data without copying between kernel 32address space and user address space. The _fd_ is the file descriptor of the output file 33and _flags_ is a bit mask of flags to be passed to the open system call of the trace_pipe 34file (see *open(2)*). If flags contain O_NONBLOCK, then that is also passed to the splice calls 35that may read the file to the output stream file descriptor. Note, O_RDONLY is or'd to 36the _flags_ and only O_NONBLOCK is useful for this parameter. 37 38The *tracefs_trace_pipe_print()* function is similar to *tracefs_trace_pipe_stream()*, but 39the stream of trace data is redirected to stdout. 40 41 42RETURN VALUE 43------------ 44The *tracefs_trace_pipe_stream()*, and *tracefs_trace_pipe_print()* functions return the 45number of bytes transfered if the operation is successful, or -1 in case of an error. 46 47EXAMPLE 48------- 49[source,c] 50-- 51#include <stdio.h> 52#include <stdlib.h> 53#include <unistd.h> 54#include <signal.h> 55#include <fcntl.h> 56 57#include <tracefs.h> 58 59void stop(int sig) 60{ 61 tracefs_trace_pipe_stop(NULL); 62} 63 64int main(int argc, char **argv) 65{ 66 mode_t mode = S_IRUSR | S_IWUSR | S_IRGRP | S_IROTH; 67 const char *filename; 68 int fd; 69 int ret; 70 71 if (argc < 2) { 72 fprintf(stderr, "usage: %s output_file\n", argv[0]); 73 exit(-1); 74 } 75 filename = argv[1]; 76 fd = creat(filename, mode); 77 if (fd < 0) { 78 perror(filename); 79 exit(-1); 80 } 81 signal(SIGINT, stop); 82 ret = tracefs_trace_pipe_stream(fd, NULL, SPLICE_F_NONBLOCK); 83 close(fd); 84 85 return ret; 86} 87-- 88FILES 89----- 90[verse] 91-- 92*tracefs.h* 93 Header file to include in order to have access to the library APIs. 94*-ltracefs* 95 Linker switch to add when building a program that uses the library. 96-- 97 98SEE ALSO 99-------- 100*libtracefs*(3), 101*libtraceevent*(3), 102*trace-cmd*(1), 103Documentation/trace/ftrace.rst from the Linux kernel tree 104 105AUTHOR 106------ 107[verse] 108-- 109*Steven Rostedt* <rostedt@goodmis.org> 110*Tzvetomir Stoyanov* <tz.stoyanov@gmail.com> 111-- 112REPORTING BUGS 113-------------- 114Report bugs to <linux-trace-devel@vger.kernel.org> 115 116LICENSE 117------- 118libtracefs is Free Software licensed under the GNU LGPL 2.1 119 120RESOURCES 121--------- 122https://git.kernel.org/pub/scm/libs/libtrace/libtracefs.git/ 123 124COPYING 125------- 126Copyright \(C) 2021 VMware, Inc. Free use of this software is granted under 127the terms of the GNU Public License (GPL). 128