reverse-engineering-anything/docs/specs/native/native-initializers/spec.md

# Native initializer and finalizer functions

## Problem and outcome

Analysts reviewing a native image need the functions it declares to run before
`main` and at exit, without executing it or opening a disassembler provider.
`inspect_native_initializers` / `inspect-native-initializers` lists the
initializer and finalizer slots of one local ELF or Mach-O image, with each
slot's location, resolved target and how that target was obtained. The
[user guide](../../../guides/native/native-initializers.md) documents the result.

## Requirements

- Accept one local ELF32, ELF64, thin Mach-O or universal Mach-O image. A
  universal Mach-O requires `architecture` to select one slice; other inputs
  reject it. The CLI resolves relative paths; MCP requires an absolute path.
- ELF sources, in order: `DT_PREINIT_ARRAY`, `DT_INIT`, `DT_INIT_ARRAY`, legacy
  `.ctors`, `DT_FINI`, `DT_FINI_ARRAY`, legacy `.dtors`. Without the dynamic tag,
  fall back to `SHT_*_ARRAY` sections or `.init_array*` / `.fini_array*` /
  `.preinit_array` names. Mach-O sources are sections typed
  `S_MOD_INIT_FUNC_POINTERS`, `S_INIT_FUNC_OFFSETS` and
  `S_MOD_TERM_FUNC_POINTERS`.
- Resolve values through RELATIVE and RELR dynamic relocations, then section
  REL / RELA records for slots no dynamic relocation covers, then the stored
  word when relocation coverage is known. Mach-O uses chained-fixup rebases,
  `LC_DYLD_INFO` rebases (reported separately), `MH_OBJECT` section
  relocations and `__init_offsets` image-base offsets. Anything else is
  `unresolved`, never a stored zero.
- Relocation coverage is per slot. A slot that a dynamic or section relocation
  only partly overwrites or writes more than once is `unresolved`, and so is an
  absolute relocation against an `STT_GNU_IFUNC` resolver. On 32-bit ARM the
  Thumb bit is cleared for target section and file-offset lookup only. A slot with no
  relocation found is `unresolved` when a dynamic table, or a section table
  that could reach it, was not fully read; such a `.ctors` slot is not dropped
  as a sentinel. A `COPY` relocation covers the bytes of its symbol's size and
  a TLS descriptor two words. The size comes from the dynamic symbol table for
  a dynamic record and from the table's linked symbols for a section record of
  a linked image; an unread size leaves coverage unknown. A linked image's
  section record that writes memory with no file bytes covers only the slots
  it overlaps there when its extent is established, by a fixed width or a
  `COPY` size, and otherwise leaves its table not fully read. A
  linked image's non-`SHF_ALLOC` relocation sections were
  applied at link time and are not reapplied. A Mach-O stored pointer word is
  used only when no undecoded bind stream or external relocation could
  replace it.
- Relocatable objects (`ET_REL`) report section-relative offsets and say so.
- `.ctors` / `.dtors` sentinels are 0 and all ones at the image's pointer width;
  they are omitted and counted in a limitation.
- `DT_INIT` / `DT_FINI` have no slot pointer: their slot is the dynamic value
  field, and `slot_va` / `slot_section` are null when that field is outside
  every load segment.
- Names are exact untrusted file text marked `observed-untrusted`. A target is
  named only by a defined symbol whose value equals it, or by the import name
  of an unresolved symbolic relocation or chained bind. An unreadable name
  (missing string table or offset outside it) is reported as no name and makes
  the report `incomplete`.
- Bounds: 64 MiB default file budget (512 MiB maximum); 65536 slots in total;
  65536 symbols across all ELF symbol tables; 65536 symbols across all
  Mach-O `LC_SYMTAB` commands; 1048576 section relocation records across all
  relocation sections; 1024-byte names. Reaching a bound makes the report
  `incomplete` with a limitation.
- Legacy Mach-O bind lookup permits at most 4096 candidate runs per query
  and twice the file byte count across image queries. Exhaustion leaves
  affected pointers unresolved; stream parsing and slot batches yield.
- Limitations are bounded: at most 24 distinct image observations, repeated
  per-row reasons reported once with a count, and at most 40 lines in total.
- Section lookups for slot and target addresses use an index built once per
  image, so their cost does not grow with headers times slots.
- Paging uses `offset` / `limit` (default 64, maximum 4096) over a stable
  ordered index. `coverage.examined_entries` counts every slot read, including
  omitted sentinels; `total_entries` is set only when the inventory is complete.
- Malformed headers, multiple `PT_DYNAMIC` segments and truncated dynamic
  sections fail without partial success. Cancellation is honored during slot
  collection, the section relocation walk and the dynamic relocation walk,
  which yields to other work at the shared reader's step boundaries.

## Acceptance

Parser tests cover ELF64 PIE (RELA, RELR, imports, `DT_INIT` / `DT_FINI`),
ELF32 REL in-place addends, `ET_REL` section relocations and sentinels,
unsupported relocation machines, slot, symbol and relocation budgets,
over-long names, tallied repeated observations, a near-maximal section table
with a full slot budget, cancellation in the relocation walks, skipped section
relocation tables, partly overwritten slots, `COPY` and TLS descriptor extents,
section `COPY` records sized by their symbol, section records that write
memory without file bytes, retained link-time
relocations, unreadable names, Mach-O chained fixups, `LC_DYLD_INFO` rebases, 32-bit images
with undecoded binds, `MH_OBJECT` section relocations, `__init_offsets`, the
shared and repeated `LC_SYMTAB` budget, and universal slices. CLI acceptance, filesystem boundary
and MCP boundary tests exercise the public workflows and Evidence output.

## Out of scope

Executing the image or proving that a listed address runs; runtime ordering
(file order is reported); disassembling initializer bodies; PE/COFF TLS
callbacks; Android packed relocations and machines other than x86-64, i386,
AArch64 and 32-bit ARM for relocation decoding; Mach-O fixup decoding for
images other than little-endian 64-bit arm64 and x86-64, and legacy
`LC_DYSYMTAB` external relocations.