Crashpad
Public Member Functions | List of all members
crashpad::ProcessSnapshotMac Class Referencefinal

A ProcessSnapshot of a running (or crashed) process running on a macOS system. More...

#include "snapshot/mac/process_snapshot_mac.h"

Inheritance diagram for crashpad::ProcessSnapshotMac:
crashpad::ProcessSnapshot

Public Member Functions

bool Initialize (task_t task)
 Initializes the object. More...
 
bool InitializeException (exception_behavior_t behavior, thread_t exception_thread, exception_type_t exception, const mach_exception_data_type_t *code, mach_msg_type_number_t code_count, thread_state_flavor_t flavor, ConstThreadState state, mach_msg_type_number_t state_count)
 Initializes the object’s exception. More...
 
void SetReportID (const UUID &report_id)
 Sets the value to be returned by ReportID(). More...
 
void SetClientID (const UUID &client_id)
 Sets the value to be returned by ClientID(). More...
 
void SetAnnotationsSimpleMap (const std::map< std::string, std::string > &annotations_simple_map)
 Sets the value to be returned by AnnotationsSimpleMap(). More...
 
void GetCrashpadOptions (CrashpadInfoClientOptions *options)
 Returns options from CrashpadInfo structures found in modules in the process. More...
 
pid_t ProcessID () const override
 Returns the snapshot process’ process ID.
 
pid_t ParentProcessID () const override
 Returns the snapshot process’ parent process’ process ID.
 
void SnapshotTime (timeval *snapshot_time) const override
 Returns the time that the snapshot was taken in snapshot_time. More...
 
void ProcessStartTime (timeval *start_time) const override
 Returns the time that the snapshot process was started in start_time. More...
 
void ProcessCPUTimes (timeval *user_time, timeval *system_time) const override
 Returns the snapshot process’ CPU usage times in user_time and system_time. More...
 
void ReportID (UUID *report_id) const override
 Returns a UUID identifying the event that the snapshot describes. More...
 
void ClientID (UUID *client_id) const override
 Returns a UUID identifying the client that the snapshot represents. More...
 
const std::map< std::string, std::string > & AnnotationsSimpleMap () const override
 Returns key-value string annotations recorded for the process, system, or snapshot producer. More...
 
const SystemSnapshotSystem () const override
 Returns a SystemSnapshot reflecting the characteristics of the system that ran the snapshot process at the time of the snapshot. More...
 
std::vector< const ThreadSnapshot * > Threads () const override
 Returns ThreadSnapshot objects reflecting the threads (lightweight processes) existing in the snapshot process at the time of the snapshot. More...
 
std::vector< const ModuleSnapshot * > Modules () const override
 Returns ModuleSnapshot objects reflecting the code modules (binary images) loaded into the snapshot process at the time of the snapshot. More...
 
std::vector< UnloadedModuleSnapshotUnloadedModules () const override
 Returns UnloadedModuleSnapshot objects reflecting the code modules the were recorded as unloaded at the time of the snapshot. More...
 
const ExceptionSnapshotException () const override
 Returns an ExceptionSnapshot reflecting the exception that the snapshot process sustained to trigger the snapshot being taken. More...
 
std::vector< const MemoryMapRegionSnapshot * > MemoryMap () const override
 Returns MemoryMapRegionSnapshot objects reflecting the regions of the memory map in the snapshot process at the time of the snapshot. More...
 
std::vector< HandleSnapshotHandles () const override
 Returns HandleSnapshot objects reflecting the open handles in the snapshot process at the time of the snapshot. More...
 
std::vector< const MemorySnapshot * > ExtraMemory () const override
 Returns a vector of additional memory blocks that should be included in a minidump. More...
 
const ProcessMemoryMemory () const override
 Returns a ProcessMemory object that allows accessing the process' memory directly. More...
 

Detailed Description

A ProcessSnapshot of a running (or crashed) process running on a macOS system.

Member Function Documentation

◆ AnnotationsSimpleMap()

const std::map< std::string, std::string > & crashpad::ProcessSnapshotMac::AnnotationsSimpleMap ( ) const
overridevirtual

Returns key-value string annotations recorded for the process, system, or snapshot producer.

This method retrieves annotations recorded for a process. These annotations are intended for diagnostic use, including crash analysis. “Simple annotations” are structured as a sequence of key-value pairs, where all keys and values are strings. These are referred to in Chrome as “crash keys.”

