Index: third_party/crashpad/crashpad/handler/crashpad_handler.md |
diff --git a/third_party/crashpad/crashpad/handler/crashpad_handler.md b/third_party/crashpad/crashpad/handler/crashpad_handler.md |
new file mode 100644 |
index 0000000000000000000000000000000000000000..31c0b3472e720eac06c0a3bf35806d0479b8af77 |
--- /dev/null |
+++ b/third_party/crashpad/crashpad/handler/crashpad_handler.md |
@@ -0,0 +1,222 @@ |
+<!-- |
+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. |