crashpad::MachOImageReader Class Reference

A reader for Mach-O images mapped into another process. More...

`#include "snapshot/mac/mach_o_image_reader.h"`

## Public Member Functions

bool | Initialize (ProcessReaderMac *process_reader, mach_vm_address_t address, const std::string &name)
| Reads the Mach-O image file’s load commands from another process. More...
uint32_t | FileType () const
| Returns the Mach-O file type. More...
mach_vm_address_t | Address () const
| Returns the Mach-O image’s load address. More...
mach_vm_size_t | Size () const
| Returns the mapped size of the Mach-O image’s `__TEXT` segment. More...
mach_vm_size_t | Slide () const
| Returns the Mach-O image’s “slide,” the difference between its actual load address and its preferred load address. More...
const MachOImageSegmentReader * | GetSegmentByName (const std::string &segment_name) const
| Obtain segment information by segment name. More...
const process_types::section * | GetSectionByName (const std::string &segment_name, const std::string &section_name, mach_vm_address_t *address) const
| Obtain section information by segment and section name. More...
const process_types::section * | GetSectionAtIndex (size_t index, const MachOImageSegmentReader **containing_segment, mach_vm_address_t *address) const
| Obtain section information by section index. More...
bool | LookUpExternalDefinedSymbol (const std::string &name, mach_vm_address_t *value) const
| Looks up a symbol in the image’s symbol table. More...
uint32_t | DylibVersion () const
| Returns a Mach-O dylib image’s current version. More...
uint64_t | SourceVersion () const
| Returns a Mach-O image’s source version. More...
void | UUID (crashpad::UUID *uuid) const
| Returns a Mach-O image’s UUID. More...
std::string | DylinkerName () const
| Returns the dynamic linker’s pathname. More...
bool | GetCrashpadInfo (process_types::CrashpadInfo *crashpad_info) const
| Obtains the module’s CrashpadInfo structure. More...

## Detailed Description

A reader for Mach-O images mapped into another process.

This class is capable of reading both 32-bit (`mach_header`/`MH_MAGIC`) and 64-bit (`mach_header_64`/`MH_MAGIC_64`) images based on the bitness of the remote process.

See also
  MachOImageAnnotationsReader

## Member Function Documentation

## Address()

mach_vm_address_t crashpad::MachOImageReader::Address | ( |  | ) | const

inline

Returns the Mach-O image’s load address.

This is the value passed as address to Initialize().

## DylibVersion()

uint32_t crashpad::MachOImageReader::DylibVersion | ( |  | ) | const

Returns a Mach-O dylib image’s current version.

This information comes from the `dylib_current_version` field of a dylib’s `LC_ID_DYLIB` load command. For dylibs without this load command, `0` will be returned.

This method may only be called on Mach-O images for which FileType() returns `MH_DYLIB`.

## DylinkerName()

std::string crashpad::MachOImageReader::DylinkerName | ( |  | ) | const

inline

Returns the dynamic linker’s pathname.

The dynamic linker is normally /usr/lib/dyld.

For executable images (those with file type `MH_EXECUTE`), this is the name provided in the `LC_LOAD_DYLINKER` load command, if any. For dynamic linker images (those with file type `MH_DYLINKER`), this is the name provided in the `LC_ID_DYLINKER` load command. In other cases, this will be empty.

## FileType()

uint32_t crashpad::MachOImageReader::FileType | ( |  | ) | const

inline

Returns the Mach-O file type.

This value comes from the `filetype` field of the `mach_header` or `mach_header_64`. Common values include `MH_EXECUTE`, `MH_DYLIB`, `MH_DYLINKER`, and `MH_BUNDLE`.

## GetCrashpadInfo()

bool crashpad::MachOImageReader::GetCrashpadInfo | ( | process_types::CrashpadInfo * | crashpad_info | ) | const

Obtains the module’s CrashpadInfo structure.

Returns
  `true` on success, `false` on failure. If the module does not have a `__DATA,crashpad_info` section, this will return `false` without logging any messages. Other failures will result in messages being logged.

## GetSectionAtIndex()

