Crashpad

Public Member Functions | Static Public Member Functions | List of all members
crashpad::MachOImageSegmentReader Class Reference

A reader for `LC_SEGMENT` or `LC_SEGMENT_64` load commands in Mach-O images mapped into another process. More...

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

## Public Member Functions
bool | Initialize (ProcessReader *process_reader, mach_vm_address_t load_command_address, const std::string &load_command_info, const std::string &module_name, uint32_t file_type)
| Reads the segment load command from another process. More...
void | SetSlide (mach_vm_size_t slide)
| Sets the image’s slide value. More...
std::string | Name () const
| Returns the segment’s name. More...
mach_vm_address_t | Address () const
mach_vm_address_t | Size () const
mach_vm_address_t | vmaddr () const
| The segment’s preferred load address. More...
mach_vm_size_t | vmsize () const
| Returns the segment’s size as mapped into memory. More...
mach_vm_size_t | fileoff () const
| Returns the file offset of the mapped segment in the file from which it was mapped. More...
uint32_t | nsects () const
| Returns the number of sections in the segment. More...
const process_types::section * | GetSectionByName (const std::string &section_name, mach_vm_address_t *address) const
| Obtain section information by section name. More...
const process_types::section * | GetSectionAtIndex (size_t index, mach_vm_address_t *address) const
| Obtain section information by section index. More...
bool | SegmentSlides () const

## Static Public Member Functions
static std::string | SegmentNameString (const char *segment_name_c)
| Returns a segment name string. More...
static std::string | SectionNameString (const char *section_name_c)
| Returns a section name string. More...
static std::string | SegmentAndSectionNameString (const char *segment_name_c, const char *section_name_c)
| Returns a segment and section name string. More...

## Detailed Description

A reader for `LC_SEGMENT` or `LC_SEGMENT_64` load commands in Mach-O images mapped into another process.

This class is capable of reading both `LC_SEGMENT` and `LC_SEGMENT_64` based on the bitness of the remote process.

A MachOImageSegmentReader will normally be instantiated by a MachOImageReader.

## Member Function Documentation

## ◆ Address()

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

Returns
  The segment’s actual load address in memory, adjusted for any “slide”.

Note
  For the segment’s preferred load address, not adjusted for slide, use vmaddr().

## ◆ fileoff()

mach_vm_size_t crashpad::MachOImageSegmentReader::fileoff | ( |  | ) | const
| inline

Returns the file offset of the mapped segment in the file from which it was mapped.

The file offset is the difference between the beginning of the `mach_header` or `mach_header_64` and the beginning of the segment’s mapped region. For segments that are not mapped from a file (such as `__PAGEZERO` segments), this will be `0`.

## ◆ GetSectionAtIndex()

