Update Crashpad to 32981a3ee9d7c2769fb27afa038fe2e194cfa329

third_party/crashpad/crashpad/handler/crashpad_handler.md

+<!--
+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.
+-->
+
+# crashpad_handler(8)
+
+## Name
+
+crashpad_handler—Crashpad’s exception handler server
+
+## Synopsis
+
+**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 macOS, 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 macOS, 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 macOS, arbitrary programs may be run with a Crashpad
+handler by using [run_with_crashpad(1)](../tools/mac/run_with_crashpad.md) 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 macOS.
+
+ * **--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 argument’s format, 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 macOS.
+
+   _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 macOS. 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
+
+[catch_exception_tool(1)](../tools/mac/catch_exception_tool.md),
+[crashpad_database_util(1)](../tools/crashpad_database_util.md),
+[generate_dump(1)](../tools/generate_dump.md),
+[run_with_crashpad(1)](../tools/mac/run_with_crashpad.md)
+
+## Resources
+
+Crashpad home page: https://crashpad.chromium.org/.
+
+Report bugs at https://crashpad.chromium.org/bug/new.
+
+## Copyright
+
+Copyright 2014 [The Crashpad
+Authors](https://chromium.googlesource.com/crashpad/crashpad/+/master/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
+
+  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.