# trace_seq_init

## 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



           **#include <event-parse.h>**
           **#include <trace-seq.h>**
    
           void **trace_seq_init**(struct trace_seq *_s_);
           void **trace_seq_destroy**(struct trace_seq *_s_);
           void **trace_seq_reset**(struct trace_seq *_s_);
           void **trace_seq_terminate**(struct trace_seq *_s_);
           int **trace_seq_putc**(struct trace_seq *_s_ , unsigned char _c_);
           int **trace_seq_puts**(struct trace_seq *_s_ , const char *_str_);
           int **trace_seq_printf**(struct trace_seq *_s_ , const char *_fmt_ , _..._);
           int **trace_seq_vprintf**(struct trace_seq *_s_ , const char *_fmt_ , va_list _args_);
           int **trace_seq_do_printf**(struct trace_seq *_s_);
           int **trace_seq_do_fprintf**(struct trace_seq *_s_ , FILE *_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 '\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



               #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



               **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.
    


## LICENSE



           libtraceevent is Free Software licensed under the GNU LGPL 2.1
    


## RESOURCES



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


## NOTES



            1. rostedt@goodmis.org
               mailto:rostedt@goodmis.org
    
            2. tz.stoyanov@gmail.com
               mailto:tz.stoyanov@gmail.com
    
            3. linux-trace-devel@vger.kernel.org
               mailto:linux-trace-devel@vger.kernel.org
    


* * *