Overview

The CTF file format compactly describes C types and the association between function and data symbols and types: if embedded in ELF objects, it can exploit the ELF string table to reduce duplication further. There is no real concept of namespacing: only top-level types are described, not types scoped to within single functions.

CTF dictionaries can be children of other dictionaries, in a one-level hierarchy: child dictionaries can refer to types in the parent, but the opposite is not sensible (since if you refer to a child type in the parent, the actual type you cited would vary depending on what child was attached). This parent/child definition is recorded in the child, but only as a recommendation: users of the API have to attach parents to children explicitly, and can choose to attach a child to any parent they like, or to none, though doing so might lead to unpleasant consequences like dangling references to types. See section Type indexes and type IDs.

(It is likely that in future we will forbid type lookups in dictionaries that were created as a child, opened, but not associated with a parent yet, but right now this will sometimes work. Don’t rely on it.)

The associated API to generate, merge together, and query this file format will be described in the accompanying libctf manual once it is written. There is no API to modify dictionaries once they’ve been written out: CTF is a write-once file format. (However, it is always possible to dynamically create a new child dictionary on the fly and attach it to a pre-existing, read-only parent.)

There are two major pieces to CTF: the archive and the dictionary. Some relatives and ancestors of CTF call dictionaries containers: the archive format is unique to this variant of CTF. (Much of the source code still uses the old term.)

The archive file format is a very simple mmappable archive used to group multiple dictionaries together into groups: it is expected to slowly go away and be replaced by other mechanisms, but right now it is an important part of the file format, used to group dictionaries containing types with conflicting definitions in different TUs with the overarching dictionary used to store all other types. (Even when archives go away, the libctf API used to access them will remain, and access the other mechanisms that replace it instead.)

The CTF dictionary consists of a preamble, which does not vary between versions of the CTF file format, and a header and some number of sections, which can vary between versions.

The rest of this specification describes the format of these sections, first for the latest version of CTF, then for all earlier versions supported by libctf: the earlier versions are defined in terms of their differences from the next later one. We describe each part of the format first by reproducing the C structure which defines that part, then describing it at greater length in terms of file offsets.

The description of the file format ends with a description of relevant limits that apply to it. These limits can vary between file format versions.

This document is quite young, so for now the C code in ctf.h should be presumed correct when this document conflicts with it.