3party/crashpad
0
0
Fork 0
mirror of https://github.com/chromium/crashpad.git synced 2025-03-09 14:06:33 +00:00
Code Issues Packages Projects Releases Wiki Activity

Add tool man pages in asciidoc format.

Browse Source 
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
This commit is contained in:
Mark Mentovai 2014-10-17 11:01:48 -04:00
parent c9db1b1d19
commit f59e3e6b78
5 changed files with 447 additions and 1 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

121
tools/catch_exception_tool.ad Normal file
View File

@ -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[]

183
tools/exception_port_tool.ad Normal file
View File

@ -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[]

2
tools/exception_port_tool.cc
View File

@ -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"

40
tools/man_footer.ad Normal file
View File

@ -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.

102
tools/on_demand_service_tool.ad Normal file
View File

@ -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[]