3party/crashpad
0
0
Fork 0
mirror of https://github.com/chromium/crashpad.git synced 2025-03-21 11:13:47 +00:00
Code Issues Packages Projects Releases Wiki Activity
0c41b15496
crashpad/tools/mac/exception_port_tool.md
Mark Mentovai 0c41b15496 Convert AsciiDoc documentation to Markdown 
Most of the world, including the Chromium universe, seems to be
standardizing on Markdown for documentation. Markdown provides the
benefit of automatic rendering on Gitiles (Gerrit), and on GitHub
mirrors as well. Crashpad should fit in with its surroundings.

There are two quirks that I was unable to resolve.

 - Markdown does not allow **emphasis** within a ```code fence```
   region. In blocks showing interactive examples, the AsciiDoc
   documentation used this to highlight what the user was expected to
   type.
 - Markdown does not have a “definition list” (<dl>). This would have
   been nice in man pages for the Options and Exit Status sections.
   In its place, I used unnumbered lists. This is a little ugly, but
   it’s not the end of the world.

The new Markdown-formatted documentation is largely identical to the
AsciiDoc that it replaces. Minor editorial revisions were made.
References to Mac OS X now mention macOS, and tool man pages describing
tools that that access task ports now mention System Integrity
Protection (SIP).

The AppEngine-based https://crashpad.chromium.org/ app in doc/appengine
is still necessary to serve Doxygen-generated documentation. This app is
updated to redirect existing generated-HTML URLs to Gitiles’ automatic
Markdown rendering.

Scripts in doc/support are updated to adapt to this change. All AsciiDoc
support files in doc/support have been removed.

BUG=crashpad:138

Change-Id: I15ad423d5b7aa1b7aa2ed1d2cb72639eec7c81aa
Reviewed-on: https://chromium-review.googlesource.com/408256
Reviewed-by: Robert Sesek <rsesek@chromium.org>
Reviewed-by: Scott Graham <scottmg@chromium.org>
2016-11-04 21:13:53 +00:00

235 lines
8.7 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

<!--
Copyright 2014 The Crashpad Authors. All rights reserved.
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.
-->
# 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)](https://support.apple.com/HT204899), 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)](catch_exception_tool.md),
[on_demand_service_tool(1)](on_demand_service_tool.md),
## Resources
Crashpad home page: https://crashpad.chromium.org/.
Report bugs at https://crashpad.chromium.org/bug/new.
## Copyright
Copyright 2014 [The Crashpad
Authors](https://chromium.googlesource.com/crashpad/crashpad/+/master/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.
Reference in New Issue View Git Blame Copy Permalink