Annotations stored here may reflect the process, system, or snapshot producer. Most annotations not under the client’s direct control will be retrievable by this method. For clients such as Chrome, this includes the product name and version.

Additional per-module annotations may be obtained by calling ModuleSnapshot::AnnotationsSimpleMap().

Implements crashpad::ProcessSnapshot.

◆ ClientID()

void crashpad::ProcessSnapshotMac::ClientID ( UUID client_id) const
overridevirtual

Returns a UUID identifying the client that the snapshot represents.

Client identification is within the scope of the application, but it is expected that the identifier will be unique for an instance of Crashpad monitoring an application or set of applications for a user. The identifier shall remain stable over time.

If no identifier is available, this field will contain zeroes.

Implements crashpad::ProcessSnapshot.

◆ Exception()

const ExceptionSnapshot * crashpad::ProcessSnapshotMac::Exception ( ) const
overridevirtual

Returns an ExceptionSnapshot reflecting the exception that the snapshot process sustained to trigger the snapshot being taken.

Returns
An ExceptionSnapshot object. The caller does not take ownership of this object, it is scoped to the lifetime of the ProcessSnapshot object that it was obtained from. If the snapshot is not a result of an exception, returns nullptr.

Implements crashpad::ProcessSnapshot.

◆ ExtraMemory()

std::vector< const MemorySnapshot * > crashpad::ProcessSnapshotMac::ExtraMemory ( ) const
overridevirtual

Returns a vector of additional memory blocks that should be included in a minidump.

Returns
An vector of MemorySnapshot objects that will be included in the crash dump. The caller does not take ownership of these objects, they are scoped to the lifetime of the ProcessSnapshot object that they were obtained from.

Implements crashpad::ProcessSnapshot.

◆ GetCrashpadOptions()

void crashpad::ProcessSnapshotMac::GetCrashpadOptions ( CrashpadInfoClientOptions options)

Returns options from CrashpadInfo structures found in modules in the process.

Parameters
[out]optionsOptions set in CrashpadInfo structures in modules in the process.

◆ Handles()

std::vector< HandleSnapshot > crashpad::ProcessSnapshotMac::Handles ( ) const
overridevirtual

Returns HandleSnapshot objects reflecting the open handles in the snapshot process at the time of the snapshot.

Returns
A vector of HandleSnapshot objects.

Implements crashpad::ProcessSnapshot.

◆ Initialize()

bool crashpad::ProcessSnapshotMac::Initialize ( task_t  task)

Initializes the object.

Parameters
[in]taskThe task to create a snapshot from.
Returns
true if the snapshot could be created, false otherwise with an appropriate message logged.

◆ InitializeException()

bool crashpad::ProcessSnapshotMac::InitializeException ( exception_behavior_t  behavior,
thread_t  exception_thread,
exception_type_t  exception,
const mach_exception_data_type_t *  code,
mach_msg_type_number_t  code_count,
thread_state_flavor_t  flavor,
ConstThreadState  state,
mach_msg_type_number_t  state_count 
)

Initializes the object’s exception.

This populates the data to be returned by Exception(). The parameters may be passed directly through from a Mach exception handler.

This method must not be called until after a successful call to Initialize().

Returns
true if the exception information could be initialized, false otherwise with an appropriate message logged. When this method returns false, the ProcessSnapshotMac object’s validity remains unchanged.

◆ Memory()

const ProcessMemory * crashpad::ProcessSnapshotMac::Memory ( ) const
overridevirtual

Returns a ProcessMemory object that allows accessing the process' memory directly.

Returns
A ProcessMemory object. The caller does not take ownership of this object, it is scoped to the lifetime of the ProcessSnapshot object that it was obtained from.

Implements crashpad::ProcessSnapshot.

◆ MemoryMap()

std::vector< const MemoryMapRegionSnapshot * > crashpad::ProcessSnapshotMac::MemoryMap ( ) const
overridevirtual

Returns MemoryMapRegionSnapshot objects reflecting the regions of the memory map in the snapshot process at the time of the snapshot.

Returns
A vector of MemoryMapRegionSnapshot objects. The caller does not take ownership of these objects, they are scoped to the lifetime of the ProcessSnapshot object that they were obtained from.

Implements crashpad::ProcessSnapshot.

◆ Modules()

std::vector< const ModuleSnapshot * > crashpad::ProcessSnapshotMac::Modules ( ) const
overridevirtual

Returns ModuleSnapshot objects reflecting the code modules (binary images) loaded into the snapshot process at the time of the snapshot.

