core.sys.darwin.mach.nlist

struct nlist_64;

An entry in a list of symbols for 64-bits architectures

Said symbols can be used to describe many different type of data, including STABS debug infos. Introduced in MacOSX 10.8 SDK.

See Also:

https://developer.apple.com/documentation/kernel/nlist_64

alias n_un = n_strx;

Compatibility alias, as n_strx is in an union in C code

uint n_strx;

Index of this symbol's name into the string table

All names are stored as NUL-terminated strings into the string table. For historical reason, the very first entry into the string table is 0, hence all non-NULL names have an index > 0.

ubyte n_type;

A bitfield that describes the type of this symbol

In reality, this describes 4 fields:

• N_STAB (top 3 bits)
• N_PEXT (next 1 bit)
• N_TYPE (next 3 bits)
• N_EXT (last 1 bit)

The enum values N_STAB, N_PEXT, N_TYPE, and N_EXT should be used as masks to check which type this nlist_64 actually is.

ubyte n_sect;

Section number (note that 0 means NO_SECT)

N_STAB

If any of these bits set, a symbolic debugging entry

Only symbolic debugging entries have some of the N_STAB bits set and if any of these bits are set then it is a symbolic debugging entry (a stab). In which case then the values of the n_type field (the entire field) are given in

N_PEXT

Private external symbol bit

N_TYPE

Mask for the type bits

N_EXT

External symbol bit, set for external symbols

N_UNDF

Undefined (n_sect == NO_SECT)

N_ABS

Absolute (n_sect == NO_SECT)

N_SECT

Defined in section number nlist_64.n_sect

N_PBUD

Prebound undefined (defined in a dylib)

N_INDR

Indirect symbol

If the type is N_INDR then the symbol is defined to be the same as another symbol. In this case the n_value field is an index into the string table of the other symbol's name. When the other symbol is defined then they both take on the defined type and value.

enum int NO_SECT;

Symbol is not in any section

If the type is N_SECT then the n_sect field contains an ordinal of the section the symbol is defined in. The sections are numbered from 1 and refer to sections in order they appear in the load commands for the file they are in. This means the same ordinal may very well refer to different sections in different files.

The n_value field for all symbol table entries (including N_STAB's) gets updated by the link editor based on the value of it's n_sect field and where the section n_sect references gets relocated. If the value of the n_sect field is NO_SECT then it's n_value field is not changed by the link editor.

enum int MAX_SECT;

Maximum number of sections: 1 thru 255 inclusive

pure nothrow @nogc @safe ubyte GET_COMM_ALIGN(uint n_desc);

pure nothrow @nogc ref @safe ushort SET_COMM_ALIGN(return ref ushort n_desc, size_t wanted_align);

Common symbols are represented by undefined (N_UNDF) external (N_EXT) types who's values (n_value) are non-zero. In which case the value of the n_value field is the size (in bytes) of the common symbol. The n_sect field is set to NO_SECT. The alignment of a common symbol may be set as a power of 2 between 2^1 and 2^15 as part of the n_desc field using the macros below. If the alignment is not set (a value of zero) then natural alignment based on the size is used.

REFERENCE_TYPE

Reference type bits of the n_desc field of undefined symbols

REFERENCE_FLAG_UNDEFINED_NON_LAZY

REFERENCE_FLAG_UNDEFINED_LAZY

REFERENCE_FLAG_DEFINED

REFERENCE_FLAG_PRIVATE_DEFINED

REFERENCE_FLAG_PRIVATE_UNDEFINED_NON_LAZY

REFERENCE_FLAG_PRIVATE_UNDEFINED_LAZY

types of references

REFERENCED_DYNAMICALLY

To simplify stripping of objects that use are used with the dynamic link editor, the static link editor marks the symbols defined an object that are referenced by a dynamicly bound object (dynamic shared libraries, bundles). With this marking strip knows not to strip these symbols.

pure nothrow @nogc @safe ubyte GET_LIBRARY_ORDINAL(uint n_desc);

pure nothrow @nogc ref @safe ushort SET_LIBRARY_ORDINAL(return ref ushort n_desc, uint ordinal);

For images created by the static link editor with the -twolevel_namespace option in effect the flags field of the mach header is marked with MH_TWOLEVEL. And the binding of the undefined references of the image are determined by the static link editor. Which library an undefined symbol is bound to is recorded by the static linker in the high 8 bits of the n_desc field using the SET_LIBRARY_ORDINAL macro below. The ordinal recorded references the libraries listed in the Mach-O's LC_LOAD_DYLIB, LC_LOAD_WEAK_DYLIB, LC_REEXPORT_DYLIB, LC_LOAD_UPWARD_DYLIB, and LC_LAZY_LOAD_DYLIB, etc. load commands in the order they appear in the headers. The library ordinals start from 1. For a dynamic library that is built as a two-level namespace image the undefined references from module defined in another use the same nlist struct an in that case SELF_LIBRARY_ORDINAL is used as the library ordinal. For defined symbols in all images they also must have the library ordinal set to SELF_LIBRARY_ORDINAL. The EXECUTABLE_ORDINAL refers to the executable image for references from plugins that refer to the executable that loads them.

The DYNAMIC_LOOKUP_ORDINAL is for undefined symbols in a two-level namespace image that are looked up by the dynamic linker with flat namespace semantics. This ordinal was added as a feature in Mac OS X 10.3 by reducing the value of MAX_LIBRARY_ORDINAL by one. So it is legal for existing binaries or binaries built with older tools to have 0xfe (254) dynamic libraries. In this case the ordinal value 0xfe (254) must be treated as a library ordinal for compatibility.

N_NO_DEAD_STRIP

Symbol is not to be dead stripped

The N_NO_DEAD_STRIP bit of the n_desc field only ever appears in a relocatable .o file (MH_OBJECT filetype). And is used to indicate to the static link editor it is never to dead strip the symbol.

N_DESC_DISCARDED

Symbol is discarded

The N_DESC_DISCARDED bit of the n_desc field never appears in linked image. But is used in very rare cases by the dynamic link editor to mark an in memory symbol as discared and longer used for linking.

N_WEAK_REF

Symbol is weak referenced

The N_WEAK_REF bit of the n_desc field indicates to the dynamic linker that the undefined symbol is allowed to be missing and is to have the address of zero when missing.

N_WEAK_DEF

Coalesed symbol is a weak definition

The N_WEAK_DEF bit of the n_desc field indicates to the static and dynamic linkers that the symbol definition is weak, allowing a non-weak symbol to also be used which causes the weak definition to be discared. Currently this is only supported for symbols in coalesed sections.

N_REF_TO_WEAK

Reference to a weak symbol

The N_REF_TO_WEAK bit of the n_desc field indicates to the dynamic linker that the undefined symbol should be resolved using flat namespace searching.

N_ARM_THUMB_DEF

Symbol is a Thumb function (ARM)

The N_ARM_THUMB_DEF bit of the n_desc field indicates that the symbol is a defintion of a Thumb function.

N_SYMBOL_RESOLVER

The N_SYMBOL_RESOLVER bit of the n_desc field indicates that the that the function is actually a resolver function and should be called to get the address of the real function to use. This bit is only available in .o files (MH_OBJECT filetype)

N_ALT_ENTRY

The N_ALT_ENTRY bit of the n_desc field indicates that the symbol is pinned to the previous content.

N_COLD_FUNC

The N_COLD_FUNC bit of the n_desc field indicates that the symbol is used infrequently and the linker should order it towards the end of the section.