# libtracecmd(3) Manual Page

## NAME

tracecmd_open, tracecmd_open_fd, tracecmd_open_head, tracecmd_init_data, tracecmd_close, tracecmd_set_private, tracecmd_get_private - Open and close a trace file.

## SYNOPSIS

    #include <trace-cmd.h>

    struct tracecmd_input *tracecmd_open(const char *file, int flags);
    struct tracecmd_input *tracecmd_open_fd(int fd, int flags);
    struct tracecmd_input *tracecmd_open_head(const char *file, int flags);
    int tracecmd_init_data(struct tracecmd_input *handle);
    void tracecmd_close(struct tracecmd_input *handle);
    void tracecmd_set_private(struct tracecmd_input *handle, void *data);
    void *tracecmd_get_private(struct tracecmd_input *handle);

## DESCRIPTION

This set of APIs can be used to open and close a trace file recorded by trace-cmd(1) and containing tracing information from ftrace, the official Linux kernel tracer. The opened file is represented by a tracecmd_input structure, all other library APIs that work with the file require a pointer to the structure. The APIs for opening a trace file have a flag input parameter, which controls how the file will be opened and parsed. The flag is a combination of these options:

    TRACECMD_FL_LOAD_NO_PLUGINS - Do not load any plugins
    TRACECMD_FL_LOAD_NO_SYSTEM_PLUGINS - Do not load system wide plugins, load only "local only"
                                           plugins from user's home directory.

The tracecmd_open() function opens a given trace file, parses the metadata headers from the file, allocates and initializes а tracecmd_input handler structure representing the file. It also initializes the handler for reading trace data from the file. The returned handler is ready to be used with tracecmd_read_ APIs.

The tracecmd_open_fd() function does the same as tracecmd_open(), but works with a file descriptor to a trace file, opened for reading.

The tracecmd_open_head() function is the same as tracecmd_open(), but does not initialize the handler for reading trace data. It reads and parses the metadata headers only. The tracecmd_init_data() should be used before using the tracecmd_read_ APIs.

The tracecmd_init_data() function initializes a handle, allocated with tracecmd_open_head(), for reading trace data from the file associated with it. This API must be called before any of the tracecmd_read_ APIs.

The tracecmd_close() function frees a handle, pointer to tracecmd_input structure, previously allocated with tracecmd_open(), tracecmd_open_fd() or tracecmd_open_head() APIs.

The tracecmd_set_private() function allows to add specific data to the handle that can be retrieved later.

The tracecmd_get_private() function will retrieve the data set by tracecmd_set_private() for the given handle.

## RETURN VALUE

The tracecmd_open(), tracecmd_open_fd() and tracecmd_open_head() functions return a pointer to tracecmd_input structure or NULL in case of an error. The returned structure must be free with tracecmd_close(). Note that if tracecmd_open_fd() is used to allocate a tracecmd_input handler, when tracecmd_close() is called to close it, that fd will be closed also.

The tracecmd_init_data() function returns -1 in case of an error or 0 otherwise.

The tracecmd_get_private() returns the data set by tracecmd_set_private().

## EXAMPLE

## FILES

    trace-cmd.h
            Header file to include in order to have access to the library APIs.
    -ltracecmd
            Linker switch to add when building a program that uses the library.

## SEE ALSO

libtracefs(3), libtraceevent(3), trace-cmd(1) trace-cmd.dat(5)

## AUTHOR

    Steven Rostedt <rostedt@goodmis.org>
    Tzvetomir Stoyanov <tz.stoyanov@gmail.com>

## REPORTING BUGS

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

## LICENSE

libtracecmd is Free Software licensed under the GNU LGPL 2.1

## RESOURCES

https://git.kernel.org/pub/scm/utils/trace-cmd/trace-cmd.git/

## COPYING

Copyright (C) 2020 VMware, Inc. Free use of this software is granted under the terms of the GNU Public License (GPL).