trace_seq_init(3) — Linux manual page

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | EXAMPLE | FILES | SEE ALSO | AUTHOR | REPORTING BUGS | LICENSE | RESOURCES | NOTES | COLOPHON

LIBTRACEEVENT(3)          libtraceevent Manual          LIBTRACEEVENT(3)

NAME         top

       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         top

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

       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         top

       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         top

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

           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         top

       libtraceevent(3), trace-cmd(1)

AUTHOR         top

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

REPORTING BUGS         top

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

LICENSE         top

       libtraceevent is Free Software licensed under the GNU LGPL 2.1

RESOURCES         top

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

NOTES         top

        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

COLOPHON         top

       This page is part of the libtraceevent (Linux kernel trace event
       library) project.  Information about the project can be found at
       ⟨https://www.trace-cmd.org/⟩.  If you have a bug report for this
       manual page, see ⟨https://www.trace-cmd.org/⟩.  This page was
       obtained from the project's upstream Git repository
       ⟨https://git.kernel.org/pub/scm/libs/libtrace/libtraceevent.git⟩
       on 2024-06-14.  (At that time, the date of the most recent commit
       that was found in the repository was 2024-05-17.)  If you
       discover any rendering problems in this HTML version of the page,
       or you believe there is a better or more up-to-date source for
       the page, or you have corrections or improvements to the
       information in this COLOPHON (which is not part of the original
       manual page), send a mail to man-pages@man7.org

libtraceevent 1.7.3            09/24/2023               LIBTRACEEVENT(3)