1 CTF archives

The CTF archive format maps names to CTF dictionaries. The names may contain any character other than \0, but for now archives containing slashes in the names may not extract correctly. It is possible to insert multiple members with the same name, but these are quite hard to access reliably (you have to iterate through all the members rather than opening by name) so this is not recommended.

CTF archives are not themselves compressed: the constituent components, CTF dictionaries, can be compressed. (See section CTF header).

CTF archives usually contain a collection of related dictionaries, one parent and many children of that parent. CTF archives can have a member with a default name, .ctf (which can be represented as NULL in the API). If present, this member is usually the parent of all the children, but it is possible for CTF producers to emit parents with different names if they wish (usually for backward- compatibility purposes).

.ctf sections in ELF objects consist of a single CTF dictionary rather than an archive of dictionaries if and only if the section contains no types with identical names but conflicting definitions: if two conflicting definitions exist, the deduplicator will place the type most commonly referred to by other types in the parent and will place the other type in a child named after the translation unit it is found in, and will emit a CTF archive containing both dictionaries instead of a raw dictionary. All types that refer to such conflicting types are also placed in the per-translation-unit child.

The definition of an archive in ctf.h is as follows:

struct ctf_archive
{
  uint64_t ctfa_magic;
  uint64_t ctfa_model;
  uint64_t ctfa_nfiles;
  uint64_t ctfa_names;
  uint64_t ctfa_ctfs;
};

typedef struct ctf_archive_modent
{
  uint64_t name_offset;
  uint64_t ctf_offset;
} ctf_archive_modent_t;

(Note one irregularity here: the ctf_archive_t is not a typedef to struct ctf_archive, but a different typedef, private to libctf, so that things that are not really archives can be made to appear as if they were.)

All the above items are always in little-endian byte order, regardless of the machine endianness.

The archive header has the following fields:

The array pointed to by ctfa_names is an array of entries of ctf_archive_modent:

The ctfa_names array is sorted into ASCIIbetical order by name (i.e. by the result of dereferencing the name_offset).

The archive file also contains a name table and a table of CTF dictionaries: these are pointed to by the structures above. The name table is a simple strtab which is not required to be sorted; the dictionary array is described above in the entry for ctfa_ctfs.

The relative order of these various parts is not defined, except that the header naturally always comes first.