| Index: third_party/crashpad/crashpad/tools/mac/exception_port_tool.ad
|
| diff --git a/third_party/crashpad/crashpad/tools/mac/exception_port_tool.ad b/third_party/crashpad/crashpad/tools/mac/exception_port_tool.ad
|
| new file mode 100644
|
| index 0000000000000000000000000000000000000000..e102cc008c2e7a722ad64087a49d2a12a2f8072c
|
| --- /dev/null
|
| +++ b/third_party/crashpad/crashpad/tools/mac/exception_port_tool.ad
|
| @@ -0,0 +1,188 @@
|
| +// 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*, *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*. 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-** 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-** 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[]
|
|
|