tools/lib/traceevent/Documentation/libtraceevent-event_print.txt

   1 libtraceevent(3)
   2 ================
   3
   4 NAME
   5 ----
   6 tep_print_event - Writes event information into a trace sequence.
   7
   8 SYNOPSIS
   9 --------
  10 [verse]
  11 --
  12 *#include <event-parse.h>*
  13 *#include <trace-seq.h>*
  14
  15 void *tep_print_event*(struct tep_handle pass:[*]_tep_, struct trace_seqpass:[*]_s_, struct tep_record pass:[*]_record_, const char pass:[*]_fmt_, _..._)
  16 --
  17
  18 DESCRIPTION
  19 -----------
  20
  21 The _tep_print_event()_ function parses the event information of the given
  22 _record_ and writes it into the trace sequence _s_, according to the format
  23 string _fmt_. The desired information is specified after the format string.
  24 The _fmt_ is printf-like format string, following arguments are supported:
  25 [verse]
  26 --
  27         TEP_PRINT_PID, "%d"  - PID of the event.
  28         TEP_PRINT_CPU, "%d"  - Event CPU.
  29         TEP_PRINT_COMM, "%s" - Event command string.
  30         TEP_PRINT_NAME, "%s" - Event name.
  31         TEP_PRINT_LATENCY, "%s" - Latency of the event. It prints 4 or more
  32                         fields - interrupt state, scheduling state,
  33                         current context, and preemption count.
  34                         Field 1 is the interrupt enabled state:
  35                                 d : Interrupts are disabled
  36                                 . : Interrupts are enabled
  37                                 X : The architecture does not support this
  38                                     information
  39                         Field 2 is the "need resched" state.
  40                                 N : The task is set to call the scheduler when
  41                                     possible, as another higher priority task
  42                                     may need to be scheduled in.
  43                                 . : The task is not set to call the scheduler.
  44                         Field 3 is the context state.
  45                                 . : Normal context
  46                                 s : Soft interrupt context
  47                                 h : Hard interrupt context
  48                                 H : Hard interrupt context which triggered
  49                                     during soft interrupt context.
  50                                 z : NMI context
  51                                 Z : NMI context which triggered during hard
  52                                     interrupt context
  53                         Field 4 is the preemption count.
  54                                 . : The preempt count is zero.
  55                         On preemptible kernels (where the task can be scheduled
  56                         out in arbitrary locations while in kernel context), the
  57                         preempt count, when non zero, will prevent the kernel
  58                         from scheduling out the current task. The preempt count
  59                         number is displayed when it is not zero.
  60                         Depending on the kernel, it may show other fields
  61                         (lock depth, or migration disabled, which are unique to
  62                         specialized kernels).
  63         TEP_PRINT_TIME, %d - event time stamp. A divisor and precision can be
  64                         specified as part of this format string:
  65                         "%precision.divisord". Example:
  66                         "%3.1000d" - divide the time by 1000 and print the first
  67                         3 digits before the dot. Thus, the time stamp
  68                         "123456000" will be printed as "123.456"
  69         TEP_PRINT_INFO, "%s" - event information.
  70         TEP_PRINT_INFO_RAW, "%s" - event information, in raw format.
  71
  72 --
  73 EXAMPLE
  74 -------
  75 [source,c]
  76 --
  77 #include <event-parse.h>
  78 #include <trace-seq.h>
  79 ...
  80 struct trace_seq seq;
  81 trace_seq_init(&seq);
  82 struct tep_handle *tep = tep_alloc();
  83 ...
  84 void print_my_event(struct tep_record *record)
  85 {
  86         trace_seq_reset(&seq);
  87         tep_print_event(tep, s, record, "%16s-%-5d [%03d] %s %6.1000d %s %s",
  88                         TEP_PRINT_COMM, TEP_PRINT_PID, TEP_PRINT_CPU,
  89                         TEP_PRINT_LATENCY, TEP_PRINT_TIME, TEP_PRINT_NAME,
  90                         TEP_PRINT_INFO);
  91 }
  92 ...
  93 --
  94
  95 FILES
  96 -----
  97 [verse]
  98 --
  99 *event-parse.h*
 100         Header file to include in order to have access to the library APIs.
 101 *trace-seq.h*
 102         Header file to include in order to have access to trace sequences related APIs.
 103         Trace sequences are used to allow a function to call several other functions
 104         to create a string of data to use.
 105 *-ltraceevent*
 106         Linker switch to add when building a program that uses the library.
 107 --
 108
 109 SEE ALSO
 110 --------
 111 _libtraceevent(3)_, _trace-cmd(1)_
 112
 113 AUTHOR
 114 ------
 115 [verse]
 116 --
 117 *Steven Rostedt* <rostedt@goodmis.org>, author of *libtraceevent*.
 118 *Tzvetomir Stoyanov* <tz.stoyanov@gmail.com>, author of this man page.
 119 --
 120 REPORTING BUGS
 121 --------------
 122 Report bugs to  <linux-trace-devel@vger.kernel.org>
 123
 124 LICENSE
 125 -------
 126 libtraceevent is Free Software licensed under the GNU LGPL 2.1
 127
 128 RESOURCES
 129 ---------
 130 https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git