3party/crashpad
0
0
Fork 0
mirror of https://github.com/chromium/crashpad.git synced 2024-12-27 07:14:10 +08:00
Code Issues Projects Releases Wiki Activity
crashpad/tools/mac/exception_port_tool.ad
Mark Mentovai 332e8219ed Migrate content from wiki. 
The wiki existed at https://code.google.com/p/crashpad/wiki, but given
Google Code Project Hosting’s impending shutdown[1], it’s prudent to
move wiki documents into the source code repository.

This change moves the existing contents of doc into doc/support, to make
way for documentation in doc. The two existing wiki pages, ProjectStatus
and DevelopingCrashpad, are converted to AsciiDoc format (a fairly
straightforward conversion) and checked in to doc. generate_asciidoc.sh
is updated to produce HTML output from these files. The generated HTML
will show up at http://docs.crashpad.googlecode.com/git/doc/. Note that
generated HTML is still hosted on Google Code Project Hosting, but it’ll
be easy to find a new home for them.

[1]
http://google-opensource.blogspot.com/2015/03/farewell-to-google-code.html

R=rsesek@chromium.org

Review URL: https://codereview.chromium.org/1055523002
2015-04-01 12:39:53 -04:00

189 lines
7.2 KiB
Plaintext
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.
:doctype: manpage
= exception_port_tool(1)
== Name
exception_port_tool - Show and change Mach exception ports
== Synopsis
[verse]
*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*, or *GUARD*. Different exception types may be
combined by combining them with pipe characters (*|*). The special value *ALL*
includes each exception type except for *CRASH*. To truly specify all exception
types including *CRASH*, use *ALL|CRASH*. 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-&#42;* 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.
*-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-&#42;* 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.
[subs="quotes"]
----
$ *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).
[subs="quotes"]
----
# *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
man_link:catch_exception_tool[1],
man_link:on_demand_service_tool[1]
include::../../doc/support/man_footer.ad[]
Reference in New Issue View Git Blame Copy Permalink