Format:CTF (Compact C Type Format)
| Developer | Sun Microsystems, then the libctf authors (binutils/GNU toolchain) |
|---|---|
| Versions | libctf CTF_VERSION_3 = 4 (older: 1, 2 upgraded, 3) |
| Magic | 0xdff2 (uint16, in the dictionary's byte order); archive magic 0x8b47f2a4d7623eeb |
| Endianness | dictionary-specific (libctf swaps on open); archive header little-endian |
| License | GPL-3.0 (include/ctf.h of binutils-gdb) |
| On this wiki | Facts · Code · Notes · Topics |
Compact type-information format for C (struct, union, enum, typedef, function and variable types, no line tables or locals) stored in an ELF section, typically .ctf, or a raw file: a header with the 16-bit magic 0xDF F2 as libctf (binutils, GCC 14 -gctf) writes it, label, object, function, variable, type and string sections, and an archive wrapper for parent/child dictionaries.
CTF is a much smaller alternative to Format:DWARF and Format:BTF (BPF Type Format) that keeps only what a debugger needs to print C types: it carries no line numbers, no local variables and no function bodies. It was designed for Solaris kernels and is read and written by libctf in GNU binutils and used by GCC (the -gctf option) and the Linux kernel's experimental CTF build. When a binary has a .ctf section, it gives struct layouts, enum values and function prototypes in a few kilobytes, which is often enough to type a stripped binary's data structures.
Identification
A CTF dictionary starts with the preamble ctp_magic (uint16, 0xdff2 in libctf's include/ctf.h), ctp_version (uint8, 4 for the current CTF_VERSION_3) and ctp_flags (uint8). Flags: 0x1 CTF_F_COMPRESS (the data after the header is compressed by libctf), 0x2 CTF_F_NEWFUNCINFO, 0x4 CTF_F_IDXSORTED, 0x8 CTF_F_DYNSTR (strings come from .dynstr). Unverified: the 2-byte magic is written in the byte order of the data model of the file, so a swapped 0xf2df means the dictionary has the other endianness; libctf byte-swaps on open (stated in the header comment). Unverified: Solaris/illumos and FreeBSD use an older header with magic 0xcff1 and version 2; the 0xdff2 magic is libctf's v3 form. See Fact:CTF (Compact C Type Format)/magic/Magic 0xDFF2.
Layout
The header gives offsets (relative to the end of the header) of: label section, data object section, function info section, optional object and function index sections (arrays of string table references that name the entries when the symbol table order is unknown), variable section, type section and string section, plus a string length. After the header the sections appear in that order: labels, objects, functions, object index, function index, variables, types, strings. Object and function entries are indexed in ELF symbol table order (undefined symbols skipped, symbols without a type padded with zeroes) and store only a type id, because the symbol table already supplies the names. Fact:CTF (Compact C Type Format)/struct/Header (version 3)
Strings are a 32-bit reference: bit 31 selects the string table (0 the CTF's own, 1 the ELF .dynstr/strtab of the object), the low 31 bits are the byte offset. Unverified: type ids are 1-based; ids with bit 31 set refer to a child dictionary's own types in the parent/child scheme (limits CTF_MAX_TYPE 0xfffffffe, CTF_MAX_PTYPE 0x7fffffff). A child dictionary (one translation unit) imports its parent (the shared, deduplicated types) by name through cth_parname. Unverified: the child-type bit is bit 31 (CTF_MAX_PTYPE suggests so); read ctf-open.c to settle it.
Type records
Types are a list of variable-size records in id order: ctt_name (string ref), ctt_info and a union ctt_size/ctt_type. In v2 and v3 ctt_info holds kind in bits 26-31, isroot in bit 25 and vlen (member count) in bits 0-24 (max 0xffffff); the small header form (ctf_stype) is 12 bytes. When a type is 0xffffffff bytes or larger, ctt_size is the sentinel 0xffffffff and two more words (ctt_lsizehi, ctt_lsizelo) follow. Kinds: 0 unknown, 1 integer, 2 float, 3 pointer, 4 array, 5 function, 6 struct, 7 union, 8 enum, 9 forward, 10 typedef, 11 volatile, 12 const, 13 restrict, 14 slice. Fact:CTF (Compact C Type Format)/enum/Type kinds
After the record come kind-specific lists: integer and float records are followed by one uint32 encoding (bits 24-31 encoding flags such as signed 0x01, char 0x02, bool 0x04, varargs 0x08; bits 16-23 offset; bits 0-15 width in bits); arrays by ctf_array_t (contents type, index type, element count); functions by vlen uint32 argument type ids; structs and unions by vlen member records (name, offset in bits, type; 12 bytes, or the 16-byte ctf_lmember form when the struct is 2^29 bits or larger); enums by (name, int32 value) pairs. Slices carry a type, bit offset and bit width, used for bit-fields.
Archives
libctf stores several dictionaries in one ctf_archive: eight-byte little-endian fields magic 0x8b47f2a4d7623eeb, data model, number of dictionaries, name table offset and CTF table offset, then an array of (name offset, CTF offset) pairs; each CTF table entry is a uint64 size followed by the dictionary. The dictionary named ".ctf" is the shared parent for the others. The ELF .ctf section of a linked binary is often such an archive. Unverified: whether a raw dictionary or an archive is stored depends on how many translation units were linked; check the first bytes for the dictionary magic 0xdff2 versus the archive magic.
Tools
binutils objdump --ctf=.ctf dumps a dictionary, and libctf's ctf_open and ctf_type_* API reads it; the linker deduplicates types across objects when --ctf-share-types is given. Unverified: these option names are quoted from memory and were not read in a source file.
Evidence & references
The field order, bit masks and magic numbers come from include/ctf.h of GNU binutils-gdb (https://sourceware.org/git/binutils-gdb.git commit b3874756227969658bd718e7ba2b152538bbb60c): header structs lines 148-186, magic line 188, versions 201-206, flags 212-217, ctf_stype/ctf_type 249-325, info macros 365-367, kind constants 408-427, integer and float encodings 433-480, member and array records 483-545, archive 586-600.