Update Crashpad to 32981a3ee9d7c2769fb27afa038fe2e194cfa329

third_party/crashpad/crashpad/handler/crashpad_handler.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
-
-= 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[]