Add tool man pages in asciidoc format.

nroff mandoc-format man pages can be generated by running:

a2x --format manpage \
    --attribute 'mansource=Crashpad' \
    --attribute 'manversion=0.6.0' \
    --attribute 'manmanual=Crashpad Manual' \
    --attribute 'revdate=October 2014' \
    manpage.ad

For HTML output, use --format xhtml.

R=rsesek@chromium.org

Review URL: https://codereview.chromium.org/664553004

tools/catch_exception_tool.ad

@@ -0,0 +1,121 @@
+// 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
+
+= catch_exception_tool(1)
+
+== Name
+
+catch_exception_tool - Catch Mach exceptions and display information about them
+
+== Synopsis
+
+[verse]
+*catch_exception_tool* *-m* 'SERVICE' ['OPTION…']
+
+== Description
+
+Runs a Mach exception server registered with the bootstrap server under the name
+'SERVICE'. The exception server is capable of receiving exceptions for
+“behavior” values of +EXCEPTION_DEFAULT+, +EXCEPTION_STATE+, and
++EXCEPTION_STATE_IDENTITY+, with or without +MACH_EXCEPTION_CODES+ set.
+
+== Options
+
+*-f*, *--file*='FILE'::
+Information about the exception will be appended to 'FILE' instead of the
+standard output stream.
+
+*-m*, *--mach_service*='SERVICE'::
+Check in with the bootstrap server under the name 'SERVICE'. This service name
+may already be reserved with the bootstrap server in cases where this tool is
+started by launchd(8) as a result of a message being sent to a service declared
+in a job’s +MachServices+ dictionary (see launchd.plist(5)). The service name
+may also be completely unknown to the system.
+
+*-n*, *--nonblocking*::
+Don’t wait for an exception to occur if one is not received immediately. In
+nonblocking mode, this tool exits immediately if no exception is received. The
+default mode is blocking.
+
+*-p*, *--persistent*::
+Continue processing exceptions after the first one. The default mode is
+one-shot, where this tool exits after processing the first exception.
+
+*-t*, *--timeout*='TIMEOUT'::
+Run for a maximum of 'TIMEOUT' seconds. This option only has an effect in
+blocking mode (when *--nonblocking* is not specified). In *--persistent* mode,
+'TIMEOUT' applies to the overall duration that this tool will run, not to the
+processing of individual exceptions.
+
+*--help*::
+Display help and exit.
+
+*--version*::
+Output version information and exit.
+
+== Examples
+
+Run a one-shot blocking exception server registered with the bootstrap server
+under the name +svc+:
+[subs="quotes"]
+----
+$ *catch_exception_tool --mach_service=svc --file=out &*
+[1] 1233
+$ *exception_port_tool --set_handler=handler=bootstrap:svc crasher*
+Illegal instruction: 4
+[1]+  Done    catch_exception_tool --mach_service=svc --file=out
+$ *cat out*
+catch_exception_tool:
+behavior EXCEPTION_DEFAULT|MACH_EXCEPTION_CODES,
+pid 1234, thread 56789, exception EXC_CRASH, codes[2] 0x4200001, 0,
+original exception EXC_BAD_INSTRUCTION, original code[0] 1,
+signal SIGILL
+----
+
+Run an on-demand exception server started by launchd(5) available via the
+bootstrap server under the name +svc+:
+[subs="quotes"]
+----
+$ *on_demand_service_tool --load --label=catch_exception \
+      --mach_service=svc \
+      $(which catch_exception_tool) --mach_service=svc \
+      --file=/tmp/out --nonblocking --persistent*
+$ *exception_port_tool --set_handler=handler=bootstrap:svc crasher*
+Illegal instruction: 4
+$ *on_demand_service_tool --unload --label=catch_exception*
+$ *cat /tmp/out*
+catch_exception_tool:
+behavior EXCEPTION_DEFAULT|MACH_EXCEPTION_CODES,
+pid 2468, thread 13579, exception EXC_CRASH, codes[2] 0x4200001, 0,
+original exception EXC_BAD_INSTRUCTION, original code[0] 1,
+signal SIGILL
+----
+
+== Exit Status
+
+*0*::
+Success. In *--persistent* mode with a *--timeout* set, it is considered
+successful if at least one exception was caught when the timer expires.
+
+*1*::
+Failure, with a message printed to the standard error stream.
+
+== See Also
+
+exception_port_tool(1),
+on_demand_service_tool(1)
+
+include::man_footer.ad[]