const process_types::section * crashpad::MachOImageReader::GetSectionAtIndex | ( | size_t | index,
|  | const MachOImageSegmentReader ** | containing_segment,
|  | mach_vm_address_t * | address
| ) |  | const

Obtain section information by section index.

Parameters

  [in] | index | The index of the section to return, in the order that it appears in the segment load commands. This is a 1-based index, matching the section number values used for `nlist::n_sect`.
  [out] | containing_segment | The segment that contains the section. This parameter can be `nullptr`. The caller does not take ownership; the lifetime of the returned object is scoped to the lifetime of this MachOImageReader object.
  [out] | address | The actual address that the section was loaded at in memory, taking any “slide” into account if the section did not load at its preferred address as stored in the Mach-O image file. This parameter can be `nullptr`.

Returns
  A pointer to the section information. If index is out of range, logs a warning and returns `nullptr`. The caller does not take ownership; the lifetime of the returned object is scoped to the lifetime of this MachOImageReader object.

No parameter is provided for the section’s size, because it can be obtained from the returned process_types::section::size field.

Note
  The process_types::section::addr field gives the section’s preferred load address as stored in the Mach-O image file, and is not adjusted for any “slide” that may have occurred when the image was loaded. Use address to obtain the section’s actual load address.
  Unlike MachOImageSegmentReader::GetSectionAtIndex(), this method accepts out-of-range values for index, and returns `nullptr` instead of aborting execution upon encountering an out-of-range value. This is because a Mach-O image file’s symbol table refers to this per-module section index, and an out-of-range index in that case should be treated as a data error (where the data is beyond this code’s control) and handled non-fatally by reporting the error to the caller.

## GetSectionByName()

const process_types::section * crashpad::MachOImageReader::GetSectionByName | ( | const std::string & | segment_name,
|  | const std::string & | section_name,
|  | mach_vm_address_t * | address
| ) |  | const

Obtain section information by segment and section name.

Parameters

  [in] | segment_name | The name of the segment to search for, for example, `"__TEXT"`.
  [in] | section_name | The name of the section within the segment to search for, for example, `"__text"`.
  [out] | address | The actual address that the section was loaded at in memory, taking any “slide” into account if the section did not load at its preferred address as stored in the Mach-O image file. This parameter can be `nullptr`.

Returns
  A pointer to the section information if it was found, or `nullptr` if it was not found. The caller does not take ownership; the lifetime of the returned object is scoped to the lifetime of this MachOImageReader object.

No parameter is provided for the section’s size, because it can be obtained from the returned process_types::section::size field.

Note
  The process_types::section::addr field gives the section’s preferred load address as stored in the Mach-O image file, and is not adjusted for any “slide” that may have occurred when the image was loaded. Use address to obtain the section’s actual load address.

## GetSegmentByName()

const MachOImageSegmentReader * crashpad::MachOImageReader::GetSegmentByName | ( | const std::string & | segment_name | ) | const

Obtain segment information by segment name.

Parameters

  [in] | segment_name | The name of the segment to search for, for example, `"__TEXT"`.

Returns
  A pointer to the segment information if it was found, or `nullptr` if it was not found. The caller does not take ownership; the lifetime of the returned object is scoped to the lifetime of this MachOImageReader object.

## Initialize()

bool crashpad::MachOImageReader::Initialize | ( | ProcessReaderMac * | process_reader,
|  | mach_vm_address_t | address,
|  | const std::string & | name
| ) |  |

Reads the Mach-O image file’s load commands from another process.

This method must only be called once on an object. This method must be called successfully before any other method in this class may be called.

Parameters

  [in] | process_reader | The reader for the remote process.
  [in] | address | The address, in the remote process’ address space, where the `mach_header` or `mach_header_64` at the beginning of the image to be read is located. This address can be determined by reading the remote process’ dyld information (see snapshot/mac/process_types/dyld_images.proctype).
  [in] | name | The module’s name, a string to be used in logged messages. This string is for diagnostic purposes and to relax otherwise strict parsing rules for common modules with known defects.

Returns
  `true` if the image was read successfully, including all load commands. `false` otherwise, with an appropriate message logged.

## LookUpExternalDefinedSymbol()

