Add tool man pages in asciidoc format

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. This
+option may be restricted to use by the superuser or processes permitted by
+taskgated(8) to use +task_for_pid()+. When this option is supplied, 'COMMAND'
+must not be specified.
+
+*-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
+
+exception_port_tool(1),
+on_demand_service_tool(1)
+
+include::man_footer.ad[]