tools/exception_port_tool.ad

@@ -0,0 +1,183 @@
+// 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[]

tools/exception_port_tool.cc

@@ -334,7 +334,7 @@ void Usage(const std::string& me) {
 "\n"
 "DESCRIPTION is formatted as a comma-separated sequence of tokens, where each\n"
 "token consists of a key and value separated by an equals sign. Available keys:\n"
-"  target    which target's exception ports to set: host, task, or target\n"
+"  target    which target's exception ports to set: host, task, or thread\n"
 "  mask      the mask of exception types to handle: CRASH, ALL, or others\n"
 "  behavior  the specific exception handler routine to call: DEFAULT, STATE,\n"
 "            or STATE_IDENTITY, possibly with MACH_EXCEPTION_CODES.\n"

tools/man_footer.ad

@@ -0,0 +1,40 @@
+// 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.
+
+== Resources
+
+Crashpad home page: https://crashpad.googlecode.com/.
+
+Report bugs at https://code.google.com/p/crashpad/issues/entry.
+
+== Copyright
+
+Copyright 2014
+https://chromium.googlesource.com/crashpad/crashpad/+/master/AUTHORS[The
+Crashpad 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
+
+[subs="macros"]
+    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.

tools/on_demand_service_tool.ad

@@ -0,0 +1,102 @@
+// 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
+
+= on_demand_service_tool(1)
+
+== Name
+
+on_demand_service_tool - Load and unload on-demand Mach services registered with
+launchd(8)
+
+== Synopsis
+
+[verse]
+*on_demand_service_tool* *-L* *-l* 'LABEL' ['OPTION…'] 'COMMAND' ['ARG…']
+*on_demand_service_tool* *-U* *-l* 'LABEL'
+
+== Description
+
+On-demand services may be registered with launchd(8) by using the *--load* form.
+One or more service names may be registered with the bootstrap server by
+specifying *--mach_service*. When a Mach message is sent to any of these
+services, launchd(8) will invoke 'COMMAND' along with any arguments specified
+('ARG…'). 'COMMAND' must be an absolute pathname.
+
+The *--unload* form unregisters jobs registered with launchd(8).
+
+== Options
+
+*-L*, *--load*::
+Registers a job with launchd(8). *--label*='LABEL' and 'COMMAND' are required.
+This operation may also be referred to as “load” or “submit”.
+
+*-U*, *--unload*::
+Unregisters a job with launchd(8). *--label*='LABEL' is required. This operation
+may also be referred to as “unload” or “remove”.
+
+*-l*, *--label*='LABEL'::
+'LABEL' is used as the job label to identify the job to launchd(8). 'LABEL' must
+be unique within a launchd(8) context.
+
+*-m*, *--mach_service*='SERVICE'::
+In conjunction with *--load*, registers 'SERVICE' with the bootstrap server.
+Clients will be able to obtain a send right by looking up the 'SERVICE' name
+with the bootstrap server. When a message is sent to such a Mach port,
+launchd(8) will invoke 'COMMAND' along with any arguments specified ('ARG…') if
+it is not running. This forms the “on-demand” nature referenced by this tool’s
+name. This option may appear zero, one, or more times. 'SERVICE' must be unique
+within a bootstrap context.
+
+*--help*::
+Display help and exit.
+
+*--version*::
+Output version information and exit.
+
+== Examples
+
+Registers an on-demand server that will execute catch_exception_tool(1) when a
+Mach message is sent to a Mach port obtained from the bootstrap server by
+looking up the name +svc+:
+[subs="quotes"]
+----
+$ *on_demand_service_tool --load --label=catch_exception \
+      --mach_service=svc \
+      $(which catch_exception_tool) --mach_service=svc \
+      --file=/tmp/out --nonblocking --persistent*
+----
+
+Unregisters the on-demand server installed above:
+[subs="quotes"]
+----
+$ *on_demand_service_tool --unload --label=catch_exception*
+----
+
+== Exit Status
+
+*0*::
+Success.
+
+*1*::
+Failure, with a message printed to the standard error stream.
+
+== See Also
+
+exception_port_tool(1),
+launchctl(1)
+on_demand_service_tool(1)
+
+include::man_footer.ad[]