diff --git a/tools/catch_exception_tool.ad b/tools/catch_exception_tool.ad new file mode 100644 index 00000000..f411dd9c --- /dev/null +++ b/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[] diff --git a/tools/exception_port_tool.ad b/tools/exception_port_tool.ad new file mode 100644 index 00000000..684f2b7a --- /dev/null +++ b/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 +++. 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_** 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_** 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[] diff --git a/tools/exception_port_tool.cc b/tools/exception_port_tool.cc index 4a2e440f..c20db73e 100644 --- a/tools/exception_port_tool.cc +++ b/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" diff --git a/tools/man_footer.ad b/tools/man_footer.ad new file mode 100644 index 00000000..10853855 --- /dev/null +++ b/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. diff --git a/tools/on_demand_service_tool.ad b/tools/on_demand_service_tool.ad new file mode 100644 index 00000000..23e2bc21 --- /dev/null +++ b/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[]