libtraceevent-tseq.txt (4578B)
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