Crashpad

Classes | Public Types | Public Member Functions | List of all members
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. More...
bool | GetExceptionPorts (exception_mask_t mask, ExceptionHandlerVector *handlers) const
| Calls `*_get_exception_ports()` on the target. More...
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. More...
const char * | TargetTypeName () const
| Returns a string identifying the target type. More...

## 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.

## ◆ 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