xref: /aosp_15_r20/external/libtraceevent/Documentation/libtraceevent-event_print.txt (revision 436bf2bcd5202612ffffe471bbcc1f277cc8d28e)

libtraceevent(3)
================

NAME
----
tep_print_event - Writes event information into a trace sequence.

SYNOPSIS
--------
[verse]
--
*#include <event-parse.h>*
*#include <trace-seq.h>*

void *tep_print_event*(struct tep_handle pass:[*]_tep_, struct trace_seqpass:[*]_s_, struct tep_record pass:[*]_record_, const char pass:[*]_fmt_, _..._)
--

DESCRIPTION
-----------

The *tep_print_event()* function parses the event information of the given
_record_ and writes it into the trace sequence _s_, according to the format
string _fmt_. The desired information is specified after the format string.
The _fmt_ is printf-like format string, following arguments are supported:
[verse]
--
	TEP_PRINT_PID, "%d"  - PID of the event.
	TEP_PRINT_CPU, "%d"  - Event CPU.
	TEP_PRINT_COMM, "%s" - Event command string.
	TEP_PRINT_NAME, "%s" - Event name.
	TEP_PRINT_LATENCY, "%s" - Latency of the event. It prints 4 or more
			fields - interrupt state, scheduling state,
			current context, and preemption count.
			Field 1 is the interrupt enabled state:
				d : Interrupts are disabled
				. : Interrupts are enabled
				X : The architecture does not support this
				    information
			Field 2 is the "need resched" state.
				N : The task is set to call the scheduler when
				    possible, as another higher priority task
				    may need to be scheduled in.
				. : The task is not set to call the scheduler.
			Field 3 is the context state.
				. : Normal context
				s : Soft interrupt context
				h : Hard interrupt context
				H : Hard interrupt context which triggered
				    during soft interrupt context.
				z : NMI context
				Z : NMI context which triggered during hard
				    interrupt context
			Field 4 is the preemption count.
				. : The preempt count is zero.
			On preemptible kernels (where the task can be scheduled
			out in arbitrary locations while in kernel context), the
			preempt count, when non zero, will prevent the kernel
			from scheduling out the current task. The preempt count
			number is displayed when it is not zero.
			Depending on the kernel, it may show other fields
			(lock depth, or migration disabled, which are unique to
			specialized kernels).
	TEP_PRINT_TIME, %d - event time stamp. A divisor and precision can be
			specified as part of this format string:
			"%precision.divisord". Example:
			"%3.1000d" - divide the time by 1000 and print the first
			3 digits before the dot. Thus, the time stamp
			"123456000" will be printed as "123.456"
	TEP_PRINT_INFO, "%s" - event information.
	TEP_PRINT_INFO_RAW, "%s" - event information, in raw format.

--
EXAMPLE
-------
[source,c]
--
#include <event-parse.h>
#include <trace-seq.h>
...
struct trace_seq seq;
trace_seq_init(&seq);
struct tep_handle *tep = tep_alloc();
...
void print_my_event(struct tep_record *record)
{
	trace_seq_reset(&seq);
	tep_print_event(tep, s, record, "%16s-%-5d [%03d] %s %6.1000d %s %s",
			TEP_PRINT_COMM, TEP_PRINT_PID, TEP_PRINT_CPU,
			TEP_PRINT_LATENCY, TEP_PRINT_TIME, TEP_PRINT_NAME,
			TEP_PRINT_INFO);
}
...
--

FILES
-----
[verse]
--
*event-parse.h*
	Header file to include in order to have access to the library APIs.
*trace-seq.h*
	Header file to include in order to have access to trace sequences related APIs.
	Trace sequences are used to allow a function to call several other functions
	to create a string of data to use.
*-ltraceevent*
	Linker switch to add when building a program that uses the library.
--

SEE ALSO
--------
*libtraceevent*(3), *trace-cmd*(1)

AUTHOR
------
[verse]
--
*Steven Rostedt* <[email protected]>, author of *libtraceevent*.
*Tzvetomir Stoyanov* <[email protected]>, author of this man page.
--
REPORTING BUGS
--------------
Report bugs to  <[email protected]>

LICENSE
-------
libtraceevent is Free Software licensed under the GNU LGPL 2.1

RESOURCES
---------
https://git.kernel.org/pub/scm/libs/libtrace/libtraceevent.git/