Editing Mach-O (section)

=== __LINKEDIT Symbol table ===

Mach-O application files and link libraries both have a symbol table command.

The command is read as follows:

{|class="wikitable"
|+ Load command (Symbol table)
|-
! Offset !! Bytes !! Description
|-
| 0 || 4 || {{code|0x00000002}} (Command type)
|-
| 4 || 4 || Command size (always 24)
|-
| 8 || 4 || Symbols (file offset relative to Mach-O header)
|-
| 12 || 4 || Number of Symbols
|-
| 16 || 4 || String table (file offset relative to Mach-O header)
|-
| 20 || 4 || String table size
|}

The symbol file offset is the offset relative to the start of the Mach-O header to where the symbol entries begins in the file. The number of symbol entries marks the end of the symbol table.

A symbol has a name offset that should never exceed the string table size. Each symbol name offset is added to the string table file offset which in turn is relative to the start of the Mach-O header. Each symbol name ends with a {{code|0x00}} byte value.

The symbol address uses a 32-bit address for 32-bit Mach-O files and a 64-bit address for 64-bit Mach-O files.

Each symbol entry is read as follows:

{|class="wikitable"
|+ Symbol32/64
|-
! Offset(32-bit) !! Bytes(32-bit) !! Offset(64-bit) !! Bytes(64-bit) !! Description
|-
| 0 || 4 || 0 || 4 || Name offset
|-
| 4 || 1 || 4 || 1 || Symbol type
|-
| 5 || 1 || 5 || 1 || Section number 0 to 255
|-
| 6 || 2 || 6 || 2 || Data info (library ordinal number)
|-
| 8 || 4 || 8 || 8 || Symbol address
|}

The symbol name offset is added to the string table offset. The last text character byte is read as {{code|0x00}}.

The symbol type value has multiple adjustable sections in binary. The symbol type is read as follows:

{|class="wikitable"
|+ Symbol type sections
|-
! Binary digits !! Description
|-
| {{code|???xxxxx}} || Local debugging symbols
|-
| {{code|xxxx???x}} || Symbol address type
|-
| {{code|xxx?xxx?}} || Symbol visibility setting flags
|}

The digits marked {{code|?}} are used for the specified purpose; the digits marked {{code|x}} are used for other purposes.

The three first binary digits are symbols that locate to function names relative to compiled machine code instructions and line numbers by address location. This information allows us to generate line numbers to the location your code crashed. Local debugging symbols are only useful when designing the application, but are not needed to run the application.

{|class="wikitable"
|+ Symbol address type
|-
! Binary value !! Description
|-
| {{code|xxxx000x}} || Symbol undefined
|-
| {{code|xxxx001x}} || Symbol absolute
|-
| {{code|xxxx101x}} || Symbol indirect
|-
| {{code|xxxx110x}} || Symbol prebound undefined
|-
| {{code|xxxx111x}} || Symbol defined in section number
|}

The following flag settings:

{|class="wikitable"
|+ Symbol visibility setting flags
|-
! Binary value !! Description
|-
| {{code|xxx1xxx0}} || Private symbol
|-
| {{code|xxx0xxx1}} || External symbol
|}

External symbols are symbols that have a defined address in the link library and can be copied to an undefined symbol in a Mach-O application. The address location is added to the  link library base address.

A private symbol is skipped even if it matches the name of an undefined symbol. A private and external symbol can only be set to an undefined symbol if it is in the same file.

After the symbol type is the section number the symbol exists in. The section number is a byte value (0 to 255). You can add more sections than 255 using segment load commands, but the section numbers are then outside the byte value range used in the symbol entries.

A section number of zero means the symbol is not in any section of the application, the address location of the symbol is zero, and is set as Undefined. A matching External symbol name has to be found in a link library that has the symbol address.

The data info field contains the link library ordinal number that the external symbol can be found in with the matching symbol name. The data info bit field breaks down as follows:

{|class="wikitable"
|+ Symbol data info sections
|-
! Binary digits !! Description
|-
| {{code|????????xxxxxxxx}} || Library ordinal number 0 to 255
|-
| {{code|xxxxxxxx????xxxx}} || Dynamic loader flag options
|-
| {{code|xxxxxxxxxxxx????}} || Address type option
|}

The library ordinal number is set zero if the symbol is an external symbol, or exists in the current file. Only undefined symbols use the data info section to specify a library ordinal number and linker options.

The dynamic loader flag options are as follows:

{|class="wikitable"
|+ Dynamic loader flag options
|-
! Binary digits !! Description
|-
| {{code|xxxxxxxx0001xxxx}} || Must be set for any defined symbol that is referenced by dynamic-loader.
|-
| {{code|xxxxxxxx0010xxxx}} || Used by the dynamic linker at runtime.
|-
| {{code|xxxxxxxx0100xxxx}} || If the dynamic linker cannot find a definition for this symbol, it sets the address of this symbol to 0.
|-
| {{code|xxxxxxxx1000xxxx}} || If the static linker or the dynamic linker finds another definition for this symbol, the definition is ignored.
|}

Any of the 4 options that apply can be set.

The address type option values are as follows:

{|class="wikitable"
|+ Dynamic loader address options
|-
! Binary digits !! Description
|-
| {{code|xxxxxxxxxxxx0000}} || Non Lazy loaded pointer method call
|-
| {{code|xxxxxxxxxxxx0001}} || Lazy loaded pointer method call
|-
| {{code|xxxxxxxxxxxx0010}} || Method call defined in this library/program
|-
| {{code|xxxxxxxxxxxx0011}} || Private Method call defined in this library/program
|-
| {{code|xxxxxxxxxxxx0100}} || Private Non Lazy loaded pointer method call
|-
| {{code|xxxxxxxxxxxx0101}} || Private Lazy loaded pointer method call
|}

Only one address type value can be set by value. A Pointer is a value that is read by the program machine code to call a method from another binary file. Private means other programs are not intended to be able to read or call the function/methods other than the binary itself. Lazy means the pointer locates to the dyld_stub_binder which looks for the symbol then calls the method, then replaces the dyld_stub_binder location with the location to the symbol. Any more calls done from machine code in the binary will now locate to the address of the symbol and will not call the dyld_stub_binder.

==== Symbol table organization ====

The symbol table entries are all stored in order by type. The first symbols that are read are local debug symbols if any, then private symbols, then external symbols, and finally the undefined symbols that link to another binary symbol table containing the external symbol address in another Mach-O binary.

The symbol table information load command {{code|0x0000000B}} always exists if there is a symbol table section in the Mach-O binary. The command tells the linker how many local symbols there are, how many private, how many external, and how many undefined. It also identifies the symbol number they start at. The symbol table information is used before reading the symbol entries by the dynamic linker as it tells the dynamic linker where to start reading the symbols to load in undefined symbols and where to start reading to look for matching external symbols without having to read all the symbol entries.

The order the symbols go in the symbol section should never be altered as each symbol is numbered from zero up. The symbol table information command uses the symbol numbers for the order to load the undefined symbols into the stubs and pointer sections. Altering the order would cause the wrong method to be called during machine code execution.