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

Public Member Functions

Detailed Description

Member Function Documentation

◆ Address()

◆ DylibVersion()

◆ DylinkerName()

◆ FileType()

◆ GetCrashpadInfo()

◆ GetSectionAtIndex()

◆ GetSectionByName()

◆ GetSegmentByName()

◆ Initialize()

◆ LookUpExternalDefinedSymbol()

◆ Size()

◆ Slide()

◆ SourceVersion()

◆ UUID()