$1(1) BSD General Commands Manual $1(1)
NAME
ktrace -- Darwin kernel trace file format
SYNOPSIS
#include <ktrace_file.h>
DESCRIPTION
ktrace files are the native format of Darwin's kernel trace system, which
collects data about what a Darwin system is doing. ktrace is a binary
file format made up of individual chunks, each containing their type and
size. A chunk can be found in either the header or body of a ktrace
file. Header chunks are guaranteed to be available at the beginning of
the file and are written before body chunks. When parsing a ktrace file,
unrecognized chunks should be skipped and chunks should not be required
to be found in any order, aside from header chunks coming before body
chunks.
Tools should not attempt to parse ktrace files directly, and should
instead use the ktrace_file interface found in libktrace.
BINARY FORMAT
Individual chunks in a ktrace file have a 16-byte header:
+------+---------------+
| size | name |
+------+---------------+
| 4 | tag |
| 2 | major version |
| 2 | minor version |
| 8 | data size |
+------+---------------+
The data contained in a chunk follows its header. Different ktrace file
writers are given different ranges of tags. Tags that have been allocated
are declared in <ktrace_file_tags.h>. The major and minor version corre-
spond to the version of data found in a single chunk. The major version
is intended to be updated when a breaking change in the format of a
chunk's data occurs. The minor version should be updated if old parsers
can still read the data, but there may be extra information that will be
missed. The data size is the number of bytes of data that follows the
chunk header in the file.
Chunk headers must be aligned to 8 bytes, so if the data size is not a
multiple of 8, additional padding bytes will be added to the end of the
data before the next chunk header.
All ktrace files start with a header structure:
+------+-----------------------+
| size | name |
+------+-----------------------+
| 4 | magic number |
| 2 | major version |
| 2 | minor version |
| 8 | header size |
| 4 | timebase numerator |
| 4 | timebase denominator |
| 8 | timestamp |
| 8 | walltime seconds |
| 4 | walltime microseconds |
| 4 | minutes west of GMT |
| 4 | DST time enabled |
| 4 | flags |
+------+-----------------------+
The latest version of trace files, V3, have the magic number 0x55aa0300.
The version fields serve the same purpose as for individual chunks. The
header size field is the size of the entire header, excluding the first
16 bytes. It includes the sizes of all header chunks and their chunk
headers. Header chunks, if there are any, start directly after this
structure, followed by normal chunks. A typical file might look like
this:
+------+---------------------+
| size | name |
+------+---------------------+
| 64 | header structure |
| 16 | header chunk header |
| 32 | header chunk data |
| 16 | header chunk header |
| 14 | header chunk data |
| 2 | padding |
| 16 | normal chunk header |
| 128 | normal chunk data |
| 16 | normal chunk header |
| 252 | normal chunk data |
| 4 | optional padding |
+------+---------------------+
SEE ALSO
ktrace(1), ktfile(1), fs_usage(1)
Mac OS X Epoch Mac OS X
Mac OS X 10.12.6 - Generated Wed Nov 1 16:38:51 CDT 2017