tools: Move Mac-specific tools to tools/mac

tools/exception_port_tool.ad

-// 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 *CRASH*. 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 or processes permitted by
-taskgated(8). Consequently, this program must normally 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
-
-catch_exception_tool(1),
-on_demand_service_tool(1)
-
-include::man_footer.ad[]