3party/crashpad
0
0
Fork 0
mirror of https://github.com/chromium/crashpad.git synced 2024-12-27 15:32:10 +08:00
Code Issues Projects Releases Wiki Activity
crashpad/handler/crashpad_handler.md

350 lines
16 KiB
Markdown
Raw Permalink Normal View History

Convert AsciiDoc documentation to Markdown Most of the world, including the Chromium universe, seems to be standardizing on Markdown for documentation. Markdown provides the benefit of automatic rendering on Gitiles (Gerrit), and on GitHub mirrors as well. Crashpad should fit in with its surroundings. There are two quirks that I was unable to resolve. - Markdown does not allow **emphasis** within a ```code fence``` region. In blocks showing interactive examples, the AsciiDoc documentation used this to highlight what the user was expected to type. - Markdown does not have a “definition list” (<dl>). This would have been nice in man pages for the Options and Exit Status sections. In its place, I used unnumbered lists. This is a little ugly, but it’s not the end of the world. The new Markdown-formatted documentation is largely identical to the AsciiDoc that it replaces. Minor editorial revisions were made. References to Mac OS X now mention macOS, and tool man pages describing tools that that access task ports now mention System Integrity Protection (SIP). The AppEngine-based https://crashpad.chromium.org/ app in doc/appengine is still necessary to serve Doxygen-generated documentation. This app is updated to redirect existing generated-HTML URLs to Gitiles’ automatic Markdown rendering. Scripts in doc/support are updated to adapt to this change. All AsciiDoc support files in doc/support have been removed. BUG=crashpad:138 Change-Id: I15ad423d5b7aa1b7aa2ed1d2cb72639eec7c81aa Reviewed-on: https://chromium-review.googlesource.com/408256 Reviewed-by: Robert Sesek <rsesek@chromium.org> Reviewed-by: Scott Graham <scottmg@chromium.org>
2016-11-04 17:10:36 -04:00
<!--
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
doc: Small updates after Markdown migration The strangest discovery relates to the # <h1> title in navbar.md. Gitiles renders it small unless there’s a [home] reference, so use that. This should only affect wrapping the site logo in the [home] link, but it appears to control the size of the navbar title too. See https://code.google.com/p/gitiles/issues/detail?id=130. BUG=crashpad:138,gitiles:130 Change-Id: I11b3a79f045efa22358b3c3ef4b50ce2e6b3282e Reviewed-on: https://chromium-review.googlesource.com/408458 Reviewed-by: Robert Sesek <rsesek@chromium.org>
2016-11-07 08:49:01 -05:00
this second copy, the PE header is modified to indicate that it’s a console app.
Convert AsciiDoc documentation to Markdown Most of the world, including the Chromium universe, seems to be standardizing on Markdown for documentation. Markdown provides the benefit of automatic rendering on Gitiles (Gerrit), and on GitHub mirrors as well. Crashpad should fit in with its surroundings. There are two quirks that I was unable to resolve. - Markdown does not allow **emphasis** within a ```code fence``` region. In blocks showing interactive examples, the AsciiDoc documentation used this to highlight what the user was expected to type. - Markdown does not have a “definition list” (<dl>). This would have been nice in man pages for the Options and Exit Status sections. In its place, I used unnumbered lists. This is a little ugly, but it’s not the end of the world. The new Markdown-formatted documentation is largely identical to the AsciiDoc that it replaces. Minor editorial revisions were made. References to Mac OS X now mention macOS, and tool man pages describing tools that that access task ports now mention System Integrity Protection (SIP). The AppEngine-based https://crashpad.chromium.org/ app in doc/appengine is still necessary to serve Doxygen-generated documentation. This app is updated to redirect existing generated-HTML URLs to Gitiles’ automatic Markdown rendering. Scripts in doc/support are updated to adapt to this change. All AsciiDoc support files in doc/support have been removed. BUG=crashpad:138 Change-Id: I15ad423d5b7aa1b7aa2ed1d2cb72639eec7c81aa Reviewed-on: https://chromium-review.googlesource.com/408256 Reviewed-by: Robert Sesek <rsesek@chromium.org> Reviewed-by: Scott Graham <scottmg@chromium.org>
2016-11-04 17:10:36 -04:00
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.
Add handler options for Linux/Android Add the options: --trace-parent-with-exception=<address> which traces the handler's parent process which has an ExceptionInformation struct at <address>. --initial-client-fd=<fd> which starts the handler server with an already connected client on socket <fd>. Bug: crashpad:30 Change-Id: Ied9760ca125a16f56173afdc56dff5fcb79d2eea Reviewed-on: https://chromium-review.googlesource.com/922895 Commit-Queue: Joshua Peraza <jperaza@chromium.org> Reviewed-by: Mark Mentovai <mark@chromium.org>
2018-02-20 15:03:14 -08:00
On Linux/Android, the handler may create a crash dump for its parent process
using **--trace-parent-with-exception**. In this mode, the handler process
creates a crash dump for its parent and exits. Alternatively, the handler may
be launched with **--initial-client-fd** which will start the server connected
to an initial client. The server will exit when all connected client sockets are
closed.
Convert AsciiDoc documentation to Markdown Most of the world, including the Chromium universe, seems to be standardizing on Markdown for documentation. Markdown provides the benefit of automatic rendering on Gitiles (Gerrit), and on GitHub mirrors as well. Crashpad should fit in with its surroundings. There are two quirks that I was unable to resolve. - Markdown does not allow **emphasis** within a ```code fence``` region. In blocks showing interactive examples, the AsciiDoc documentation used this to highlight what the user was expected to type. - Markdown does not have a “definition list” (<dl>). This would have been nice in man pages for the Options and Exit Status sections. In its place, I used unnumbered lists. This is a little ugly, but it’s not the end of the world. The new Markdown-formatted documentation is largely identical to the AsciiDoc that it replaces. Minor editorial revisions were made. References to Mac OS X now mention macOS, and tool man pages describing tools that that access task ports now mention System Integrity Protection (SIP). The AppEngine-based https://crashpad.chromium.org/ app in doc/appengine is still necessary to serve Doxygen-generated documentation. This app is updated to redirect existing generated-HTML URLs to Gitiles’ automatic Markdown rendering. Scripts in doc/support are updated to adapt to this change. All AsciiDoc support files in doc/support have been removed. BUG=crashpad:138 Change-Id: I15ad423d5b7aa1b7aa2ed1d2cb72639eec7c81aa Reviewed-on: https://chromium-review.googlesource.com/408256 Reviewed-by: Robert Sesek <rsesek@chromium.org> Reviewed-by: Scott Graham <scottmg@chromium.org>
2016-11-04 17:10:36 -04:00
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.
doc: Small updates after Markdown migration The strangest discovery relates to the # <h1> title in navbar.md. Gitiles renders it small unless there’s a [home] reference, so use that. This should only affect wrapping the site logo in the [home] link, but it appears to control the size of the navbar title too. See https://code.google.com/p/gitiles/issues/detail?id=130. BUG=crashpad:138,gitiles:130 Change-Id: I11b3a79f045efa22358b3c3ef4b50ce2e6b3282e Reviewed-on: https://chromium-review.googlesource.com/408458 Reviewed-by: Robert Sesek <rsesek@chromium.org>
2016-11-07 08:49:01 -05:00
* **--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*
Convert AsciiDoc documentation to Markdown Most of the world, including the Chromium universe, seems to be standardizing on Markdown for documentation. Markdown provides the benefit of automatic rendering on Gitiles (Gerrit), and on GitHub mirrors as well. Crashpad should fit in with its surroundings. There are two quirks that I was unable to resolve. - Markdown does not allow **emphasis** within a ```code fence``` region. In blocks showing interactive examples, the AsciiDoc documentation used this to highlight what the user was expected to type. - Markdown does not have a “definition list” (<dl>). This would have been nice in man pages for the Options and Exit Status sections. In its place, I used unnumbered lists. This is a little ugly, but it’s not the end of the world. The new Markdown-formatted documentation is largely identical to the AsciiDoc that it replaces. Minor editorial revisions were made. References to Mac OS X now mention macOS, and tool man pages describing tools that that access task ports now mention System Integrity Protection (SIP). The AppEngine-based https://crashpad.chromium.org/ app in doc/appengine is still necessary to serve Doxygen-generated documentation. This app is updated to redirect existing generated-HTML URLs to Gitiles’ automatic Markdown rendering. Scripts in doc/support are updated to adapt to this change. All AsciiDoc support files in doc/support have been removed. BUG=crashpad:138 Change-Id: I15ad423d5b7aa1b7aa2ed1d2cb72639eec7c81aa Reviewed-on: https://chromium-review.googlesource.com/408256 Reviewed-by: Robert Sesek <rsesek@chromium.org> Reviewed-by: Scott Graham <scottmg@chromium.org>
2016-11-04 17:10:36 -04:00
Register the initial client using the inherited handles and data provided.
doc: Small updates after Markdown migration The strangest discovery relates to the # <h1> title in navbar.md. Gitiles renders it small unless there’s a [home] reference, so use that. This should only affect wrapping the site logo in the [home] link, but it appears to control the size of the navbar title too. See https://code.google.com/p/gitiles/issues/detail?id=130. BUG=crashpad:138,gitiles:130 Change-Id: I11b3a79f045efa22358b3c3ef4b50ce2e6b3282e Reviewed-on: https://chromium-review.googlesource.com/408458 Reviewed-by: Robert Sesek <rsesek@chromium.org>
2016-11-07 08:49:01 -05:00
For more information on the argument’s format, see the implementations of
Convert AsciiDoc documentation to Markdown Most of the world, including the Chromium universe, seems to be standardizing on Markdown for documentation. Markdown provides the benefit of automatic rendering on Gitiles (Gerrit), and on GitHub mirrors as well. Crashpad should fit in with its surroundings. There are two quirks that I was unable to resolve. - Markdown does not allow **emphasis** within a ```code fence``` region. In blocks showing interactive examples, the AsciiDoc documentation used this to highlight what the user was expected to type. - Markdown does not have a “definition list” (<dl>). This would have been nice in man pages for the Options and Exit Status sections. In its place, I used unnumbered lists. This is a little ugly, but it’s not the end of the world. The new Markdown-formatted documentation is largely identical to the AsciiDoc that it replaces. Minor editorial revisions were made. References to Mac OS X now mention macOS, and tool man pages describing tools that that access task ports now mention System Integrity Protection (SIP). The AppEngine-based https://crashpad.chromium.org/ app in doc/appengine is still necessary to serve Doxygen-generated documentation. This app is updated to redirect existing generated-HTML URLs to Gitiles’ automatic Markdown rendering. Scripts in doc/support are updated to adapt to this change. All AsciiDoc support files in doc/support have been removed. BUG=crashpad:138 Change-Id: I15ad423d5b7aa1b7aa2ed1d2cb72639eec7c81aa Reviewed-on: https://chromium-review.googlesource.com/408256 Reviewed-by: Robert Sesek <rsesek@chromium.org> Reviewed-by: Scott Graham <scottmg@chromium.org>
2016-11-04 17:10:36 -04:00
`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.
linux: Implement StartHandler() This CL adds a RequestCrashDumpHandler to request a crash dump over a socket. Common functionality with LaunchAtCrashHandler is factored out into a SignalHandler base class. Bug: crashpad:284 Change-Id: I86293ef599a0dd6eea63c096a5c931c620c05ecc Reviewed-on: https://chromium-review.googlesource.com/c/crashpad/crashpad/+/1568985 Reviewed-by: Mark Mentovai <mark@chromium.org>
2019-05-01 22:19:21 -07:00
* **--initial-client-fd**=_FD_
Wait for client requests on _FD_. Either this option or
**--trace-parent-with-exception**, but not both, is required. The handler
exits when all client connections have been closed. This option is only valid
on Linux platforms.
Convert AsciiDoc documentation to Markdown Most of the world, including the Chromium universe, seems to be standardizing on Markdown for documentation. Markdown provides the benefit of automatic rendering on Gitiles (Gerrit), and on GitHub mirrors as well. Crashpad should fit in with its surroundings. There are two quirks that I was unable to resolve. - Markdown does not allow **emphasis** within a ```code fence``` region. In blocks showing interactive examples, the AsciiDoc documentation used this to highlight what the user was expected to type. - Markdown does not have a “definition list” (<dl>). This would have been nice in man pages for the Options and Exit Status sections. In its place, I used unnumbered lists. This is a little ugly, but it’s not the end of the world. The new Markdown-formatted documentation is largely identical to the AsciiDoc that it replaces. Minor editorial revisions were made. References to Mac OS X now mention macOS, and tool man pages describing tools that that access task ports now mention System Integrity Protection (SIP). The AppEngine-based https://crashpad.chromium.org/ app in doc/appengine is still necessary to serve Doxygen-generated documentation. This app is updated to redirect existing generated-HTML URLs to Gitiles’ automatic Markdown rendering. Scripts in doc/support are updated to adapt to this change. All AsciiDoc support files in doc/support have been removed. BUG=crashpad:138 Change-Id: I15ad423d5b7aa1b7aa2ed1d2cb72639eec7c81aa Reviewed-on: https://chromium-review.googlesource.com/408256 Reviewed-by: Robert Sesek <rsesek@chromium.org> Reviewed-by: Scott Graham <scottmg@chromium.org>
2016-11-04 17:10:36 -04:00
* **--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.
Add the --monitor-self argument to crashpad_handler https://crbug.com/678959 added “fallback” crash reporting for crashpad_handler on Windows, in a Chrome- and Windows-specific way. This implements a more general self-monitor mechanism that will work on multiple platforms and in the absence of Chrome. When starting crashpad_handler (let’s call it the “first instance”) with --monitor-self, it will start another crashpad_handler (the “second instance”). The second instance monitors the first one for crashes. The second instance will be started in mostly the same way as the first instance, except --monitor-self will not be provided to the second instance. Bug: crashpad:143 Change-Id: I76f3f47d1762d8ecae1814357cb672c8b7bd5e95 Reviewed-on: https://chromium-review.googlesource.com/466267 Reviewed-by: Sigurður Ásgeirsson <siggi@chromium.org> Reviewed-by: Scott Graham <scottmg@chromium.org>
2017-04-04 10:08:56 -04:00
* **--metrics-dir**=_DIR_
Metrics information will be written to _DIR_. This option only has an effect
when built as part of Chromium. In non-Chromium builds, and in the absence of
this option, metrics information will not be written.
* **--monitor-self**
Causes a second instance of the Crashpad handler program to be started,
monitoring the original instance for exceptions. The original instance will
become a client of the second one. The second instance will be started with
handler: Add --monitor-self-annotations --monitor-self-annotations allows the Crashpad-using application to push module-level annotations in to crashpad_handler. These annotations will appear in any crash report written for that handler by --monitor-self. Bug: crashpad:143 Change-Id: If47395da75a90be4f4bdce0630ce95ea93f9fcf3 Reviewed-on: https://chromium-review.googlesource.com/467746 Reviewed-by: Scott Graham <scottmg@chromium.org>
2017-04-04 14:26:52 -04:00
the same **--annotation**, **--database**, **--monitor-self-annotation**,
**--no-rate-limit**, **--no-upload-gzip**, and **--url** arguments as the
Don’t attempt to do periodic tasks in a secondary crashpad_handler 76a67a37b1d0 adds crashpad_handler’s --monitor-self argument, which results in a second crashpad_handler instance running out of the same database as the initial crashpad_handler instance that it monitors. The two handlers start at nearly the same time, and will initially be on precisely the same schedule for periodic tasks such as scanning for new reports to upload and pruning the database. This is an unnecessary duplication of effort. This adds a new --no-periodic-tasks argument to crashpad_handler. When the first instance of crashpad_handler starts a second to monitor it, it will use this argument, which prevents the second instance from performing these tasks. When --no-periodic-tasks is in effect, crashpad_handler will still be able to upload crash reports that it knows about by virtue of having written them itself, but it will not scan the database for other pending reports to upload. Bug: crashpad:143 Test: crashpad_util_test ThreadSafeVector.ThreadSafeVector Change-Id: I7b249dd7b6d5782448d8071855818f986b98ab5a Reviewed-on: https://chromium-review.googlesource.com/473827 Reviewed-by: Robert Sesek <rsesek@chromium.org>
2017-04-14 14:50:11 -04:00
original one. The second instance will always be started with a
**--no-periodic-tasks** argument, and will not be started with a
handler: Add --monitor-self-annotations --monitor-self-annotations allows the Crashpad-using application to push module-level annotations in to crashpad_handler. These annotations will appear in any crash report written for that handler by --monitor-self. Bug: crashpad:143 Change-Id: If47395da75a90be4f4bdce0630ce95ea93f9fcf3 Reviewed-on: https://chromium-review.googlesource.com/467746 Reviewed-by: Scott Graham <scottmg@chromium.org>
2017-04-04 14:26:52 -04:00
**--metrics-dir** argument even if the original instance was.
Add the --monitor-self argument to crashpad_handler https://crbug.com/678959 added “fallback” crash reporting for crashpad_handler on Windows, in a Chrome- and Windows-specific way. This implements a more general self-monitor mechanism that will work on multiple platforms and in the absence of Chrome. When starting crashpad_handler (let’s call it the “first instance”) with --monitor-self, it will start another crashpad_handler (the “second instance”). The second instance monitors the first one for crashes. The second instance will be started in mostly the same way as the first instance, except --monitor-self will not be provided to the second instance. Bug: crashpad:143 Change-Id: I76f3f47d1762d8ecae1814357cb672c8b7bd5e95 Reviewed-on: https://chromium-review.googlesource.com/466267 Reviewed-by: Sigurður Ásgeirsson <siggi@chromium.org> Reviewed-by: Scott Graham <scottmg@chromium.org>
2017-04-04 10:08:56 -04:00
Where supported by the underlying operating system, the second instance will
be restarted should it exit before the first instance. The second instance
will not be eligible to be started asynchronously.
handler: Add --monitor-self-annotations --monitor-self-annotations allows the Crashpad-using application to push module-level annotations in to crashpad_handler. These annotations will appear in any crash report written for that handler by --monitor-self. Bug: crashpad:143 Change-Id: If47395da75a90be4f4bdce0630ce95ea93f9fcf3 Reviewed-on: https://chromium-review.googlesource.com/467746 Reviewed-by: Scott Graham <scottmg@chromium.org>
2017-04-04 14:26:52 -04:00
* **--monitor-self-annotation**=_KEY_=_VALUE_
Sets a module-level annotation mapping _KEY_ to _VALUE_ in the Crashpad
handler. This option may appear zero, one, or more times.
If **--monitor-self** is in use, the second instance of the Crashpad handler
program will find these annotations stored in the original instance and will
include them in any crash reports written for the original instance.
These annotations will only appear in crash reports written for the Crashpad
handler itself. To apply a process-level annotation to all crash reports
written by an instance of the Crashpad handler, use **--annotation** instead.
Add the --monitor-self argument to crashpad_handler https://crbug.com/678959 added “fallback” crash reporting for crashpad_handler on Windows, in a Chrome- and Windows-specific way. This implements a more general self-monitor mechanism that will work on multiple platforms and in the absence of Chrome. When starting crashpad_handler (let’s call it the “first instance”) with --monitor-self, it will start another crashpad_handler (the “second instance”). The second instance monitors the first one for crashes. The second instance will be started in mostly the same way as the first instance, except --monitor-self will not be provided to the second instance. Bug: crashpad:143 Change-Id: I76f3f47d1762d8ecae1814357cb672c8b7bd5e95 Reviewed-on: https://chromium-review.googlesource.com/466267 Reviewed-by: Sigurður Ásgeirsson <siggi@chromium.org> Reviewed-by: Scott Graham <scottmg@chromium.org>
2017-04-04 10:08:56 -04:00
* **--monitor-self-argument**=_ARGUMENT_
When directed by **--monitor-self** to start a second instance of the
Crashpad handler program, the second instance will be started with _ARGUMENT_
as one of its arguments. This option may appear zero, one, or more times.
This option has no effect in the absence of **--monitor-self**.
This supports embedding the Crashpad handler into a multi-purpose executable
that dispatches to the desired entry point based on a command-line argument.
To prevent excessive accumulation of handler processes, _ARGUMENT_ must not
be `--monitor-self`.
linux: Implement StartHandler() This CL adds a RequestCrashDumpHandler to request a crash dump over a socket. Common functionality with LaunchAtCrashHandler is factored out into a SignalHandler base class. Bug: crashpad:284 Change-Id: I86293ef599a0dd6eea63c096a5c931c620c05ecc Reviewed-on: https://chromium-review.googlesource.com/c/crashpad/crashpad/+/1568985 Reviewed-by: Mark Mentovai <mark@chromium.org>
2019-05-01 22:19:21 -07:00
* **--no-identify-client-via-url**
Do not add client-identifying fields to the URL. By default, `"prod"`,
`"ver"`, and `"guid"` annotations are added to the upload URL as name-value
pairs `"product"`, `"version"`, and `"guid"`, respectively. Using this
option disables that behavior.
Don’t attempt to do periodic tasks in a secondary crashpad_handler 76a67a37b1d0 adds crashpad_handler’s --monitor-self argument, which results in a second crashpad_handler instance running out of the same database as the initial crashpad_handler instance that it monitors. The two handlers start at nearly the same time, and will initially be on precisely the same schedule for periodic tasks such as scanning for new reports to upload and pruning the database. This is an unnecessary duplication of effort. This adds a new --no-periodic-tasks argument to crashpad_handler. When the first instance of crashpad_handler starts a second to monitor it, it will use this argument, which prevents the second instance from performing these tasks. When --no-periodic-tasks is in effect, crashpad_handler will still be able to upload crash reports that it knows about by virtue of having written them itself, but it will not scan the database for other pending reports to upload. Bug: crashpad:143 Test: crashpad_util_test ThreadSafeVector.ThreadSafeVector Change-Id: I7b249dd7b6d5782448d8071855818f986b98ab5a Reviewed-on: https://chromium-review.googlesource.com/473827 Reviewed-by: Robert Sesek <rsesek@chromium.org>
2017-04-14 14:50:11 -04:00
* **--no-periodic-tasks**
Do not scan for new pending crash reports or prune the crash report database.
Only crash reports recorded by this instance of the Crashpad handler will
become eligible for upload in this instance, and only a single initial upload
attempt will be made.
This option is not intended for general use. It is provided to prevent
multiple instances of the Crashpad handler from duplicating the effort of
performing the same periodic tasks. In normal use, the first instance of the
Crashpad handler will assume the responsibility for performing these tasks,
and will provide this argument to any second instance. See
**--monitor-self**.
Convert AsciiDoc documentation to Markdown Most of the world, including the Chromium universe, seems to be standardizing on Markdown for documentation. Markdown provides the benefit of automatic rendering on Gitiles (Gerrit), and on GitHub mirrors as well. Crashpad should fit in with its surroundings. There are two quirks that I was unable to resolve. - Markdown does not allow **emphasis** within a ```code fence``` region. In blocks showing interactive examples, the AsciiDoc documentation used this to highlight what the user was expected to type. - Markdown does not have a “definition list” (<dl>). This would have been nice in man pages for the Options and Exit Status sections. In its place, I used unnumbered lists. This is a little ugly, but it’s not the end of the world. The new Markdown-formatted documentation is largely identical to the AsciiDoc that it replaces. Minor editorial revisions were made. References to Mac OS X now mention macOS, and tool man pages describing tools that that access task ports now mention System Integrity Protection (SIP). The AppEngine-based https://crashpad.chromium.org/ app in doc/appengine is still necessary to serve Doxygen-generated documentation. This app is updated to redirect existing generated-HTML URLs to Gitiles’ automatic Markdown rendering. Scripts in doc/support are updated to adapt to this change. All AsciiDoc support files in doc/support have been removed. BUG=crashpad:138 Change-Id: I15ad423d5b7aa1b7aa2ed1d2cb72639eec7c81aa Reviewed-on: https://chromium-review.googlesource.com/408256 Reviewed-by: Robert Sesek <rsesek@chromium.org> Reviewed-by: Scott Graham <scottmg@chromium.org>
2016-11-04 17:10:36 -04:00
* **--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.
Use zlib to gzip-compress uploads This adds zlib to Crashpad. By default in standalone Crashpad builds, the system zlib will be used where available. A copy of Chromium’s zlib (currently a slightly patched 1.2.11) is checked out via DEPS into third_party for use on Windows, which does not have a system zlib. zlib is used to produce gzip streams for HTTP upload request bodies sent by crashpad_handler by default. The Content-Encoding: gzip header is set for these compressed request bodies. Compression can be disabled for upload to servers without corresponding decompression support by starting crashpad_handler with the --no-upload-gzip option. Most minidumps compress quite well with zlib. A size reduction of 90% is not uncommon. BUG=crashpad:157 TEST=crashpad_util_test GzipHTTPBodyStream.*:HTTPTransport.* Change-Id: I99b86db3952c3685cd78f5dc858a60b54399c513 Reviewed-on: https://chromium-review.googlesource.com/438585 Reviewed-by: Robert Sesek <rsesek@chromium.org>
2017-02-15 19:54:19 -05:00
* **--no-upload-gzip**
Do not use `gzip` compression for uploaded crash reports. Normally, the
entire request body is compressed into a `gzip` stream and transmitted with
`Content-Encoding: gzip`. This option disables compression, and is intended
for use with collection servers that don’t accept uploads compressed in this
way.
[log minidump] add option to log minidump in handler_main - Add option to log minidump in handler_main, also add option to disable to dump minidump and generate report. - Implement log minidump in CrashReportExceptionHandler. Bug: crashpad:308 Change-Id: I8d2f7e118912011a8416f1ec36c9ee9d561d06e6 Reviewed-on: https://chromium-review.googlesource.com/c/crashpad/crashpad/+/1995825 Commit-Queue: Tao Bai <michaelbai@chromium.org> Reviewed-by: Joshua Peraza <jperaza@chromium.org>
2020-01-28 12:02:55 -08:00
* **--no-write-minidump-to-database**
Do not write the minidump to database. Normally, the minidump is written to
database for upload. Use this option with **--write-minidump-to-log** to
only write the minidump to log. This option is only available to Android.
Convert AsciiDoc documentation to Markdown Most of the world, including the Chromium universe, seems to be standardizing on Markdown for documentation. Markdown provides the benefit of automatic rendering on Gitiles (Gerrit), and on GitHub mirrors as well. Crashpad should fit in with its surroundings. There are two quirks that I was unable to resolve. - Markdown does not allow **emphasis** within a ```code fence``` region. In blocks showing interactive examples, the AsciiDoc documentation used this to highlight what the user was expected to type. - Markdown does not have a “definition list” (<dl>). This would have been nice in man pages for the Options and Exit Status sections. In its place, I used unnumbered lists. This is a little ugly, but it’s not the end of the world. The new Markdown-formatted documentation is largely identical to the AsciiDoc that it replaces. Minor editorial revisions were made. References to Mac OS X now mention macOS, and tool man pages describing tools that that access task ports now mention System Integrity Protection (SIP). The AppEngine-based https://crashpad.chromium.org/ app in doc/appengine is still necessary to serve Doxygen-generated documentation. This app is updated to redirect existing generated-HTML URLs to Gitiles’ automatic Markdown rendering. Scripts in doc/support are updated to adapt to this change. All AsciiDoc support files in doc/support have been removed. BUG=crashpad:138 Change-Id: I15ad423d5b7aa1b7aa2ed1d2cb72639eec7c81aa Reviewed-on: https://chromium-review.googlesource.com/408256 Reviewed-by: Robert Sesek <rsesek@chromium.org> Reviewed-by: Scott Graham <scottmg@chromium.org>
2016-11-04 17:10:36 -04:00
* **--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.
linux: Implement StartHandler() This CL adds a RequestCrashDumpHandler to request a crash dump over a socket. Common functionality with LaunchAtCrashHandler is factored out into a SignalHandler base class. Bug: crashpad:284 Change-Id: I86293ef599a0dd6eea63c096a5c931c620c05ecc Reviewed-on: https://chromium-review.googlesource.com/c/crashpad/crashpad/+/1568985 Reviewed-by: Mark Mentovai <mark@chromium.org>
2019-05-01 22:19:21 -07:00
* **--sanitization-information**=_SANITIZATION-INFORMATION-ADDRESS_
Provides sanitization settings in a SanitizationInformation struct at
_SANITIZATION-INFORMATION-ADDRESS_. This option requires
**--trace-parent-with-exception** and is only valid on Linux platforms.
* **--shared-client-connection**
Indicates that the file descriptor provided by **--initial-client-fd** is
shared among mulitple clients. Using a broker process is not supported for
clients using this option. This option is only valid on Linux platforms.
Add handler options for Linux/Android Add the options: --trace-parent-with-exception=<address> which traces the handler's parent process which has an ExceptionInformation struct at <address>. --initial-client-fd=<fd> which starts the handler server with an already connected client on socket <fd>. Bug: crashpad:30 Change-Id: Ied9760ca125a16f56173afdc56dff5fcb79d2eea Reviewed-on: https://chromium-review.googlesource.com/922895 Commit-Queue: Joshua Peraza <jperaza@chromium.org> Reviewed-by: Mark Mentovai <mark@chromium.org>
2018-02-20 15:03:14 -08:00
* **--trace-parent-with-exception**=_EXCEPTION-INFORMATION-ADDRESS_
Causes the handler process to trace its parent process and exit. The parent
process should have an ExceptionInformation struct at
linux: Implement StartHandler() This CL adds a RequestCrashDumpHandler to request a crash dump over a socket. Common functionality with LaunchAtCrashHandler is factored out into a SignalHandler base class. Bug: crashpad:284 Change-Id: I86293ef599a0dd6eea63c096a5c931c620c05ecc Reviewed-on: https://chromium-review.googlesource.com/c/crashpad/crashpad/+/1568985 Reviewed-by: Mark Mentovai <mark@chromium.org>
2019-05-01 22:19:21 -07:00
_EXCEPTION-INFORMATION-ADDRESS_. This option is only valid on Linux
platforms.
Add handler options for Linux/Android Add the options: --trace-parent-with-exception=<address> which traces the handler's parent process which has an ExceptionInformation struct at <address>. --initial-client-fd=<fd> which starts the handler server with an already connected client on socket <fd>. Bug: crashpad:30 Change-Id: Ied9760ca125a16f56173afdc56dff5fcb79d2eea Reviewed-on: https://chromium-review.googlesource.com/922895 Commit-Queue: Joshua Peraza <jperaza@chromium.org> Reviewed-by: Mark Mentovai <mark@chromium.org>
2018-02-20 15:03:14 -08:00
Convert AsciiDoc documentation to Markdown Most of the world, including the Chromium universe, seems to be standardizing on Markdown for documentation. Markdown provides the benefit of automatic rendering on Gitiles (Gerrit), and on GitHub mirrors as well. Crashpad should fit in with its surroundings. There are two quirks that I was unable to resolve. - Markdown does not allow **emphasis** within a ```code fence``` region. In blocks showing interactive examples, the AsciiDoc documentation used this to highlight what the user was expected to type. - Markdown does not have a “definition list” (<dl>). This would have been nice in man pages for the Options and Exit Status sections. In its place, I used unnumbered lists. This is a little ugly, but it’s not the end of the world. The new Markdown-formatted documentation is largely identical to the AsciiDoc that it replaces. Minor editorial revisions were made. References to Mac OS X now mention macOS, and tool man pages describing tools that that access task ports now mention System Integrity Protection (SIP). The AppEngine-based https://crashpad.chromium.org/ app in doc/appengine is still necessary to serve Doxygen-generated documentation. This app is updated to redirect existing generated-HTML URLs to Gitiles’ automatic Markdown rendering. Scripts in doc/support are updated to adapt to this change. All AsciiDoc support files in doc/support have been removed. BUG=crashpad:138 Change-Id: I15ad423d5b7aa1b7aa2ed1d2cb72639eec7c81aa Reviewed-on: https://chromium-review.googlesource.com/408256 Reviewed-by: Robert Sesek <rsesek@chromium.org> Reviewed-by: Scott Graham <scottmg@chromium.org>
2016-11-04 17:10:36 -04:00
* **--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.
android, chromeos: fix build breakages Also augment some documentation. Change-Id: Icbb8bdbe435484346f2b24e37f81182a3f189cb5 Reviewed-on: https://chromium-review.googlesource.com/c/crashpad/crashpad/+/1797189 Commit-Queue: Joshua Peraza <jperaza@chromium.org> Reviewed-by: Mark Mentovai <mark@chromium.org>
2019-09-11 10:37:54 -07:00
* **--use-cros-crash-reporter**
Causes crash reports to be passed via an in-memory file to
`/sbin/crash_reporter` instead of storing them in the database. The database
is still used for Crashpad settings. This option is only valid on Chromium
OS.
[log minidump] add option to log minidump in handler_main - Add option to log minidump in handler_main, also add option to disable to dump minidump and generate report. - Implement log minidump in CrashReportExceptionHandler. Bug: crashpad:308 Change-Id: I8d2f7e118912011a8416f1ec36c9ee9d561d06e6 Reviewed-on: https://chromium-review.googlesource.com/c/crashpad/crashpad/+/1995825 Commit-Queue: Tao Bai <michaelbai@chromium.org> Reviewed-by: Joshua Peraza <jperaza@chromium.org>
2020-01-28 12:02:55 -08:00
* **--write-minidump-to-log**
Write the minidump to log. By default the minidump is only written to
database. Use this option with **--no-write-minidump-to-database** to only
write the minidump to log. This option is only available to Android.
Convert AsciiDoc documentation to Markdown Most of the world, including the Chromium universe, seems to be standardizing on Markdown for documentation. Markdown provides the benefit of automatic rendering on Gitiles (Gerrit), and on GitHub mirrors as well. Crashpad should fit in with its surroundings. There are two quirks that I was unable to resolve. - Markdown does not allow **emphasis** within a ```code fence``` region. In blocks showing interactive examples, the AsciiDoc documentation used this to highlight what the user was expected to type. - Markdown does not have a “definition list” (<dl>). This would have been nice in man pages for the Options and Exit Status sections. In its place, I used unnumbered lists. This is a little ugly, but it’s not the end of the world. The new Markdown-formatted documentation is largely identical to the AsciiDoc that it replaces. Minor editorial revisions were made. References to Mac OS X now mention macOS, and tool man pages describing tools that that access task ports now mention System Integrity Protection (SIP). The AppEngine-based https://crashpad.chromium.org/ app in doc/appengine is still necessary to serve Doxygen-generated documentation. This app is updated to redirect existing generated-HTML URLs to Gitiles’ automatic Markdown rendering. Scripts in doc/support are updated to adapt to this change. All AsciiDoc support files in doc/support have been removed. BUG=crashpad:138 Change-Id: I15ad423d5b7aa1b7aa2ed1d2cb72639eec7c81aa Reviewed-on: https://chromium-review.googlesource.com/408256 Reviewed-by: Robert Sesek <rsesek@chromium.org> Reviewed-by: Scott Graham <scottmg@chromium.org>
2016-11-04 17:10:36 -04:00
* **--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.
Reference in New Issue Copy Permalink