0001 libtraceevent(3)
0002 ================
0003
0004 NAME
0005 ----
0006 trace_seq_init, trace_seq_destroy, trace_seq_reset, trace_seq_terminate,
0007 trace_seq_putc, trace_seq_puts, trace_seq_printf, trace_seq_vprintf,
0008 trace_seq_do_fprintf, trace_seq_do_printf -
0009 Initialize / destroy a trace sequence.
0010
0011 SYNOPSIS
0012 --------
0013 [verse]
0014 --
0015 *#include <event-parse.h>*
0016 *#include <trace-seq.h>*
0017
0018 void *trace_seq_init*(struct trace_seq pass:[*]_s_);
0019 void *trace_seq_destroy*(struct trace_seq pass:[*]_s_);
0020 void *trace_seq_reset*(struct trace_seq pass:[*]_s_);
0021 void *trace_seq_terminate*(struct trace_seq pass:[*]_s_);
0022 int *trace_seq_putc*(struct trace_seq pass:[*]_s_, unsigned char _c_);
0023 int *trace_seq_puts*(struct trace_seq pass:[*]_s_, const char pass:[*]_str_);
0024 int *trace_seq_printf*(struct trace_seq pass:[*]_s_, const char pass:[*]_fmt_, _..._);
0025 int *trace_seq_vprintf*(struct trace_seq pass:[*]_s_, const char pass:[*]_fmt_, va_list _args_);
0026 int *trace_seq_do_printf*(struct trace_seq pass:[*]_s_);
0027 int *trace_seq_do_fprintf*(struct trace_seq pass:[*]_s_, FILE pass:[*]_fp_);
0028 --
0029
0030 DESCRIPTION
0031 -----------
0032 Trace sequences are used to allow a function to call several other functions
0033 to create a string of data to use.
0034
0035 The _trace_seq_init()_ function initializes the trace sequence _s_.
0036
0037 The _trace_seq_destroy()_ function destroys the trace sequence _s_ and frees
0038 all its resources that it had used.
0039
0040 The _trace_seq_reset()_ function re-initializes the trace sequence _s_. All
0041 characters already written in _s_ will be deleted.
0042
0043 The _trace_seq_terminate()_ function terminates the trace sequence _s_. It puts
0044 the null character pass:['\0'] at the end of the buffer.
0045
0046 The _trace_seq_putc()_ function puts a single character _c_ in the trace
0047 sequence _s_.
0048
0049 The _trace_seq_puts()_ function puts a NULL terminated string _str_ in the
0050 trace sequence _s_.
0051
0052 The _trace_seq_printf()_ function puts a formated string _fmt _with
0053 variable arguments _..._ in the trace sequence _s_.
0054
0055 The _trace_seq_vprintf()_ function puts a formated string _fmt _with
0056 list of arguments _args_ in the trace sequence _s_.
0057
0058 The _trace_seq_do_printf()_ function prints the buffer of trace sequence _s_ to
0059 the standard output stdout.
0060
0061 The _trace_seq_do_fprintf()_ function prints the buffer of trace sequence _s_
0062 to the given file _fp_.
0063
0064 RETURN VALUE
0065 ------------
0066 Both _trace_seq_putc()_ and _trace_seq_puts()_ functions return the number of
0067 characters put in the trace sequence, or 0 in case of an error
0068
0069 Both _trace_seq_printf()_ and _trace_seq_vprintf()_ functions return 0 if the
0070 trace oversizes the buffer's free space, the number of characters printed, or
0071 a negative value in case of an error.
0072
0073 Both _trace_seq_do_printf()_ and _trace_seq_do_fprintf()_ functions return the
0074 number of printed characters, or -1 in case of an error.
0075
0076 EXAMPLE
0077 -------
0078 [source,c]
0079 --
0080 #include <event-parse.h>
0081 #include <trace-seq.h>
0082 ...
0083 struct trace_seq seq;
0084 trace_seq_init(&seq);
0085 ...
0086 void foo_seq_print(struct trace_seq *tseq, char *format, ...)
0087 {
0088 va_list ap;
0089 va_start(ap, format);
0090 if (trace_seq_vprintf(tseq, format, ap) <= 0) {
0091 /* Failed to print in the trace sequence */
0092 }
0093 va_end(ap);
0094 }
0095
0096 trace_seq_reset(&seq);
0097
0098 char *str = " MAN page example";
0099 if (trace_seq_puts(&seq, str) != strlen(str)) {
0100 /* Failed to put str in the trace sequence */
0101 }
0102 if (trace_seq_putc(&seq, ':') != 1) {
0103 /* Failed to put ':' in the trace sequence */
0104 }
0105 if (trace_seq_printf(&seq, " trace sequence: %d", 1) <= 0) {
0106 /* Failed to print in the trace sequence */
0107 }
0108 foo_seq_print( &seq, " %d\n", 2);
0109
0110 trace_seq_terminate(&seq);
0111 ...
0112
0113 if (trace_seq_do_printf(&seq) < 0 ) {
0114 /* Failed to print the sequence buffer to the standard output */
0115 }
0116 FILE *fp = fopen("trace.txt", "w");
0117 if (trace_seq_do_fprintf(&seq, fp) < 0 ) [
0118 /* Failed to print the sequence buffer to the trace.txt file */
0119 }
0120
0121 trace_seq_destroy(&seq);
0122 ...
0123 --
0124
0125 FILES
0126 -----
0127 [verse]
0128 --
0129 *event-parse.h*
0130 Header file to include in order to have access to the library APIs.
0131 *trace-seq.h*
0132 Header file to include in order to have access to trace sequences related APIs.
0133 *-ltraceevent*
0134 Linker switch to add when building a program that uses the library.
0135 --
0136
0137 SEE ALSO
0138 --------
0139 _libtraceevent(3)_, _trace-cmd(1)_
0140
0141 AUTHOR
0142 ------
0143 [verse]
0144 --
0145 *Steven Rostedt* <rostedt@goodmis.org>, author of *libtraceevent*.
0146 *Tzvetomir Stoyanov* <tz.stoyanov@gmail.com>, author of this man page.
0147 --
0148 REPORTING BUGS
0149 --------------
0150 Report bugs to <linux-trace-devel@vger.kernel.org>
0151
0152 LICENSE
0153 -------
0154 libtraceevent is Free Software licensed under the GNU LGPL 2.1
0155
0156 RESOURCES
0157 ---------
0158 https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git
