1*4882a593Smuzhiyunlibtraceevent(3) 2*4882a593Smuzhiyun================ 3*4882a593Smuzhiyun 4*4882a593SmuzhiyunNAME 5*4882a593Smuzhiyun---- 6*4882a593Smuzhiyuntrace_seq_init, trace_seq_destroy, trace_seq_reset, trace_seq_terminate, 7*4882a593Smuzhiyuntrace_seq_putc, trace_seq_puts, trace_seq_printf, trace_seq_vprintf, 8*4882a593Smuzhiyuntrace_seq_do_fprintf, trace_seq_do_printf - 9*4882a593SmuzhiyunInitialize / destroy a trace sequence. 10*4882a593Smuzhiyun 11*4882a593SmuzhiyunSYNOPSIS 12*4882a593Smuzhiyun-------- 13*4882a593Smuzhiyun[verse] 14*4882a593Smuzhiyun-- 15*4882a593Smuzhiyun*#include <event-parse.h>* 16*4882a593Smuzhiyun*#include <trace-seq.h>* 17*4882a593Smuzhiyun 18*4882a593Smuzhiyunvoid *trace_seq_init*(struct trace_seq pass:[*]_s_); 19*4882a593Smuzhiyunvoid *trace_seq_destroy*(struct trace_seq pass:[*]_s_); 20*4882a593Smuzhiyunvoid *trace_seq_reset*(struct trace_seq pass:[*]_s_); 21*4882a593Smuzhiyunvoid *trace_seq_terminate*(struct trace_seq pass:[*]_s_); 22*4882a593Smuzhiyunint *trace_seq_putc*(struct trace_seq pass:[*]_s_, unsigned char _c_); 23*4882a593Smuzhiyunint *trace_seq_puts*(struct trace_seq pass:[*]_s_, const char pass:[*]_str_); 24*4882a593Smuzhiyunint *trace_seq_printf*(struct trace_seq pass:[*]_s_, const char pass:[*]_fmt_, _..._); 25*4882a593Smuzhiyunint *trace_seq_vprintf*(struct trace_seq pass:[*]_s_, const char pass:[*]_fmt_, va_list _args_); 26*4882a593Smuzhiyunint *trace_seq_do_printf*(struct trace_seq pass:[*]_s_); 27*4882a593Smuzhiyunint *trace_seq_do_fprintf*(struct trace_seq pass:[*]_s_, FILE pass:[*]_fp_); 28*4882a593Smuzhiyun-- 29*4882a593Smuzhiyun 30*4882a593SmuzhiyunDESCRIPTION 31*4882a593Smuzhiyun----------- 32*4882a593SmuzhiyunTrace sequences are used to allow a function to call several other functions 33*4882a593Smuzhiyunto create a string of data to use. 34*4882a593Smuzhiyun 35*4882a593SmuzhiyunThe _trace_seq_init()_ function initializes the trace sequence _s_. 36*4882a593Smuzhiyun 37*4882a593SmuzhiyunThe _trace_seq_destroy()_ function destroys the trace sequence _s_ and frees 38*4882a593Smuzhiyunall its resources that it had used. 39*4882a593Smuzhiyun 40*4882a593SmuzhiyunThe _trace_seq_reset()_ function re-initializes the trace sequence _s_. All 41*4882a593Smuzhiyuncharacters already written in _s_ will be deleted. 42*4882a593Smuzhiyun 43*4882a593SmuzhiyunThe _trace_seq_terminate()_ function terminates the trace sequence _s_. It puts 44*4882a593Smuzhiyunthe null character pass:['\0'] at the end of the buffer. 45*4882a593Smuzhiyun 46*4882a593SmuzhiyunThe _trace_seq_putc()_ function puts a single character _c_ in the trace 47*4882a593Smuzhiyunsequence _s_. 48*4882a593Smuzhiyun 49*4882a593SmuzhiyunThe _trace_seq_puts()_ function puts a NULL terminated string _str_ in the 50*4882a593Smuzhiyuntrace sequence _s_. 51*4882a593Smuzhiyun 52*4882a593SmuzhiyunThe _trace_seq_printf()_ function puts a formated string _fmt _with 53*4882a593Smuzhiyunvariable arguments _..._ in the trace sequence _s_. 54*4882a593Smuzhiyun 55*4882a593SmuzhiyunThe _trace_seq_vprintf()_ function puts a formated string _fmt _with 56*4882a593Smuzhiyunlist of arguments _args_ in the trace sequence _s_. 57*4882a593Smuzhiyun 58*4882a593SmuzhiyunThe _trace_seq_do_printf()_ function prints the buffer of trace sequence _s_ to 59*4882a593Smuzhiyunthe standard output stdout. 60*4882a593Smuzhiyun 61*4882a593SmuzhiyunThe _trace_seq_do_fprintf()_ function prints the buffer of trace sequence _s_ 62*4882a593Smuzhiyunto the given file _fp_. 63*4882a593Smuzhiyun 64*4882a593SmuzhiyunRETURN VALUE 65*4882a593Smuzhiyun------------ 66*4882a593SmuzhiyunBoth _trace_seq_putc()_ and _trace_seq_puts()_ functions return the number of 67*4882a593Smuzhiyuncharacters put in the trace sequence, or 0 in case of an error 68*4882a593Smuzhiyun 69*4882a593SmuzhiyunBoth _trace_seq_printf()_ and _trace_seq_vprintf()_ functions return 0 if the 70*4882a593Smuzhiyuntrace oversizes the buffer's free space, the number of characters printed, or 71*4882a593Smuzhiyuna negative value in case of an error. 72*4882a593Smuzhiyun 73*4882a593SmuzhiyunBoth _trace_seq_do_printf()_ and _trace_seq_do_fprintf()_ functions return the 74*4882a593Smuzhiyunnumber of printed characters, or -1 in case of an error. 75*4882a593Smuzhiyun 76*4882a593SmuzhiyunEXAMPLE 77*4882a593Smuzhiyun------- 78*4882a593Smuzhiyun[source,c] 79*4882a593Smuzhiyun-- 80*4882a593Smuzhiyun#include <event-parse.h> 81*4882a593Smuzhiyun#include <trace-seq.h> 82*4882a593Smuzhiyun... 83*4882a593Smuzhiyunstruct trace_seq seq; 84*4882a593Smuzhiyuntrace_seq_init(&seq); 85*4882a593Smuzhiyun... 86*4882a593Smuzhiyunvoid foo_seq_print(struct trace_seq *tseq, char *format, ...) 87*4882a593Smuzhiyun{ 88*4882a593Smuzhiyun va_list ap; 89*4882a593Smuzhiyun va_start(ap, format); 90*4882a593Smuzhiyun if (trace_seq_vprintf(tseq, format, ap) <= 0) { 91*4882a593Smuzhiyun /* Failed to print in the trace sequence */ 92*4882a593Smuzhiyun } 93*4882a593Smuzhiyun va_end(ap); 94*4882a593Smuzhiyun} 95*4882a593Smuzhiyun 96*4882a593Smuzhiyuntrace_seq_reset(&seq); 97*4882a593Smuzhiyun 98*4882a593Smuzhiyunchar *str = " MAN page example"; 99*4882a593Smuzhiyunif (trace_seq_puts(&seq, str) != strlen(str)) { 100*4882a593Smuzhiyun /* Failed to put str in the trace sequence */ 101*4882a593Smuzhiyun} 102*4882a593Smuzhiyunif (trace_seq_putc(&seq, ':') != 1) { 103*4882a593Smuzhiyun /* Failed to put ':' in the trace sequence */ 104*4882a593Smuzhiyun} 105*4882a593Smuzhiyunif (trace_seq_printf(&seq, " trace sequence: %d", 1) <= 0) { 106*4882a593Smuzhiyun /* Failed to print in the trace sequence */ 107*4882a593Smuzhiyun} 108*4882a593Smuzhiyunfoo_seq_print( &seq, " %d\n", 2); 109*4882a593Smuzhiyun 110*4882a593Smuzhiyuntrace_seq_terminate(&seq); 111*4882a593Smuzhiyun... 112*4882a593Smuzhiyun 113*4882a593Smuzhiyunif (trace_seq_do_printf(&seq) < 0 ) { 114*4882a593Smuzhiyun /* Failed to print the sequence buffer to the standard output */ 115*4882a593Smuzhiyun} 116*4882a593SmuzhiyunFILE *fp = fopen("trace.txt", "w"); 117*4882a593Smuzhiyunif (trace_seq_do_fprintf(&seq, fp) < 0 ) [ 118*4882a593Smuzhiyun /* Failed to print the sequence buffer to the trace.txt file */ 119*4882a593Smuzhiyun} 120*4882a593Smuzhiyun 121*4882a593Smuzhiyuntrace_seq_destroy(&seq); 122*4882a593Smuzhiyun... 123*4882a593Smuzhiyun-- 124*4882a593Smuzhiyun 125*4882a593SmuzhiyunFILES 126*4882a593Smuzhiyun----- 127*4882a593Smuzhiyun[verse] 128*4882a593Smuzhiyun-- 129*4882a593Smuzhiyun*event-parse.h* 130*4882a593Smuzhiyun Header file to include in order to have access to the library APIs. 131*4882a593Smuzhiyun*trace-seq.h* 132*4882a593Smuzhiyun Header file to include in order to have access to trace sequences related APIs. 133*4882a593Smuzhiyun*-ltraceevent* 134*4882a593Smuzhiyun Linker switch to add when building a program that uses the library. 135*4882a593Smuzhiyun-- 136*4882a593Smuzhiyun 137*4882a593SmuzhiyunSEE ALSO 138*4882a593Smuzhiyun-------- 139*4882a593Smuzhiyun_libtraceevent(3)_, _trace-cmd(1)_ 140*4882a593Smuzhiyun 141*4882a593SmuzhiyunAUTHOR 142*4882a593Smuzhiyun------ 143*4882a593Smuzhiyun[verse] 144*4882a593Smuzhiyun-- 145*4882a593Smuzhiyun*Steven Rostedt* <rostedt@goodmis.org>, author of *libtraceevent*. 146*4882a593Smuzhiyun*Tzvetomir Stoyanov* <tz.stoyanov@gmail.com>, author of this man page. 147*4882a593Smuzhiyun-- 148*4882a593SmuzhiyunREPORTING BUGS 149*4882a593Smuzhiyun-------------- 150*4882a593SmuzhiyunReport bugs to <linux-trace-devel@vger.kernel.org> 151*4882a593Smuzhiyun 152*4882a593SmuzhiyunLICENSE 153*4882a593Smuzhiyun------- 154*4882a593Smuzhiyunlibtraceevent is Free Software licensed under the GNU LGPL 2.1 155*4882a593Smuzhiyun 156*4882a593SmuzhiyunRESOURCES 157*4882a593Smuzhiyun--------- 158*4882a593Smuzhiyunhttps://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git 159