'\" 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_tracer_set, tracefs_tracer_clear \- Enable or disable a tracer in an instance or the top level
.SH "SYNOPSIS"
.sp
.nf
\fB#include \fR
int \fBtracefs_tracer_set\fR(struct tracefs_instance *\fIinstance\fR, enum tracefs_tracers \fItracer\fR);
int \fBtracefs_tracer_set\fR(struct tracefs_instance *\fIinstance\fR, enum tracefs_tracers \fItracer\fR, const char *\fIname\fR);
int \fBtracefs_tracer_clear\fR(struct tracefs_instance *\fIinstance\fR);
.fi
.SH "DESCRIPTION"
.sp
\fBtracefs_tracer_set\fR enables a tracer in the given instance, defined by the \fIinstance\fR parameter\&. If \fIinstance\fR is NULL, then the top level instance is changed\&. If \fItracer\fR is set to \fBTRACFES_TRACER_CUSTOM\fR then a \fIname\fR string must be passed in as the third parameter, and that is written into the instance to enable the tracer with that name\&. This is useful for newer or custom kernels that contain tracers that are not yet identified by the tracefs_tracers enum\&.
.sp
\fBtracefs_tracer_clear\fR disables the tracer for the given instance defined by the \fIinstance\fR variable, or the top level instance if it is NULL\&. This is the same as calling \fBtracefs_tracer_set\fR with TRACEFS_TRACER_NOP as the \fItracer\fR parameter\&.
.SH "TRACEFS_TRACER ENUMS"
.sp
The currently defined enums that are accepted are:
.sp
\fBTRACEFS_TRACER_NOP\fR : This is the idle tracer, which does nothing and is used to clear any active tracer\&.
.sp
\fBTRACEFS_TRACER_FUNCTION\fR : Enables most functions in the kernel to be traced\&.
.sp
\fBTRACEFS_TRACER_FUNCTION_GRAPH\fR : Enables most functions in the kernel to be traced as well as the return of the function\&.
.sp
\fBTRACEFS_TRACER_IRQSOFF\fR : Tracers the latency of interrupts disabled\&.
.sp
\fBTRACEFS_TRACER_PREEMPTOFF\fR : Tracers the latency of preemption disabled (the time in the kernel that tasks can not be scheduled from the CPU)\&.
.sp
\fBTRACEFS_TRACER_PREEMPTIRQSOFF\fR : Traces the combined total latency of when interrupts are disabled as well as when preemption is disabled\&.
.sp
\fBTRACEFS_TRACER_WAKEUP\fR : Traces the latency of when the highest priority task takes to wake up\&.
.sp
\fBTRACEFS_TRACER_WAKEUP_RT\fR : Traces the latency of when the highest priority real\-time task takes to wake up\&. All other tasks are ignored\&.
.sp
\fBTRACEFS_TRACER_WAKEUP_DL\fR : Traces the latency of when the highest priority DEADLINE task takes to wake up\&. All other tasks are ignored\&.
.sp
\fBTRACEFS_TRACER_MMIOTRACE\fR : Traces the interaction of devices with the kernel\&.
.sp
\fBTRACEFS_TRACER_HWLAT\fR : Detects latency caused by the hardware that is outside the scope of the kernel\&.
.sp
\fBTRACEFS_TRACER_BRANCH\fR : Traces when likely or unlikely branches are taken\&.
.sp
\fBTRACEFS_TRACER_BLOCK\fR : Special tracer for the block devices\&.
.sp
Note that the above tracers may not be available in the kernel and \fBtracefs_tracer_set()\fR will return an error with errno set to ENODEV, if the kernel does not support the \fItracer\fR option, or the custom one if TRACEFS_TRACER_CUSTOM is used\&.
.SH "RETURN VALUE"
.sp
Returns 0 on success, or \-1 on error\&.
.SH "ERRORS"
.sp
\fBtracefs_tracer_set\fR() can fail with the following errors:
.sp
\fBEINVAL\fR The \fItracer\fR parameter is outside the scope of what is defined\&.
.sp
\fBENOMEM\fR Memory allocation error\&.
.sp
\fBENOENT\fR Tracers are not supported on the running kernel\&.
.sp
\fBENODEV\fR The specified tracer is not supported on the running kernel\&.
.sp
Other errors may also happen caused by internal system calls\&.
.SH "EXAMPLE"
.sp
.if n \{\
.RS 4
.\}
.nf
#include
#include
#include
#include
#include
int main(int argc, char *argv[])
{
struct tracefs_instance *inst = NULL;
enum tracefs_tracers t = TRACEFS_TRACER_NOP;
const char *buf = NULL;
const char *cust;
int ret;
int ch;
while ((ch = getopt(argc, argv, "nfgiwdc:B:")) > 0) {
switch (ch) {
case \*(Aqf\*(Aq: t = TRACEFS_TRACER_FUNCTION; break;
case \*(Aqg\*(Aq: t = TRACEFS_TRACER_FUNCTION_GRAPH; break;
case \*(Aqi\*(Aq: t = TRACEFS_TRACER_PREEMPTIRQSOFF; break;
case \*(Aqw\*(Aq: t = TRACEFS_TRACER_WAKEUP_RT; break;
case \*(Aqd\*(Aq: t = TRACEFS_TRACER_WAKEUP_DL; break;
case \*(Aqc\*(Aq:
t = TRACEFS_TRACER_CUSTOM;
cust = optarg;
break;
case \*(AqB\*(Aq:
buf = optarg;
break;
case \*(Aqn\*(Aq:
/* nop */
break;
default:
printf("Unknow arg %c\en", ch);
exit(\-1);
}
}
if (buf) {
inst = tracefs_instance_create(buf);
if (!inst) {
printf("failed to create instance\en");
exit(\-1);
}
}
if (t == TRACEFS_TRACER_CUSTOM)
ret = tracefs_tracer_set(inst, t, cust);
else
ret = tracefs_tracer_set(inst, t);
if (ret < 0) {
if (inst) {
tracefs_instance_destroy(inst);
tracefs_instance_free(inst);
}
if (errno == ENODEV)
printf("Tracer not supported by kernel\en");
else
perror("Error");
exit(\-1);
}
if (inst)
tracefs_instance_free(inst);
exit(0);
}
.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>
\fBsameeruddin shaik\fR <\m[blue]\fBsameeruddin\&.shaik8@gmail\&.com\fR\m[]\&\s-2\u[3]\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[4]\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) 2020 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
sameeruddin.shaik8@gmail.com
.RS 4
\%mailto:sameeruddin.shaik8@gmail.com
.RE
.IP " 4." 4
linux-trace-devel@vger.kernel.org
.RS 4
\%mailto:linux-trace-devel@vger.kernel.org
.RE