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