const process_types::section * crashpad::MachOImageSegmentReader::GetSectionAtIndex | ( | size_t | index,
|  | 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 command. Unlike MachOImageReader::GetSectionAtIndex(), this is a 0-based index. This parameter must be in the range of valid indices aas reported by nsects().
  [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, execution is aborted. The caller does not take ownership; the lifetime of the returned object is scoped to the lifetime of this MachOImageSegmentReader object.

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.
  Unlike MachOImageReader::GetSectionAtIndex(), this method does not accept out-of-range values for index, and aborts execution instead of returning `nullptr` upon encountering an out-of-range value. This is because this method is expected to be used in a loop that can be limited to nsects() iterations, so an out-of-range error can be treated more harshly as a logic error, as opposed to a data error.

See also
  MachOImageReader::GetSectionAtIndex()

## ◆ GetSectionByName()

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

Obtain section information by section name.

Parameters

  [in] | section_name | The name of the section to search for, without the leading segment name. For example, use `"__text"`, not `"__TEXT,__text"` or `"__TEXT.__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 MachOImageSegmentReader object.

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.

See also
  MachOImageReader::GetSectionByName()

## ◆ Initialize()

bool crashpad::MachOImageSegmentReader::Initialize | ( | ProcessReader * | process_reader,
|  | mach_vm_address_t | load_command_address,
|  | const std::string & | load_command_info,
|  | const std::string & | module_name,
|  | uint32_t | file_type
| ) |  |

Reads the segment load command 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] | load_command_address | The address, in the remote process’ address space, where the `LC_SEGMENT` or `LC_SEGMENT_64` load command to be read is located. This address is determined by a Mach-O image reader, such as MachOImageReader, as it walks Mach-O load commands.
  [in] | load_command_info | A string to be used in logged messages. This string is for diagnostic purposes only, and may be empty.
  [in] | module_name | The path used to load the module. This string is used to relax otherwise strict parsing rules for common modules with known defects.
  [in] | file_type | The module’s Mach-O file type. This is used to relax otherwise strict parsing rules for common modules with known defects.

Returns
  `true` if the load command was read successfully. `false` otherwise, with an appropriate message logged.

## ◆ Name()

std::string crashpad::MachOImageSegmentReader::Name | ( |  | ) | const

Returns the segment’s name.

The segment’s name is taken from the load command’s `segname` field. Common segment names are `"__TEXT"`, `"__DATA"`, and `"__LINKEDIT"`. Symbolic constants for these common names are defined in `<mach-o/loader.h>`.

## ◆ nsects()

uint32_t crashpad::MachOImageSegmentReader::nsects | ( |  | ) | const
| inline

Returns the number of sections in the segment.

This will return `0` for a segment without any sections, typical for `__PAGEZERO` and `__LINKEDIT` segments.

Although the Mach-O file format uses a `uint32_t` for this field, there is an overall limit of 255 sections in an entire Mach-O image file (not just in a single segment) imposed by the symbol table format. Symbols will not be able to reference anything in a section beyond the first 255 in a Mach-O image file.

## ◆ SectionNameString()

std::string crashpad::MachOImageSegmentReader::SectionNameString | ( | const char * | section_name_c | ) |
| static

Returns a section name string.

Section names may be 16 characters long, and are not necessarily `NUL`-terminated. This function will return a section name based on up to the first 16 characters found at section_name_c.

## ◆ SegmentAndSectionNameString()

std::string crashpad::MachOImageSegmentReader::SegmentAndSectionNameString | ( | const char * | segment_name_c,
|  | const char * | section_name_c
| ) |  |
| static

Returns a segment and section name string.

A segment and section name string is composed of a segment name string (see SegmentNameString()) and a section name string (see SectionNameString()) separated by a comma. An example is `"__TEXT,__text"`.

## ◆ SegmentNameString()

std::string crashpad::MachOImageSegmentReader::SegmentNameString | ( | const char * | segment_name_c | ) |
| static

Returns a segment name string.

Segment names may be 16 characters long, and are not necessarily `NUL`-terminated. This function will return a segment name based on up to the first 16 characters found at segment_name_c.

## ◆ SegmentSlides()

bool crashpad::MachOImageSegmentReader::SegmentSlides | ( |  | ) | const

Returns whether the segment slides.

Most segments slide, but the `__PAGEZERO` segment does not, it grows instead. This method identifies non-sliding segments in the same way that the kernel does.

## ◆ SetSlide()

void crashpad::MachOImageSegmentReader::SetSlide | ( | mach_vm_size_t | slide | ) |

Sets the image’s slide value.

This method must only be called once on an object, after Initialize() is called successfully. It must be called before Address(), Size(), GetSectionByName(), or GetSectionAtIndex() can be called.

This method is provided because slide is a property of the image that cannot be determined until at least some segments have been read. As such, it is not necessarily known at the time that Initialize() is called.

## ◆ Size()

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

Returns
  The segment’s actual size address in memory, adjusted for any growth in the case of a nonsliding segment.

Note
  For the segment’s preferred size, not adjusted for growth, use vmsize().

## ◆ vmaddr()

mach_vm_address_t crashpad::MachOImageSegmentReader::vmaddr | ( |  | ) | const
| inline

The segment’s preferred load address.

Returns
  The segment’s preferred load address as stored in the Mach-O file.

Note
  This value is not adjusted for any “slide” that may have occurred when the image was loaded. Use Address() for a value adjusted for slide.

See also
  MachOImageReader::GetSegmentByName()

## ◆ vmsize()

mach_vm_size_t crashpad::MachOImageSegmentReader::vmsize | ( |  | ) | const
| inline

Returns the segment’s size as mapped into memory.

Note
  For non-sliding segments, this value is not adjusted for any growth that may have occurred when the image was loaded. Use Size() for a value adjusted for growth.

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

- snapshot/mac/mach_o_image_segment_reader.h
- snapshot/mac/mach_o_image_segment_reader.cc