1LIBTRACEEVENT(3)             libtraceevent Manual             LIBTRACEEVENT(3)
2
3
4

NAME

6       trace_seq_init, trace_seq_destroy, trace_seq_reset,
7       trace_seq_terminate, trace_seq_putc, trace_seq_puts, trace_seq_printf,
8       trace_seq_vprintf, trace_seq_do_fprintf, trace_seq_do_printf -
9       Initialize / destroy a trace sequence.
10

SYNOPSIS

12       #include <event-parse.h>
13       #include <trace-seq.h>
14
15       void trace_seq_init(struct trace_seq *s);
16       void trace_seq_destroy(struct trace_seq *s);
17       void trace_seq_reset(struct trace_seq *s);
18       void trace_seq_terminate(struct trace_seq *s);
19       int trace_seq_putc(struct trace_seq *s, unsigned char c);
20       int trace_seq_puts(struct trace_seq *s, const char *str);
21       int trace_seq_printf(struct trace_seq *s, const char *fmt, ...);
22       int trace_seq_vprintf(struct trace_seq *s, const char *fmt, va_list args);
23       int trace_seq_do_printf(struct trace_seq *s);
24       int trace_seq_do_fprintf(struct trace_seq *s, FILE *fp);
25

DESCRIPTION

27       Trace sequences are used to allow a function to call several other
28       functions to create a string of data to use.
29
30       The trace_seq_init() function initializes the trace sequence s.
31
32       The trace_seq_destroy() function destroys the trace sequence s and
33       frees all its resources that it had used.
34
35       The trace_seq_reset() function re-initializes the trace sequence s. All
36       characters already written in s will be deleted.
37
38       The trace_seq_terminate() function terminates the trace sequence s. It
39       puts the null character '\0' at the end of the buffer.
40
41       The trace_seq_putc() function puts a single character c in the trace
42       sequence s.
43
44       The trace_seq_puts() function puts a NULL terminated string str in the
45       trace sequence s.
46
47       The trace_seq_printf() function puts a formated string fmt _with
48       variable arguments _... in the trace sequence s.
49
50       The trace_seq_vprintf() function puts a formated string fmt _with list
51       of arguments _args in the trace sequence s.
52
53       The trace_seq_do_printf() function prints the buffer of trace sequence
54       s to the standard output stdout.
55
56       The trace_seq_do_fprintf() function prints the buffer of trace sequence
57       s to the given file fp.
58

RETURN VALUE

60       Both trace_seq_putc() and trace_seq_puts() functions return the number
61       of characters put in the trace sequence, or 0 in case of an error
62
63       Both trace_seq_printf() and trace_seq_vprintf() functions return 0 if
64       the trace oversizes the buffer’s free space, the number of characters
65       printed, or a negative value in case of an error.
66
67       Both trace_seq_do_printf() and trace_seq_do_fprintf() functions return
68       the number of printed characters, or -1 in case of an error.
69

EXAMPLE

71           #include <event-parse.h>
72           #include <trace-seq.h>
73           ...
74           struct trace_seq seq;
75           trace_seq_init(&seq);
76           ...
77           void foo_seq_print(struct trace_seq *tseq, char *format, ...)
78           {
79                   va_list ap;
80                   va_start(ap, format);
81                   if (trace_seq_vprintf(tseq, format, ap) <= 0) {
82                           /* Failed to print in the trace sequence */
83                   }
84                   va_end(ap);
85           }
86
87           trace_seq_reset(&seq);
88
89           char *str = " MAN page example";
90           if (trace_seq_puts(&seq, str) != strlen(str)) {
91                   /* Failed to put str in the trace sequence */
92           }
93           if (trace_seq_putc(&seq, ':') != 1) {
94                   /* Failed to put ':' in the trace sequence */
95           }
96           if (trace_seq_printf(&seq, " trace sequence: %d", 1) <= 0) {
97                   /* Failed to print in the trace sequence */
98           }
99           foo_seq_print( &seq, "  %d\n", 2);
100
101           trace_seq_terminate(&seq);
102           ...
103
104           if (trace_seq_do_printf(&seq) < 0 ) {
105                   /* Failed to print the sequence buffer to the standard output */
106           }
107           FILE *fp = fopen("trace.txt", "w");
108           if (trace_seq_do_fprintf(&seq, fp) < 0 ) [
109                   /* Failed to print the sequence buffer to the trace.txt file */
110           }
111
112           trace_seq_destroy(&seq);
113           ...
114

FILES

116           event-parse.h
117                   Header file to include in order to have access to the library APIs.
118           trace-seq.h
119                   Header file to include in order to have access to trace sequences related APIs.
120           -ltraceevent
121                   Linker switch to add when building a program that uses the library.
122

SEE ALSO

124       libtraceevent(3), trace-cmd(1)
125

AUTHOR

127           Steven Rostedt <rostedt@goodmis.org[1]>, author of libtraceevent.
128           Tzvetomir Stoyanov <tz.stoyanov@gmail.com[2]>, author of this man page.
129

REPORTING BUGS

131       Report bugs to <linux-trace-devel@vger.kernel.org[3]>
132

LICENSE

134       libtraceevent is Free Software licensed under the GNU LGPL 2.1
135

RESOURCES

137       https://git.kernel.org/pub/scm/libs/libtrace/libtraceevent.git/
138

NOTES

140        1. rostedt@goodmis.org
141           mailto:rostedt@goodmis.org
142
143        2. tz.stoyanov@gmail.com
144           mailto:tz.stoyanov@gmail.com
145
146        3. linux-trace-devel@vger.kernel.org
147           mailto:linux-trace-devel@vger.kernel.org
148
149
150
151libtraceevent 1.1.1               02/08/2021                  LIBTRACEEVENT(3)
Impressum