---
name: "tracecmd_read_cpu_first"
section: "3"
platform: "linux"
package: "trace-cmd"
version: "3.4-1"
release: "Arch Linux 2026-11-01"
platforms: ["linux"]
url: "https://new.carta.tech/tracecmd_read_cpu_first"
---

# tracecmd\_read\_cpu\_first(3)

Read recorded events from a trace file.

## NAME

tracecmd\_read\_cpu\_first, tracecmd\_read\_data, tracecmd\_read\_at, tracecmd\_free\_record, tracecmd\_get\_tep - Read recorded events from a trace file.

## SYNOPSIS

```
#include <trace-cmd.h>
struct tep_record *tracecmd_read_cpu_first(struct tracecmd_input *handle, int cpu);
struct tep_record *tracecmd_read_data(struct tracecmd_input *handle, int cpu);
struct tep_record *tracecmd_read_at(struct tracecmd_input *handle, unsigned long long offset, int *cpu);
void tracecmd_free_record(struct tep_record *record);
struct tep_handle *tracecmd_get_tep(struct tracecmd_input *handle);
```

## DESCRIPTION

This set of APIs can be used to read tracing data from a trace file opened with **tracecmd\_open()(3)**, **tracecmd\_open\_fd()(3)** or **tracecmd\_open\_head()(3)**.

The **tracecmd\_read\_cpu\_first()** function reads the first trace record for a given *cpu* from a trace file associated with *handle*. The returned record must be freed with **tracecmd\_free\_record()**.

The **tracecmd\_read\_data()** function reads the next trace record for a given *cpu* from a trace file associated with *handle* and increments the read location pointer, so that the next call to **tracecmd\_read\_data()** will not read the same record again. The returned record must be freed with **tracecmd\_free\_record()**.

The **tracecmd\_read\_at()** function reads a trace record from a specific *offset* within the file associated with *handle*. The CPU on which the recorded event occurred is stored in the *cpu*. The function does not change the current read location pointer. The returned record must be freed with **tracecmd\_free\_record()**.

The **tracecmd\_free\_record()** function frees a *record* returned by any of the *tracecmd\_read\_* APIs.

The **tracecmd\_get\_tep()** function returns a tep context for a given *handle*.

## RETURN VALUE

The **tracecmd\_read\_cpu\_first()**, **tracecmd\_read\_data()** and **tracecmd\_read\_at()** functions return a pointer to struct tep\_record or NULL in case of an error.The returned record must be freed with **tracecmd\_free\_record()**.

The **tracecmd\_get\_tep()** function returns a pointer to tep context or NULL if there is no tep context for the given *handle*. The returned tep pointer must **not** be freed.

## EXAMPLE

```
#include <trace-cmd.h>
...
struct tracecmd_input *handle = tracecmd_open("trace.dat");
        if (!handle) {
                /* Failed to open trace.dat file */
        }
...
unsigned long long offset = 0;
struct tep_record *rec;
int cpu = 0;
        rec = tracecmd_read_cpu_first(handle, cpu);
        while (rec) {
                ...
                if ( /* some interesting record noticed */) {
                        /* store the offset of the interesting record */
                        offset = rec->offset;
                }
                ...
                tracecmd_free_record(rec);
                rec = tracecmd_read_data(handle, cpu);
        }
        ...
        if (offset) {
                rec = tracecmd_read_at(handle, offset, &cpu);
                if (rec) {
                        /* Got record at offset on cpu */
                        ...
                        tracecmd_free_record(rec);
                }
        }
...
        tracecmd_close(hadle);
```

## 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)](/libtracefs/3.md)**, **[libtraceevent(3)](/libtraceevent/3.md)**, **[trace-cmd(1)](/trace-cmd/1.md)** **[trace-cmd.dat(5)](/trace-cmd.dat/5.md)**

## AUTHOR

```
Steven Rostedt <rostedt@goodmis.org[1]>
Tzvetomir Stoyanov <tz.stoyanov@gmail.com[2]>
```

## REPORTING BUGS

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

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

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