---
name: "trace_seq_init"
section: "3"
platform: "linux"
package: "libtraceevent"
version: "1:1.9.1-1"
release: "Arch Linux 2026-11-01"
platforms: ["linux"]
url: "https://new.carta.tech/trace_seq_init"
---

# trace\_seq\_init(3)

Initialize / destroy a trace sequence.

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

## SEE ALSO

[**libtraceevent**(3)](/libtraceevent/3.md), [**trace-cmd**(1)](/trace-cmd/1.md)

## AUTHOR

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

## REPORTING BUGS

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

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