| // 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 |
| |
| = crashpad_handler(8) |
| |
| == Name |
| |
| crashpad_handler - Crashpad’s exception handler server |
| |
| == Synopsis |
| |
| [verse] |
| *crashpad_handler* ['OPTION…'] |
| |
| == Description |
| |
| This program is Crashpad’s main exception-handling server. It is responsible for |
| catching exceptions, writing crash reports, and uploading them to a crash report |
| collection server. Uploads are disabled by default, and can only be enabled by a |
| Crashpad client using the Crashpad client library, typically in response to a |
| user requesting this behavior. |
| |
| On OS X, this server may be started by its initial client, in which case it |
| performs a handshake with this client via a pipe established by the client that |
| is inherited by the server, referenced by the *--handshake-fd* argument. During |
| the handshake, the server furnishes the client with a send right that the client |
| may use as an exception port. The server retains the corresponding receive |
| right, which it monitors for exception messages. When the receive right loses |
| all senders, the server exits after allowing any upload in progress to complete. |
| |
| Alternatively, on OS X, this server may be started from launchd(8), where it |
| receives the Mach service name in a *--mach-service* argument. It checks in with |
| the bootstrap server under this service name, and clients may look it up with |
| the bootstrap server under this service name. It monitors this service for |
| exception messages. Upon receipt of +SIGTERM+, the server exits after allowing |
| any upload in progress to complete. +SIGTERM+ is normally sent by launchd(8) |
| when it determines that the server should exit. |
| |
| On Windows, clients register with this server by communicating with it via the |
| named pipe identified by the *--pipe-name* argument. Alternatively, the server |
| can inherit an already-created pipe from a parent process by using the |
| *--initial-client-data* mechanism. That argument also takes all of the arguments |
| that would normally be passed in a registration message, and so constitutes |
| registration of the first client. Subsequent clients may then register by |
| communicating with the server via the pipe. During registration, a client |
| provides the server with an OS event object that it will signal should it crash. |
| The server obtains the client’s process handle and waits on the crash event |
| object for a crash, as well as the client’s process handle for the client to |
| exit cleanly without crashing. When a server started via the |
| *--initial-client-data* mechanism loses all of its clients, it exits after |
| allowing any upload in progress to complete. |
| |
| On Windows, this executable is built by default as a Windows GUI app, so no |
| console will appear in normal usage. This is the version that will typically be |
| used. A second copy is also made with a +.com+ extension, rather than +.exe+. In |
| this second copy, the PE header is modified to indicate that it's a console app. |
| This is useful because the +.com+ is found in the path before the +.exe+, so |
| when run normally from a shell using only the basename (without an explicit |
| +.com+ or +.exe+ extension), the +.com+ console version will be chosen, and so |
| stdio will be hooked up as expected to the parent console so that logging output |
| will be visible. |
| |
| It is not normally appropriate to invoke this program directly. Usually, it will |
| be invoked by a Crashpad client using the Crashpad client library, or started by |
| another system service. On OS X, arbitrary programs may be run with a Crashpad |
| handler by using man_link:run_with_crashpad[1] to establish the Crashpad client |
| environment before running a program. |
| |
| == Options |
| *--annotation*='KEY=VALUE':: |
| Sets a process-level annotation mapping 'KEY' to 'VALUE' in each crash report |
| that is written. This option may appear zero, one, or multiple times. |
| + |
| Most annotations should be provided by the Crashpad client as module-level |
| annotations instead of process-level annotations. Module-level annotations are |
| more flexible in that they can be modified and cleared during the client |
| program’s lifetime. Module-level annotations can be set via the Crashpad client |
| library. Process-level annotations are useful for annotations that the |
| collection server requires be present, that have fixed values, and for cases |
| where a program that does not use the Crashpad client library is being |
| monitored. |
| + |
| Breakpad-type collection servers only require the +"prod"+ and +"ver"+ |
| annotations, which should be set to the product name or identifier and product |
| version, respectively. It is unusual to specify other annotations as |
| process-level annotations via this argument. |
| |
| *--database*='PATH':: |
| Use 'PATH' as the path to the Crashpad crash report database. This option is |
| required. Crash reports are written to this database, and if uploads are |
| enabled, uploaded from this database to a crash report collection server. If the |
| database does not exist, it will be created, provided that the parent directory |
| of 'PATH' exists. |
| |
| *--handshake-fd*='FD':: |
| Perform the handshake with the initial client on the file descriptor at 'FD'. |
| Either this option or *--mach-service*, but not both, is required. This option |
| is only valid on OS X. |
| |
| *--initial-client-data*='HANDLE_request_crash_dump','HANDLE_request_non_crash_dump','HANDLE_non_crash_dump_completed','HANDLE_first_pipe_instance','HANDLE_client_process','Address_crash_exception_information','Address_non_crash_exception_information','Address_debug_critical_section':: |
| Register the initial client using the inherited handles and data provided. For |
| more information on the arguments, see the implementations of +CrashpadClient+ |
| and +ExceptionHandlerServer+. Either this option or *--pipe-name*, but not both, |
| is required. This option is only valid on Windows. |
| + |
| When this option is present, the server creates a new named pipe at a random |
| name and informs its client of the name. The server waits for at least one |
| client to register, and exits when all clients have exited, after waiting for |
| any uploads in progress to complete. |
| |
| *--mach-service*='SERVICE':: |
| Check in with the bootstrap server under the name 'SERVICE'. Either this option |
| or *--handshake-fd*, but not both, is required. This option is only valid on OS |
| X. |
| + |
| 'SERVICE' 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. |
| |
| *--no-rate-limit*:: |
| Do not rate limit the upload of crash reports. By default uploads are throttled |
| to one per hour. Using this option disables that behavior, and Crashpad will |
| attempt to upload all captured reports. |
| |
| *--pipe-name*='PIPE':: |
| Listen on the given pipe name for connections from clients. 'PIPE' must be of |
| the form +\\.\pipe\<somename>+. Either this option or *--initial-client-data*, |
| but not both, is required. This option is only valid on Windows. |
| + |
| When this option is present, the server creates a named pipe at 'PIPE', a name |
| known to both the server and its clients. The server continues running even |
| after all clients have exited. |
| |
| *--reset-own-crash-exception-port-to-system-default*:: |
| Causes the exception handler server to set its own crash handler to the system |
| default before beginning operation. This is only expected to be useful in cases |
| where the server inherits an inappropriate crash handler from its parent |
| process. This option is only valid on OS X. Use of this option is discouraged. |
| It should not be used absent extraordinary circumstances. |
| |
| *--url*='URL':: |
| If uploads are enabled, sends crash reports to the Breakpad-type crash report |
| collection server at 'URL'. Uploads are disabled by default, and can only be |
| enabled for a database by a Crashpad client using the Crashpad client library, |
| typically in response to a user requesting this behavior. If this option is not |
| specified, this program will behave as if uploads are disabled. |
| |
| *--help*:: |
| Display help and exit. |
| |
| *--version*:: |
| Output version information and exit. |
| |
| == Exit Status |
| |
| *0*:: |
| Success. |
| |
| *1*:: |
| Failure, with a message printed to the standard error stream. |
| |
| == See Also |
| |
| man_link:catch_exception_tool[1], |
| man_link:crashpad_database_util[1], |
| man_link:generate_dump[1], |
| man_link:run_with_crashpad[1] |
| |
| include::../doc/support/man_footer.ad[] |