crashpad::ExceptionPorts Class Reference

A better interface to *_get_exception_ports() and *_set_exception_ports(). More...

#include "util/mach/exception_ports.h"

Classes
struct	ExceptionHandler
	Information about a registered exception handler. More...
class	ExceptionHandlerVector
	Wraps std::vector<ExceptionHandler>, providing proper cleanup of the send rights contained in each element’s ExceptionHandler::port. More...

Public Types
enum	TargetType
	Various entities which can have their own exception ports set. More...

Public Member Functions
	ExceptionPorts (TargetType target_type, mach_port_t target_port)
	Constructs an interface object to get or set exception ports on a host, task, or thread port.
	ExceptionPorts (const ExceptionPorts &)=delete
ExceptionPorts &	operator= (const ExceptionPorts &)=delete
bool	GetExceptionPorts (exception_mask_t mask, ExceptionHandlerVector *handlers) const
	Calls *_get_exception_ports() on the target.
bool	SetExceptionPort (exception_mask_t mask, exception_handler_t port, exception_behavior_t behavior, thread_state_flavor_t flavor) const
	Calls *_set_exception_ports() on the target.
bool	SwapExceptionPorts (exception_mask_t mask, exception_handler_t new_port, exception_behavior_t new_behavior, thread_state_flavor_t new_flavor, ExceptionHandlerVector *old_handlers) const
	Calls *_swap_exception_ports() on the target.
const char *	TargetTypeName () const
	Returns a string identifying the target type.

Detailed Description

A better interface to *_get_exception_ports() and *_set_exception_ports().

The same generic interface can be used to operate on host, task, and thread exception ports. The “get” interface is superior to the system’s native interface because it keeps related data about a single exception handler together in one struct, rather than separating it into four parallel arrays.

Member Enumeration Documentation

TargetType

enum crashpad::ExceptionPorts::TargetType

Various entities which can have their own exception ports set.

Enumerator
kTargetTypeHost	The host exception target. host_get_exception_ports() and host_set_exception_ports() will be used. If no target port is explicitly provided, mach_host_self() will be used as the target port. mach_host_self() is the only target port for this type that is expected to function properly. Note Operations on this target type are not expected to succeed as non-root, because mach_host_self() doesn’t return the privileged host_priv port to non-root users, and this is the target port that’s required for host_get_exception_ports() and host_set_exception_ports().
kTargetTypeTask	A task exception target. task_get_exception_ports() and task_set_exception_ports() will be used. If no target port is explicitly provided, mach_task_self() will be used as the target port.
kTargetTypeThread	A thread exception target. thread_get_exception_ports() and thread_set_exception_ports() will be used. If no target port is explicitly provided, mach_thread_self() will be used as the target port.

Constructor & Destructor Documentation

ExceptionPorts()

crashpad::ExceptionPorts::ExceptionPorts	(	TargetType	target_type,
		mach_port_t	target_port )

Constructs an interface object to get or set exception ports on a host, task, or thread port.

Parameters

[in]	target_type	The type of target on which the exception ports are to be get or set: kTargetTypeHost, kTargetTypeTask, or or kTargetTypeThread. The correct functions for *_get_exception_ports() and *_set_exception_ports() will be used.
[in]	target_port	The target on which to call *_get_exception_ports() or *_set_exception_ports(). The target port must be a send right to a port of the type specified in target_type. In this case, ownership of target_port is not given to the new ExceptionPorts object. target_port may also be HOST_NULL, TASK_NULL, or THREAD_NULL, in which case mach_host_self(), mach_task_self(), or mach_thread_self() will be used as the target port depending on the value of target_type. In this case, ownership of the target port will be managed appropriately for target_type.

Member Function Documentation

GetExceptionPorts()

bool crashpad::ExceptionPorts::GetExceptionPorts	(	exception_mask_t	mask,
		ExceptionHandlerVector *	handlers ) const

Calls *_get_exception_ports() on the target.

Parameters

[in]	mask	The exception mask, containing the EXC_MASK_* values to be looked up and returned in handlers.
[out]	handlers	The exception handlers registered for target_port to handle exceptions indicated in mask. If no execption port is registered for a bit in mask, handlers will not contain an entry corresponding to that bit. This is a departure from the *_get_exception_ports() functions, which may return a handler whose port is set to EXCEPTION_PORT_NULL in this case. On failure, this argument is untouched.

Returns

true if *_get_exception_ports() returned KERN_SUCCESS, with handlers set appropriately. false otherwise, with an appropriate message logged.

SetExceptionPort()

bool crashpad::ExceptionPorts::SetExceptionPort	(	exception_mask_t	mask,
		exception_handler_t	port,
		exception_behavior_t	behavior,
		thread_state_flavor_t	flavor ) const

Calls *_set_exception_ports() on the target.

Parameters

[in]	mask	A mask specifying the exception types to direct to port, containing EXC_MASK_* values.
[in]	port	A send right to a Mach port that will handle exceptions sustained by target_port of the types indicated in mask. The send right is copied, not consumed, by this call.
[in]	behavior	The “behavior” that the exception handler at port implements: EXCEPTION_DEFAULT, EXCEPTION_STATE, or EXCEPTION_STATE_IDENTITY, possibly combined with MACH_EXCEPTION_CODES.
[in]	flavor	The thread state flavor that the exception handler at port expects to receive and possibly modify. This argument has no effect for behavior values that indicate a “default” behavior.

Returns

true if *_set_exception_ports() returned KERN_SUCCESS. false otherwise, with an appropriate message logged.

SwapExceptionPorts()

bool crashpad::ExceptionPorts::SwapExceptionPorts	(	exception_mask_t	mask,
		exception_handler_t	new_port,
		exception_behavior_t	new_behavior,
		thread_state_flavor_t	new_flavor,
		ExceptionHandlerVector *	old_handlers ) const

Calls *_swap_exception_ports() on the target.

Parameters

[in]	mask	A mask specifying the exception types to direct to port, containing EXC_MASK_* values.
[in]	new_port	A send right to a Mach port that will handle exceptions sustained by target_port of the types indicated in mask. The send right is copied, not consumed, by this call.
[in]	new_behavior	The “behavior” that the exception handler at port implements: EXCEPTION_DEFAULT, EXCEPTION_STATE, or EXCEPTION_STATE_IDENTITY, possibly combined with MACH_EXCEPTION_CODES.
[in]	new_flavor	The thread state flavor that the exception handler at port expects to receive and possibly modify. This argument has no effect for new_behavior values that indicate a “default” behavior.
[out]	old_handlers	The exception handlers registered for target_port to handle exceptions indicated in mask. If no execption port is registered for a bit in mask, old_handlers will not contain an entry corresponding to that bit. This is a departure from the *_get_exception_ports() functions, which may return a handler whose port is set to EXCEPTION_PORT_NULL in this case. On failure, this argument is untouched.

Returns

true if *_swap_exception_ports() returned KERN_SUCCESS, with old_handlers set appropriately. . false otherwise, with an appropriate message logged.

TargetTypeName()

const char * crashpad::ExceptionPorts::TargetTypeName

(

)

const

Returns a string identifying the target type.

Returns

"host", "task", or "thread", as appropriate.

---

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

• util/mach/exception_ports.h
• util/mach/exception_ports.cc