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