Returns
A vector of ModuleSnapshot objects. The caller does not take ownership of these objects, they are scoped to the lifetime of the ProcessSnapshot object that they were obtained from.

Implements crashpad::ProcessSnapshot.

◆ ProcessCPUTimes()

void crashpad::ProcessSnapshotMac::ProcessCPUTimes ( timeval *  user_time,
timeval *  system_time 
) const
overridevirtual

Returns the snapshot process’ CPU usage times in user_time and system_time.

Parameters
[out]user_timeThe time that the process has spent executing in user mode.
[out]system_timeThe time that the process has spent executing in system (kernel) mode.

Implements crashpad::ProcessSnapshot.

◆ ProcessStartTime()

void crashpad::ProcessSnapshotMac::ProcessStartTime ( timeval *  start_time) const
overridevirtual

Returns the time that the snapshot process was started in start_time.

Normally, process uptime in wall clock time can be computed as SnapshotTime()ProcessStartTime(), but this cannot be guaranteed in cases where the real-time clock has been set during the snapshot process’ lifetime.

Parameters
[out]start_timeThe time that the process was started.

Implements crashpad::ProcessSnapshot.

◆ ReportID()

void crashpad::ProcessSnapshotMac::ReportID ( UUID client_id) const
overridevirtual

Returns a UUID identifying the event that the snapshot describes.

This provides a stable identifier for a crash even as the report is converted to different formats, provided that all formats support storing a crash report ID. When a report is originally created, a report ID should be assigned. From that point on, any operations involving the same report should preserve the same report ID.

If no identifier is available, this field will contain zeroes.

Implements crashpad::ProcessSnapshot.

◆ SetAnnotationsSimpleMap()

void crashpad::ProcessSnapshotMac::SetAnnotationsSimpleMap ( const std::map< std::string, std::string > &  annotations_simple_map)
inline

Sets the value to be returned by AnnotationsSimpleMap().

On macOS, all process annotations are under the control of the snapshot producer, which may call this method to establish these annotations. Contrast this with module annotations, which are under the control of the process being snapshotted.

◆ SetClientID()

void crashpad::ProcessSnapshotMac::SetClientID ( const UUID client_id)
inline

Sets the value to be returned by ClientID().

On macOS, the client ID is under the control of the snapshot producer, which may call this method to set the client ID. If this is not done, ClientID() will return an identifier consisting entirely of zeroes.

◆ SetReportID()

void crashpad::ProcessSnapshotMac::SetReportID ( const UUID report_id)
inline

Sets the value to be returned by ReportID().

On macOS, the crash report ID is under the control of the snapshot producer, which may call this method to set the report ID. If this is not done, ReportID() will return an identifier consisting entirely of zeroes.

◆ SnapshotTime()

void crashpad::ProcessSnapshotMac::SnapshotTime ( timeval *  snapshot_time) const
overridevirtual

Returns the time that the snapshot was taken in snapshot_time.

Parameters
[out]snapshot_timeThe time that the snapshot was taken. This is distinct from the time that a ProcessSnapshot object was created or initialized, although it may be that time for ProcessSnapshot objects representing live or recently-crashed process state.

Implements crashpad::ProcessSnapshot.

◆ System()

const SystemSnapshot * crashpad::ProcessSnapshotMac::System ( ) const
overridevirtual

Returns a SystemSnapshot reflecting the characteristics of the system that ran the snapshot process at the time of the snapshot.

Returns
A SystemSnapshot object. The caller does not take ownership of this object, it is scoped to the lifetime of the ProcessSnapshot object that it was obtained from.

Implements crashpad::ProcessSnapshot.

◆ Threads()

std::vector< const ThreadSnapshot * > crashpad::ProcessSnapshotMac::Threads ( ) const
overridevirtual

Returns ThreadSnapshot objects reflecting the threads (lightweight processes) existing in the snapshot process at the time of the snapshot.

Returns
A vector of ThreadSnapshot objects. The caller does not take ownership of these objects, they are scoped to the lifetime of the ProcessSnapshot object that they were obtained from.

Implements crashpad::ProcessSnapshot.

◆ UnloadedModules()

std::vector< UnloadedModuleSnapshot > crashpad::ProcessSnapshotMac::UnloadedModules ( ) const
overridevirtual

Returns UnloadedModuleSnapshot objects reflecting the code modules the were recorded as unloaded at the time of the snapshot.

Returns
A vector of UnloadedModuleSnapshot objects.

Implements crashpad::ProcessSnapshot.


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