Jump to content
Setting up an AI agent? ReverseEngineering.wiki skill (works from the command line, no configuration): https://reverseengineering.wiki/skill/rewiki/SKILL.md · setup for every client, including MCP: https://reverseengineering.wiki/llms.txt · REWiki:Connect

Format:Mach-O/Chained fixups

From ReverseEngineering.wiki
Topic page of Format:Mach-O.

LC_DYLD_CHAINED_FIXUPS (0x80000034): the header, per-segment starts, import tables and every DYLD_CHAINED_PTR_* pointer format with bit layouts (including arm64e authenticated pointers), as defined in dyld's fixup-chains.h.

Overview

Since the iOS 15 / macOS 12 toolchains (-fixup_chains) a linked image carries pointer fixups as linked lists inside the data itself instead of the opcode streams of LC_DYLD_INFO (see Format:Mach-O/Bind and rebase opcodes). The load command is LC_DYLD_CHAINED_FIXUPS = 0x80000034 (a linkedit_data_command pointing into __LINKEDIT); LC_DYLD_EXPORTS_TRIE = 0x80000033 holds the export trie separately. Until the chains are decoded, pointers in __DATA, __got and __objc_* sections look like garbage (tag bits in the high bits). Decode them before following pointers, see Technique:Objective-C runtime metadata.

Header and starts

All fields are little-endian uint32 unless noted. Offsets are relative to the start of the blob.

struct dyld_chained_fixups_header {
  uint32_t fixups_version;  // 0
  uint32_t starts_offset;   // -> dyld_chained_starts_in_image
  uint32_t imports_offset;  // -> import table
  uint32_t symbols_offset;  // -> symbol-name pool
  uint32_t imports_count;
  uint32_t imports_format;  // 1 IMPORT, 2 IMPORT_ADDEND, 3 IMPORT_ADDEND64
  uint32_t symbols_format;  // 0 uncompressed, 1 zlib
};
struct dyld_chained_starts_in_image {
  uint32_t seg_count;
  uint32_t seg_info_offset[];   // one per segment, 0 = segment has no fixups
};
struct dyld_chained_starts_in_segment {
  uint32_t size;
  uint16_t page_size;        // 0x1000 or 0x4000
  uint16_t pointer_format;   // DYLD_CHAINED_PTR_*
  uint64_t segment_offset;   // from the start of __TEXT (vm offset)
  uint32_t max_valid_pointer;// 32-bit formats only
  uint16_t page_count;
  uint16_t page_start[];     // per page: offset of the first fixup, or a marker
};

page_start values: 0xFFFF (DYLD_CHAINED_PTR_START_NONE) no fixups on the page; 0x8000 (START_MULTI) the value indexes an overflow list of starts (some 32-bit formats); 0x8000 also marks the last entry of that list (START_LAST). Otherwise the value is the byte offset in the page of the first chain entry. Follow each chain by adding next times the stride (see below) until next is 0.

Imports

struct dyld_chained_import        { uint32_t lib_ordinal:8, weak_import:1, name_offset:23; };
struct dyld_chained_import_addend { /* same word */ int32_t addend; };
struct dyld_chained_import_addend64 { uint64_t lib_ordinal:16, weak_import:1, reserved:15, name_offset:32; uint64_t addend; };

name_offset is a byte offset into the symbol pool at symbols_offset (NUL-terminated names). lib_ordinal is the 1-based index of the LC_LOAD_DYLIB-family command; the top values are special: dyld's fixup-chains.h comments the 8-bit field as "-15 .. 240 (0xF1 .. 0xF0)", i.e. 0x01-0xF0 are dylib ordinals and 0xF1-0xFF are the signed values -15 to -1 (so 0xFF = -1 main executable, 0xFE = -2 flat lookup, 0xFD = -3 weak lookup, the same numbers as BIND_SPECIAL_DYLIB_* in loader.h). The 16-bit field of IMPORT_ADDEND64 is commented "-15 .. 65520 (0xFFF1 .. 0xFFF0)" the same way. Unverified: that the 0xFF/0xFE/0xFD mapping is applied by dyld exactly as the loader.h constants suggest (the header gives only the range comment).

Pointer formats (pointer_format)

Value Name Stride Notes
1 ARM64E 8 arm64e, unauthenticated target is a vmaddr
2 64 4 generic 64-bit, target is a vmaddr
3 32 4 32-bit
4 32_CACHE 4
5 32_FIRMWARE 4
6 64_OFFSET 4 like 64, target is a vm offset
7 ARM64E_KERNEL 4 target is a vm offset (old name ARM64E_OFFSET)
8 64_KERNEL_CACHE 4 (or 1)
9 ARM64E_USERLAND 8 target is a vm offset
10 ARM64E_FIRMWARE 4 target is a vmaddr
11 X86_64_KERNEL_CACHE 1
12 ARM64E_USERLAND24 8 24-bit bind ordinal
13 ARM64E_SHARED_CACHE 8 A keys only
14 ARM64E_SEGMENTED 4 two uint32 words, segment index plus offset

