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

   1 libtraceevent(3)
   2 ================
   3
   4 NAME
   5 ----
   6 trace_seq_init, trace_seq_destroy, trace_seq_reset, trace_seq_terminate,
   7 trace_seq_putc, trace_seq_puts, trace_seq_printf, trace_seq_vprintf,
   8 trace_seq_do_fprintf, trace_seq_do_printf -
   9 Initialize / destroy a trace sequence.
  10
  11 SYNOPSIS
  12 --------
  13 [verse]
  14 --
  15 *#include <event-parse.h>*
  16 *#include <trace-seq.h>*
  17
  18 void *trace_seq_init*(struct trace_seq pass:[*]_s_);
  19 void *trace_seq_destroy*(struct trace_seq pass:[*]_s_);
  20 void *trace_seq_reset*(struct trace_seq pass:[*]_s_);
  21 void *trace_seq_terminate*(struct trace_seq pass:[*]_s_);
  22 int *trace_seq_putc*(struct trace_seq pass:[*]_s_, unsigned char _c_);
  23 int *trace_seq_puts*(struct trace_seq pass:[*]_s_, const char pass:[*]_str_);
  24 int *trace_seq_printf*(struct trace_seq pass:[*]_s_, const char pass:[*]_fmt_, _..._);
  25 int *trace_seq_vprintf*(struct trace_seq pass:[*]_s_, const char pass:[*]_fmt_, va_list _args_);
  26 int *trace_seq_do_printf*(struct trace_seq pass:[*]_s_);
  27 int *trace_seq_do_fprintf*(struct trace_seq pass:[*]_s_, FILE pass:[*]_fp_);
  28 --
  29
  30 DESCRIPTION
  31 -----------
  32 Trace sequences are used to allow a function to call several other functions
  33 to create a string of data to use.
  34
  35 The _trace_seq_init()_ function initializes the trace sequence _s_.
  36
  37 The _trace_seq_destroy()_ function destroys the trace sequence _s_ and frees
  38 all its resources that it had used.
  39
  40 The _trace_seq_reset()_ function re-initializes the trace sequence _s_. All
  41 characters already written in _s_ will be deleted.
  42
  43 The _trace_seq_terminate()_ function terminates the trace sequence _s_. It puts
  44 the null character pass:['\0'] at the end of the buffer.
  45
  46 The _trace_seq_putc()_ function puts a single character _c_ in the trace
  47 sequence _s_.
  48
  49 The _trace_seq_puts()_ function puts a NULL terminated string _str_ in the
  50 trace sequence _s_.
  51
  52 The _trace_seq_printf()_ function puts a formated string _fmt _with
  53 variable arguments _..._ in the trace sequence _s_.
  54
  55 The _trace_seq_vprintf()_ function puts a formated string _fmt _with
  56 list of arguments _args_ in the trace sequence _s_.
  57
  58 The _trace_seq_do_printf()_ function prints the buffer of trace sequence _s_ to
  59 the standard output stdout.
  60
  61 The _trace_seq_do_fprintf()_ function prints the buffer of trace sequence _s_
  62 to the given file _fp_.
  63
  64 RETURN VALUE
  65 ------------
  66 Both _trace_seq_putc()_ and _trace_seq_puts()_ functions return the number of
  67 characters put in the trace sequence, or 0 in case of an error
  68
  69 Both _trace_seq_printf()_ and _trace_seq_vprintf()_ functions return 0 if the
  70 trace oversizes the buffer's free space, the number of characters printed, or
  71 a negative value in case of an error.
  72
  73 Both _trace_seq_do_printf()_ and _trace_seq_do_fprintf()_ functions return the
  74 number of printed characters, or -1 in case of an error.
  75
  76 EXAMPLE
  77 -------
  78 [source,c]
  79 --
  80 #include <event-parse.h>
  81 #include <trace-seq.h>
  82 ...
  83 struct trace_seq seq;
  84 trace_seq_init(&seq);
  85 ...
  86 void foo_seq_print(struct trace_seq *tseq, char *format, ...)
  87 {
  88         va_list ap;
  89         va_start(ap, format);
  90         if (trace_seq_vprintf(tseq, format, ap) <= 0) {
  91                 /* Failed to print in the trace sequence */
  92         }
  93         va_end(ap);
  94 }
  95
  96 trace_seq_reset(&seq);
  97
  98 char *str = " MAN page example";
  99 if (trace_seq_puts(&seq, str) != strlen(str)) {
 100         /* Failed to put str in the trace sequence */
 101 }
 102 if (trace_seq_putc(&seq, ':') != 1) {
 103         /* Failed to put ':' in the trace sequence */
 104 }
 105 if (trace_seq_printf(&seq, " trace sequence: %d", 1) <= 0) {
 106         /* Failed to print in the trace sequence */
 107 }
 108 foo_seq_print( &seq, "  %d\n", 2);
 109
 110 trace_seq_terminate(&seq);
 111 ...
 112
 113 if (trace_seq_do_printf(&seq) < 0 ) {
 114         /* Failed to print the sequence buffer to the standard output */
 115 }
 116 FILE *fp = fopen("trace.txt", "w");
 117 if (trace_seq_do_fprintf(&seq, fp) < 0 ) [
 118         /* Failed to print the sequence buffer to the trace.txt file */
 119 }
 120
 121 trace_seq_destroy(&seq);
 122 ...
 123 --
 124
 125 FILES
 126 -----
 127 [verse]
 128 --
 129 *event-parse.h*
 130         Header file to include in order to have access to the library APIs.
 131 *trace-seq.h*
 132         Header file to include in order to have access to trace sequences related APIs.
 133 *-ltraceevent*
 134         Linker switch to add when building a program that uses the library.
 135 --
 136
 137 SEE ALSO
 138 --------
 139 _libtraceevent(3)_, _trace-cmd(1)_
 140
 141 AUTHOR
 142 ------
 143 [verse]
 144 --
 145 *Steven Rostedt* <rostedt@goodmis.org>, author of *libtraceevent*.
 146 *Tzvetomir Stoyanov* <tz.stoyanov@gmail.com>, author of this man page.
 147 --
 148 REPORTING BUGS
 149 --------------
 150 Report bugs to  <linux-trace-devel@vger.kernel.org>
 151
 152 LICENSE
 153 -------
 154 libtraceevent is Free Software licensed under the GNU LGPL 2.1
 155
 156 RESOURCES
 157 ---------
 158 https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git