'\" t .\" Title: libtracefs .\" Author: [see the "AUTHOR" section] .\" Generator: DocBook XSL Stylesheets vsnapshot .\" Date: 10/08/2022 .\" Manual: libtracefs Manual .\" Source: libtracefs 1.5.0 .\" Language: English .\" .TH "LIBTRACEFS" "3" "10/08/2022" "libtracefs 1\&.5\&.0" "libtracefs Manual" .\" ----------------------------------------------------------------- .\" * Define some portability stuff .\" ----------------------------------------------------------------- .\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .\" http://bugs.debian.org/507673 .\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html .\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .ie \n(.g .ds Aq \(aq .el .ds Aq ' .\" ----------------------------------------------------------------- .\" * set default formatting .\" ----------------------------------------------------------------- .\" disable hyphenation .nh .\" disable justification (adjust text to left margin only) .ad l .\" ----------------------------------------------------------------- .\" * MAIN CONTENT STARTS HERE * .\" ----------------------------------------------------------------- .SH "NAME" tracefs_trace_is_on, tracefs_trace_on, tracefs_trace_off, tracefs_trace_on_get_fd, tracefs_trace_on_fd, tracefs_trace_off_fd \- Functions to enable or disable tracing\&. .SH "SYNOPSIS" .sp .nf \fB#include \fR int \fBtracefs_trace_is_on\fR(struct tracefs_instance *\fIinstance\fR); int \fBtracefs_trace_on\fR(struct tracefs_instance *\fIinstance\fR); int \fBtracefs_trace_off\fR(struct tracefs_instance *\fIinstance\fR); int \fBtracefs_trace_on_get_fd\fR(struct tracefs_instance *\fIinstance\fR); int \fBtracefs_trace_on_fd\fR(int \fIfd\fR); int \fBtracefs_trace_off_fd\fR(int \fIfd\fR); .fi .SH "DESCRIPTION" .sp This set of functions can be used to check, enable or disable writing to the ring buffer in the given trace instance\&. The tracing is enabled when writing to the ring buffer is enabled\&. .sp The \fBtracefs_trace_is_on()\fR function checks if tracing is enabled for the given \fIinstance\fR\&. If \fIinstance\fR is NULL, the top instance is used\&. .sp The \fBtracefs_trace_on()\fR and \fBtracefs_trace_off()\fR functions set the tracing in the \fIinstance\fR to enable or disable state\&. If \fIinstance\fR is NULL, the top instance is used\&. .sp The \fBtracefs_trace_on_get_fd()\fR function returns a file descriptor to the "tracing_on" file from the given \fIinstance\fR\&. If \fIinstance\fR is NULL, the top trace instance is used\&. The returned descriptor can be used for fast enabling or disabling the tracing of the instance\&. .sp The \fBtracefs_trace_on_fd()\fR and \fBtracefs_trace_off_fd()\fR functions set the tracing state to enable or disable using the given \fIfd\fR\&. This file descriptor must be opened for writing with \fBtracefs_trace_on_get_fd\fR(3) of the desired trace instance\&. These functions are faster than \fBtracefs_trace_on\fR and \fBtracefs_trace_off\fR\&. .SH "RETURN VALUE" .sp The \fBtracefs_trace_is_on()\fR function returns 0 if tracing is disable, 1 if it is enabled or \-1 in case of an error\&. .sp The \fBtracefs_trace_on_get_fd()\fR function returns a file descriptor to "tracing_on" file for reading and writing, which must be closed wuth close()\&. In case of an error \-1 is returned\&. .sp The \fBtracefs_trace_on()\fR, \fBtracefs_trace_off()\fR, \fBtracefs_trace_on_fd()\fR and \fBtracefs_trace_off_fd()\fR functions return \-1 in case of an error or 0 otherwise\&. .SH "EXAMPLE" .sp .if n \{\ .RS 4 .\} .nf #include int ret; ret = tracefs_trace_is_on(NULL); if (ret == 0) { /* Tracing is disabled in the top instance */ } else if (ret == 1) { /* Tracing is enabled in the top instance */ } else { /* Error getting tracing state of the top instance */ } \&.\&.\&. if (!tracefs_trace_on(NULL)) { /* Enabled tracing in the top instance */ \&.\&.\&. if (!tracefs_trace_off(NULL)) { /* Disabled tracing in the top instance */ } else { /* Error disabling tracing in the top instance */ } } else { /* Error enabling tracing in the top instance */ } \&.\&.\&. int fd = tracefs_trace_on_get_fd(NULL); if (fd < 0) { /* Error opening tracing_on file */ } \&.\&.\&. if (!tracefs_trace_on_fd(fd)) { /* Enabled tracing in the top instance */ \&.\&.\&. if (!tracefs_trace_off_fd(fd)) { /* Disabled tracing in the top instance */ } else { /* Error disabling tracing in the top instance */ } } else { /* Error enabling tracing in the top instance */ } \&.\&.\&. close(fd); .fi .if n \{\ .RE .\} .SH "FILES" .sp .if n \{\ .RS 4 .\} .nf \fBtracefs\&.h\fR Header file to include in order to have access to the library APIs\&. \fB\-ltracefs\fR Linker switch to add when building a program that uses the library\&. .fi .if n \{\ .RE .\} .SH "SEE ALSO" .sp \fBlibtracefs\fR(3), \fBlibtraceevent\fR(3), \fBtrace\-cmd\fR(1) .SH "AUTHOR" .sp .if n \{\ .RS 4 .\} .nf \fBSteven Rostedt\fR <\m[blue]\fBrostedt@goodmis\&.org\fR\m[]\&\s-2\u[1]\d\s+2> \fBTzvetomir Stoyanov\fR <\m[blue]\fBtz\&.stoyanov@gmail\&.com\fR\m[]\&\s-2\u[2]\d\s+2> .fi .if n \{\ .RE .\} .SH "REPORTING BUGS" .sp Report bugs to <\m[blue]\fBlinux\-trace\-devel@vger\&.kernel\&.org\fR\m[]\&\s-2\u[3]\d\s+2> .SH "LICENSE" .sp libtracefs is Free Software licensed under the GNU LGPL 2\&.1 .SH "RESOURCES" .sp \m[blue]\fBhttps://git\&.kernel\&.org/pub/scm/libs/libtrace/libtracefs\&.git/\fR\m[] .SH "COPYING" .sp Copyright (C) 2021 VMware, Inc\&. Free use of this software is granted under the terms of the GNU Public License (GPL)\&. .SH "NOTES" .IP " 1." 4 rostedt@goodmis.org .RS 4 \%mailto:rostedt@goodmis.org .RE .IP " 2." 4 tz.stoyanov@gmail.com .RS 4 \%mailto:tz.stoyanov@gmail.com .RE .IP " 3." 4 linux-trace-devel@vger.kernel.org .RS 4 \%mailto:linux-trace-devel@vger.kernel.org .RE