crashpad/tools/mac/exception_port_tool.md

exception_port_tool(1)

Name

exception_port_tool—Show and change Mach exception ports

Synopsis

exception_port_tool [OPTION…] [COMMAND [ARG…]]

Description

Shows Mach exception ports registered for a thread, task, or host target with a --show-* option, changes Mach exception ports with --set-handler, shows changes with a --show-new-* option, and executes COMMAND along with any arguments specified (ARG…) with the changed exception ports in effect.

Options

• -s, --set-handler=DESCRIPTION

  Set an exception port to DESCRIPTION. This option may appear zero, one, or more times.

  DESCRIPTION is formatted as a comma-separated sequence of tokens, where each token consists of a key and value separated by an equals sign. These keys are recognized:

  • target=TARGET

    TARGET defines which target’s exception ports to set: host, task, or thread. The default value of TARGET is task. Operations on host are restricted to the superuser.

  • mask=MASK

    MASK defines the mask of exception types to handle, from <mach/exception_types.h>. This can be BAD_ACCESS, BAD_INSTRUCTION, ARITHMETIC, EMULATION, SOFTWARE, BREAKPOINT, SYSCALL, MACH_SYSCALL, RPC_ALERT, CRASH, RESOURCE, GUARD, or CORPSE_NOTIFY. Different exception types may be combined by combining them with pipe characters (|). The special value ALL includes each exception type except for CRASH and CORPSE_NOTIFY. To truly specify all exception types including these, use ALL|CRASH|CORPSE_NOTIFY. The default value of MASK is CRASH.

  • behavior=BEHAVIOR

    BEHAVIOR defines the specific exception handler routine to be called when an exception occurs. This can be DEFAULT, STATE, or STATE_IDENTITY. MACH may also be specified by combining them with pipe characters (|). The most complete set of exception information is provided with STATE_IDENTITY|MACH. Not all exception servers implement all possible behaviors. The default value of BEHAVIOR is DEFAULT|MACH.

  • flavor=FLAVOR

    For state-carrying values of BEHAVIOR (those including STATE or STATE_IDENTITY), FLAVOR specifies the architecture-specific thread state flavor to be provided to the exception handler. For the x86 family, this can be THREAD, THREAD32, THREAD64, FLOAT, FLOAT32, FLOAT64, DEBUG, DEBUG32, or DEBUG64. The default value of FLAVOR is NONE, which is not valid for state-carrying values of BEHAVIOR.

  • handler=HANDLER

    HANDLER defines the exception handler. NULL indicates that any existing exception port should be cleared. HANDLER may also take the form bootstrap:SERVICE, which will look SERVICE up with the bootstrap server and set that service as the exception handler. The default value of HANDLER is NULL.

• --show-bootstrap=SERVICE

  Looks up SERVICE with the bootstrap server and shows it. Normally, the handler port values displayed by the other --show-* options are meaningless handles, but by comparing them to the port values for known bootstrap services, it is possible to verify that they are set as intended.

• -p, --pid=PID

  For operations on the task target, including --set-handler with TARGET set to task, --show-task, and --show-new-task, operates on the task associated with process id PID instead of the current task associated with the tool. When this option is supplied, COMMAND must not be specified.

  This option uses task_for_pid() to access the process’ task port. This operation may be restricted to use by the superuser, executables signed by an authority trusted by the system, and processes otherwise permitted by taskgated(8). Consequently, this program must normally either be signed or be invoked by root to use this option. It is possible to install this program as a setuid root executable to overcome this limitation. However, it is not possible to use this option to operate on processes protected by System Integrity Protection (SIP), including those whose “restrict” codesign(1) option is respected.

• -h, --show-host

  Shows the original host exception ports before making any changes requested by --set-handler. This option is restricted to the superuser.

• -t, --show-task

  Shows the original task exception ports before making any changes requested by --set-handler.

• --show-thread

  Shows the original thread exception ports before making any changes requested by --set-handler.

• -H, --show-new-host

  Shows the modified host exception ports after making any changes requested by --set-handler. This option is restricted to the superuser.

• -T, --show-new-task

  Shows the modified task exception ports after making any changes requested by --set-handler.

• --show-new-thread

  Shows the modified thread exception ports after making any changes requested by --set-handler

• -n, --numeric

  For --show-* options, all values will be displayed numerically only. The default is to decode numeric values and display them symbolically as well.

• --help

  Display help and exit.

• --version

  Output version information and exit.

Examples

Sets a new task-level exception handler for EXC_CRASH-type exceptions to the handler registered with the bootstrap server as svc, showing the task-level exception ports before and after the change. The old and new exception handlers are verified by their service names as registered with the bootstrap server. With the new task-level exception ports in effect, a program is run.

$ exception_port_tool --show-task --show-new-task \
      --show-bootstrap=com.apple.ReportCrash --show-bootstrap=svc \
      --set-handler=behavior=DEFAULT,handler=bootstrap:svc crash
service com.apple.ReportCrash 0xe03
service svc 0x1003
task exception port 0, mask 0x400 (CRASH), port 0xe03, behavior 0x80000003 (STATE_IDENTITY|MACH), flavor 7 (THREAD)
new task exception port 0, mask 0x400 (CRASH), port 0x1003, behavior 0x1 (DEFAULT), flavor 13 (NONE)
Illegal instruction: 4

Shows the task-level exception ports for the process with PID 1234. This requires superuser permissions or the approval of taskgated(8), and the process must not be SIP-protected.

# exception_port_tool --pid=1234 --show-task
task exception port 0, mask 0x4e (BAD_ACCESS|BAD_INSTRUCTION|ARITHMETIC|BREAKPOINT), port 0x1503, behavior 0x1 (DEFAULT), flavor 13 (NONE)
task exception port 1, mask 0x1c00 (CRASH|RESOURCE|GUARD), port 0x1403, behavior 0x80000003 (STATE_IDENTITY|MACH), flavor 7 (THREAD)

Exit Status

• 0

  Success.

• 125

  Failure, with a message printed to the standard error stream.

• 126

  The program specified by COMMAND was found, but could not be invoked.

• 127

  The program specified by COMMAND could not be found.

See Also

catch_exception_tool(1), on_demand_service_tool(1)

Resources

Crashpad home page: https://crashpad.chromium.org/.

Report bugs at https://crashpad.chromium.org/bug/new.

Copyright

Copyright 2014 The Crashpad Authors.

License

Licensed under the Apache License, Version 2.0 (the “License”); you may not use this file except in compliance with the License. You may obtain a copy of the License at

http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an “AS IS” BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.