Checked in apple-oss-distributions/dyld include/mach-o/fixup-chains.h @ fd8d0c4d52: the enum comments and the next field comments give the strides above. The 64 and 64_OFFSET formats share dyld_chained_ptr_64_rebase/bind (next: 12 bits, 4-byte stride); 32, 32_CACHE and 32_FIRMWARE are each commented 4-byte stride; the 64_KERNEL_CACHE rebase comment reads 1 or 4-byte stride.

Bit layouts (least significant bit first)

Arm64e (formats 1, 7, 9, 10; bit 63 is auth, bit 62 is bind):

  • rebase: target:43, high8:8, next:11, bind=0, auth=0. The final pointer is target with high8 placed in bits 56-63.
  • bind: ordinal:16, zero:16, addend:19, next:11, bind=1, auth=0.
  • auth_rebase: target:32, diversity:16, addrDiv:1, key:2, next:11, bind=0, auth=1.
  • auth_bind: ordinal:16, zero:16, diversity:16, addrDiv:1, key:2, next:11, bind=1, auth=1.
  • USERLAND24 (12): bind24 is ordinal:24, zero:8, addend:19, next:11, bind=1, auth=0; auth_bind24 is ordinal:24, zero:8, diversity:16, addrDiv:1, key:2, next:11, bind=1, auth=1.

Pointer authentication fields: diversity is the 16-bit constant discriminator, addrDiv mixes in the address of the pointer slot, key selects the PAC key (Unverified: 0 IA, 1 IB, 2 DA, 3 DB, from the Arm architecture, not read in the header).

Generic 64-bit (2, 6): rebase target:36, high8:8, reserved:7, next:12, bind=0; bind ordinal:24, addend:8, reserved:19, next:12, bind=1.

64_KERNEL_CACHE (8) and X86_64_KERNEL_CACHE (11): target:30, cacheLevel:2, diversity:16, addrDiv:1, key:2, next:12, isAuth:1.

ARM64E_SHARED_CACHE (13): rebase runtimeOffset:34, high8:8, unused:10, next:11, auth=0; auth_rebase runtimeOffset:34, diversity:16, addrDiv:1, keyIsData:1, next:11, auth=1.

ARM64E_SEGMENTED (14), two uint32 words: word 0 targetSegOffset:28, targetSegIndex:4; word 1 padding:19, next:12, auth=0 (rebase) or diversity:16, addrDiv:1, key:2, next:12, auth=1.

32-bit: 32 rebase target:26, next:5, bind=0; bind ordinal:20, addend:6, next:5, bind=1; 32_CACHE target:30, next:2; 32_FIRMWARE target:26, next:6. In format 32, a value above max_valid_pointer is plain data, not a pointer; the header gives the bias (64MB + max_valid_pointer) / 2 for recovering it.

The header defines no struct for ARM64E_KERNEL (7) or ARM64E_FIRMWARE (10); use the arm64e layouts above.

Firmware images

dyld_chained_starts_offsets { uint32 pointer_format; uint32 starts_count; uint32 chain_starts[] } in a __TEXT,__chain_starts section lists chain starts for images without a normal load command; its reserved1 flags 0x1 (USE_FILE_OFFSET) and 0x2 (USE_VM_OFFSET) say how the starts are expressed.

Reversing notes

  • Disassemblers without chain support show garbage pointers; resolve them first (the dyld shared cache extractors do this for system libraries, see Format:Dyld shared cache).
  • Distinguish format by the pointer_format of the segment, not by CPU type alone: arm64 apps normally use 2 or 6, arm64e uses 1, 9 or 12.
  • Binding the import: ordinal indexes the import table, not the dylib list.

Parent: Format:Mach-O. Related: Format:Mach-O/Load commands.

Code & repositories

  • https://github.com/apple-oss-distributions/dyld @ fd8d0c4d52320ebf64db34f3cb280310d905c5ae · license: APSL-2.0 (declared by the contributor; GitHub's detector did not recognize a license file)
    dyld source: mach_o/ExportsTrie.cpp (export trie node decoding), include/mach-o/fixup-chains.h, cache_builder/SubCache.cpp
    Tested on: source read, not run: source read, not run: source read only · checked 2026-10-19; last activity 2026-06-18