bool crashpad::MachOImageReader::LookUpExternalDefinedSymbol | ( | const std::string & | name,
|  | mach_vm_address_t * | value
| ) |  | const

Looks up a symbol in the image’s symbol table.

This method is capable of locating external defined symbols. Specifically, this method can look up symbols that have these charcteristics:

- `N_STAB` (debugging) and `N_PEXT` (private external) must not be set.
- `N_EXT` (external) must be set.
- The type must be `N_ABS` (absolute) or `N_SECT` (defined in section).

`N_INDR` (indirect), `N_UNDF` (undefined), and `N_PBUD` (prebound undefined) symbols cannot be located through this mechanism.

Parameters

  [in] | name | The name of the symbol to look up, “mangled” or “decorated” appropriately. For example, use `"_main"` to look up the symbol for the C `main()` function, and use `"__Z4Funcv"` to look up the symbol for the C++ `Func()` function. Contrary to `dlsym()`, the leading underscore must not be stripped when using this interface.
  [out] | value | If the lookup was successful, this will be set to the value of the symbol, adjusted for any “slide” as needed. The value can be used as an address in the remote process’ address space where the pointee of the symbol exists in memory.

Returns
  `true` if the symbol lookup was successful and the symbol was found. `false` otherwise, including error conditions (for which a warning message will be logged), modules without symbol tables, and symbol names not found in the symbol table.

Note
  Symbol values returned via this interface are adjusted for “slide” as appropriate, in contrast to the underlying implementation, MachOImageSymbolTableReader::LookUpExternalDefinedSymbol().

Warning
  Symbols that are resolved by running symbol resolvers (`.symbol_resolver`) are not properly handled by this interface. The address of the symbol resolver is returned because that’s what shows up in the symbol table, rather than the effective address of the resolved symbol as used by dyld after running the resolver. The only way to detect this situation would be to read the `LC_DYLD_INFO` or `LC_DYLD_INFO_ONLY` load command if present and looking for the `EXPORT_SYMBOL_FLAGS_STUB_AND_RESOLVER` flag, but that would just be able to detect symbols with a resolver, it would not be able to resolve them from out-of-process, so it’s not currently done.

## Size()

mach_vm_size_t crashpad::MachOImageReader::Size | ( |  | ) | const

inline

Returns the mapped size of the Mach-O image’s `__TEXT` segment.

Note that this is returns only the size of the `__TEXT` segment, not of any other segment. This is because the interface only allows one load address and size to be reported, but Mach-O image files may consist of multiple discontiguous segments. By convention, the `__TEXT` segment is always mapped at the beginning of a Mach-O image file, and it is the most useful for the expected intended purpose of collecting data to obtain stack backtraces. The implementation insists during initialization that the `__TEXT` segment be mapped at the beginning of the file.

In practice, discontiguous segments are only found for images that have loaded out of the dyld shared cache, but the `__TEXT` segment’s size is returned for modules that loaded with contiguous segments as well for consistency.

## Slide()

mach_vm_size_t crashpad::MachOImageReader::Slide | ( |  | ) | const

inline

Returns the Mach-O image’s “slide,” the difference between its actual load address and its preferred load address.

“Slide” is computed by subtracting the `__TEXT` segment’s preferred load address from its actual load address. It will be reported as a positive offset when the actual load address is greater than the preferred load address. The preferred load address is taken to be the segment’s reported `vmaddr` value.

## SourceVersion()

uint64_t crashpad::MachOImageReader::SourceVersion | ( |  | ) | const

inline

Returns a Mach-O image’s source version.

This information comes from a Mach-O image’s `LC_SOURCE_VERSION` load command. For Mach-O images without this load command, `0` will be returned.

## UUID()

void crashpad::MachOImageReader::UUID | ( | crashpad::UUID * | uuid | ) | const

Returns a Mach-O image’s UUID.

This information comes from a Mach-O image’s `LC_UUID` load command. For Mach-O images without this load command, a zeroed-out UUID value will be returned.

The documentation for this class was generated from the following files:

- snapshot/mac/mach_o_image_reader.h
- snapshot/mac/mach_o_image_reader.cc