Next: CTF archive, Up: Top [Contents][Index]
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. Type lookups in child dicts that are not associated with a
parent at all will fail with ECTF_NOPARENT
if a parent type was
needed.
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.
Next: CTF archive, Up: Top [Contents][Index]