diff --git a/README.md b/README.md new file mode 100644 index 00000000..c7be545e --- /dev/null +++ b/README.md @@ -0,0 +1,41 @@ + + +# Crashpad + +[Crashpad](https://crashpad.chromium.org/) is a crash-reporting system. + +## Documentation + + * [Project status](doc/status.md) + * [Developing Crashpad](doc/developing.md): instructions for getting the source + code, building, testing, and contributing to the project. + * [Crashpad interface documentation](https://crashpad.chromium.org/doxygen/) + * [Crashpad tool man pages](https://crashpad.chromium.org/man/) + +## Source Code + +Crashpad’s source code is hosted in a Git repository at +https://chromium.googlesource.com/crashpad/crashpad. + +## Other Links + + * Bugs can be reported at the [Crashpad issue + tracker](https://crashpad.chromium.org/bug/). + * The [Crashpad Buildbot](https://build.chromium.org/p/client.crashpad) + performs automated builds and tests. + * [crashpad-dev](https://groups.google.com/a/chromium.org/group/crashpad-dev) + is the Crashpad developers’ mailing list. diff --git a/doc/appengine/README b/doc/appengine/README index 00a7f761..b92e311b 100644 --- a/doc/appengine/README +++ b/doc/appengine/README @@ -1,7 +1,7 @@ This is the App Engine app that serves https://crashpad.chromium.org/. To work on this app, obtain the App Engine SDK for Go from -https://cloud.google.com/appengine/downloads. Unpacking it produces a +https://cloud.google.com/appengine/docs/go/download. Unpacking it produces a go_appengine directory. This may be added to your $PATH for convenience, although it is not necessary. @@ -19,7 +19,7 @@ $ GOROOT=…/go_appengine/goroot GOPATH=…/go_appengine/gopath go get -d To test locally: -$ goapp serve +$ …/go_appengine/goapp serve Look for the “Starting module "default" running at: http://localhost:8080” line, which tells you the URL of the local running instance of the app. diff --git a/doc/appengine/main.go b/doc/appengine/main.go index e05870f5..adcf6716 100644 --- a/doc/appengine/main.go +++ b/doc/appengine/main.go @@ -37,31 +37,49 @@ func init() { func handler(w http.ResponseWriter, r *http.Request) { const ( - baseURL = "https://chromium.googlesource.com/crashpad/crashpad/+/doc/doc/generated/?format=TEXT" - bugBaseURL = "https://bugs.chromium.org/p/crashpad/" + baseURL = "https://chromium.googlesource.com/crashpad/crashpad/+/" + masterBaseURL = baseURL + "master/" + generatedDocBaseURL = baseURL + "doc/doc/generated/?format=TEXT" + bugBaseURL = "https://bugs.chromium.org/p/crashpad/" ) + redirectMap := map[string]string{ + "/": masterBaseURL + "README.md", + "/bug": bugBaseURL, + "/bug/": bugBaseURL, + "/bug/new": bugBaseURL + "issues/entry", + "/doc/developing.html": masterBaseURL + "/doc/developing.md", + "/doc/status.html": masterBaseURL + "/doc/status.md", + "/man/catch_exception_tool.html": masterBaseURL + "tools/mac/catch_exception_tool.md", + "/man/crashpad_database_util.html": masterBaseURL + "tools/crashpad_database_util.md", + "/man/crashpad_handler.html": masterBaseURL + "handler/crashpad_handler.md", + "/man/exception_port_tool.html": masterBaseURL + "tools/mac/exception_port_tool.md", + "/man/generate_dump.html": masterBaseURL + "tools/generate_dump.md", + "/man/on_demand_service_tool.html": masterBaseURL + "tools/mac/on_demand_service_tool.md", + "/man/run_with_crashpad.html": masterBaseURL + "tools/mac/run_with_crashpad.md", + } + ctx := appengine.NewContext(r) client := urlfetch.Client(ctx) + destinationURL, exists := redirectMap[r.URL.Path] + if exists { + http.Redirect(w, r, destinationURL, http.StatusFound) + return + } + + if strings.HasPrefix(r.URL.Path, "/bug/") { + http.Redirect(w, r, bugBaseURL+"issues/detail?id="+r.URL.Path[5:], http.StatusFound) + return + } + // Don’t show dotfiles. if strings.HasPrefix(path.Base(r.URL.Path), ".") { http.Error(w, http.StatusText(http.StatusNotFound), http.StatusNotFound) return } - if r.URL.Path == "/bug" || r.URL.Path == "/bug/" { - http.Redirect(w, r, bugBaseURL, http.StatusFound) - return - } else if r.URL.Path == "/bug/new" { - http.Redirect(w, r, bugBaseURL+"issues/entry", http.StatusFound) - return - } else if strings.HasPrefix(r.URL.Path, "/bug/") { - http.Redirect(w, r, bugBaseURL+"issues/detail?id="+r.URL.Path[5:], http.StatusFound) - return - } - - u, err := url.Parse(baseURL) + u, err := url.Parse(generatedDocBaseURL) if err != nil { http.Error(w, err.Error(), http.StatusInternalServerError) return diff --git a/doc/developing.ad b/doc/developing.ad deleted file mode 100644 index a8aafcf1..00000000 --- a/doc/developing.ad +++ /dev/null @@ -1,323 +0,0 @@ -// Copyright 2015 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: article - -= Developing Crashpad - -== Status - -link:status.html[Project status] information has moved to its own page. - -== Introduction - -Crashpad is a https://dev.chromium.org/Home[Chromium project]. Most of -its development practices follow Chromium’s. In order to function on its -own in other projects, Crashpad uses -https://chromium.googlesource.com/chromium/mini_chromium/[mini_chromium], -a small, self-contained library that provides many of Chromium’s useful -low-level base routines. -https://chromium.googlesource.com/chromium/mini_chromium/+/master/README[mini_chromium’s -README] provides more detail. - -== Prerequisites - -To develop Crashpad, the following tools are necessary, and must be -present in the `$PATH` environment variable: - - * Chromium’s - https://dev.chromium.org/developers/how-tos/depottools[depot_tools]. - * https://git-scm.com/[Git]. This is provided by Xcode on Mac OS X and by - depot_tools on Windows. - * https://www.python.org/[Python]. This is provided by the operating system on - Mac OS X, and by depot_tools on Windows. - * Appropriate development tools. For Mac OS X, this is - https://developer.apple.com/xcode/[Xcode], and for Windows, it’s - https://www.visualstudio.com/[Visual Studio]. - -== Getting the Source Code - -The main source code repository is a Git repository hosted at -https://chromium.googlesource.com/crashpad/crashpad. Although it is possible to -check out this repository directly with `git clone`, Crashpad’s dependencies are -managed by -https://dev.chromium.org/developers/how-tos/depottools#TOC-gclient[`gclient`] -instead of Git submodules, so to work on Crashpad, it is best to use `fetch` to -get the source code. - -`fetch` and `gclient` are part of the -https://dev.chromium.org/developers/how-tos/depottools[depot_tools]. There’s no -need to install them separately. - -=== Initial Checkout - -[subs="verbatim,quotes"] ----- -$ *mkdir \~/crashpad* -$ *cd ~/crashpad* -$ *fetch crashpad* ----- - -`fetch crashpad` performs the initial `git clone` and `gclient sync`, -establishing a fully-functional local checkout. - -=== Subsequent Checkouts - -[subs="verbatim,quotes"] ----- -$ *cd ~/crashpad/crashpad* -$ *git pull -r* -$ *gclient sync* ----- - -== Building - -Crashpad uses https://gyp.gsrc.io/[GYP] to generate -https://ninja-build.org/[Ninja] build files. The build is described by `.gyp` -files throughout the Crashpad source code tree. The `build/gyp_crashpad.py` -script runs GYP properly for Crashpad, and is also called when you run `fetch -crashpad`, `gclient sync`, or `gclient runhooks`. - -The Ninja build files and build output are in the `out` directory. Both debug- -and release-mode configurations are available. The examples below show the debug -configuration. To build and test the release configuration, substitute `Release` -for `Debug`. - -[subs="verbatim,quotes"] ----- -$ *cd ~/crashpad/crashpad* -$ *ninja -C out/Debug* ----- - -Ninja is part of the -https://dev.chromium.org/developers/how-tos/depottools[depot_tools]. There’s no -need to install it separately. - -=== Android - -Crashpad’s Android port is in its early stages. This build relies on -cross-compilation. It’s possible to develop Crashpad for Android on any platform -that the https://developer.android.com/ndk/[Android NDK (Native Development -Kit)] runs on. - -If it’s not already present on your system, -https://developer.android.com/ndk/downloads/[download the NDK package for your -system] and expand it to a suitable location. These instructions assume that -it’s been expanded to `~/android-ndk-r13`. - -To build Crashpad, portions of the NDK must be reassembled into a -https://developer.android.com/ndk/guides/standalone_toolchain.html[standalone -toolchain]. This is a repackaged subset of the NDK suitable for cross-compiling -for a single Android architecture (such as `arm`, `arm64`, `x86`, and `x86_64`) -targeting a specific -https://source.android.com/source/build-numbers.html[Android API level]. The -standalone toolchain only needs to be built from the NDK one time for each set -of options desired. To build a standalone toolchain targeting 64-bit ARM and API -level 21 (Android 5.0 “Lollipop”), run: - -[subs="verbatim,quotes"] ----- -$ *cd ~* -$ *python android-ndk-r13/build/tools/make_standalone_toolchain.py \ - --arch=arm64 --api=21 --install-dir=android-ndk-r13_arm64_api21* ----- - -Note that Chrome uses Android API level 21 for 64-bit platforms and 16 for -32-bit platforms. See Chrome’s -https://chromium.googlesource.com/chromium/src/+/master/build/config/android/config.gni[`build/config/android/config.gni`] -which sets `_android_api_level` and `_android64_api_level`. - -To configure a Crashpad build for Android using this standalone toolchain, -set several environment variables directing the build to the standalone -toolchain, along with GYP options to identify an Android build. This must be -done after any `gclient sync`, or instead of any `gclient runhooks` operation. -The environment variables only need to be set for this `gyp_crashpad.py` -invocation, and need not be permanent. - -[subs="verbatim,quotes"] ----- -$ *cd \~/crashpad/crashpad* -$ *CC_target=\~/android-ndk-r13_arm64_api21/bin/clang \ - CXX_target=\~/android-ndk-r13_arm64_api21/bin/clang++ \ - AR_target=\~/android-ndk-r13_arm64_api21/bin/aarch64-linux-android-ar \ - NM_target=\~/android-ndk-r13_arm64_api21/bin/aarch64-linux-android-nm \ - READELF_target=~/android-ndk-r13_arm64_api21/bin/aarch64-linux-android-readelf \ - python build/gyp_crashpad.py \ - -DOS=android -Dtarget_arch=arm64 -Dclang=1 \ - --generator-output=out_android_arm64_api21 -f ninja-android* ----- - -Target “triplets” to use for `ar`, `nm`, and `readelf` are: - -[width="40%",cols="1,3",frame="topbot"] -|=== -|`arm` |`arm-linux-androideabi` -|`arm64` |`aarch64-linux-android` -|`x86` |`i686-linux-android` -|`x86_64` |`x86_64-linux-android` -|=== - -The port is incomplete, but targets known to be working include `crashpad_util`, -`crashpad_test`, and `crashpad_test_test`. This list will grow over time. To -build, direct `ninja` to the specific `out` directory chosen by -`--generator-output` above. - -[subs="verbatim,quotes"] ----- -$ *ninja -C out_android_arm64_api21/out/Debug crashpad_test_test* ----- - -== Testing - -Crashpad uses https://github.com/google/googletest/[Google Test] as its -unit-testing framework, and some tests use -https://github.com/google/googletest/tree/master/googlemock/[Google Mock] as -well. Its tests are currently split up into several test executables, each -dedicated to testing a different component. This may change in the future. After -a successful build, the test executables will be found at -`out/Debug/crashpad_*_test`. - -[subs="verbatim,quotes"] ----- -$ *cd ~/crashpad/crashpad* -$ *out/Debug/crashpad_minidump_test* -$ *out/Debug/crashpad_util_test* ----- - -A script is provided to run all of Crashpad’s tests. It accepts a single -argument that tells it which configuration to test. - -[subs="verbatim,quotes"] ----- -$ *cd ~/crashpad/crashpad* -$ *python build/run_tests.py Debug* ----- - -=== Android - -To test on Android, use -https://developer.android.com/studio/command-line/adb.html[ADB (Android Debug -Bridge)] to `adb push` test executables and test data to a device or emulator, -then use `adb shell` to get a shell to run the test executables from. ADB is -part of the https://developer.android.com/sdk/[Android SDK]. Note that it is -sufficient to install just the command-line tools. The entire Android Studio IDE -is not necessary to obtain ADB. - -This example runs `crashpad_test_test` on a device. This test executable has a -run-time dependency on a second executable and a test data file, which are also -transferred to the device prior to running the test. - -[subs="verbatim,quotes"] ----- -$ *cd ~/crashpad/crashpad* -$ *adb push out_android_arm64_api21/out/Debug/crashpad_test_test /data/local/tmp/* -[100%] /data/local/tmp/crashpad_test_test -$ *adb push \ - out_android_arm64_api21/out/Debug/crashpad_test_test_multiprocess_exec_test_child \ - /data/local/tmp/* -[100%] /data/local/tmp/crashpad_test_test_multiprocess_exec_test_child -$ *adb shell mkdir -p /data/local/tmp/crashpad_test_data_root/test* -$ *adb push test/paths_test_data_root.txt \ - /data/local/tmp/crashpad_test_data_root/test/* -[100%] /data/local/tmp/crashpad_test_data_root/test/paths_test_data_root.txt -$ *adb shell* -device:/ $ *cd /data/local/tmp* -device:/data/local/tmp $ *CRASHPAD_TEST_DATA_ROOT=crashpad_test_data_root \ - ./crashpad_test_test* ----- - -== Contributing - -Crashpad’s contribution process is very similar to -https://dev.chromium.org/developers/contributing-code[Chromium’s contribution -process]. - -=== Code Review - -A code review must be conducted for every change to Crashpad’s source code. Code -review is conducted on https://chromium-review.googlesource.com/[Chromium’s -Gerrit] system, and all code reviews must be sent to an appropriate reviewer, -with a Cc sent to -https://groups.google.com/a/chromium.org/group/crashpad-dev[crashpad-dev]. The -https://chromium.googlesource.com/crashpad/crashpad/+/master/codereview.settings[`codereview.settings`] -file specifies this environment to `git-cl`. - -`git-cl` is part of the -https://dev.chromium.org/developers/how-tos/depottools[depot_tools]. There’s no -need to install it separately. - -[subs="verbatim,quotes"] ----- -$ *cd ~/crashpad/crashpad* -$ *git checkout -b work_branch origin/master* -_…do some work…_ -$ *git add …* -$ *git commit* -$ *git cl upload* ----- - -The https://polygerrit.appspot.com/[PolyGerrit interface] to Gerrit, undergoing -active development, is recommended. To switch from the classic GWT-based Gerrit -UI to PolyGerrit, click the PolyGerrit link in a Gerrit review page’s footer. - -Uploading a patch to Gerrit does not automatically request a review. You must -select a reviewer on the Gerrit review page after running `git cl upload`. This -action notifies your reviewer of the code review request. If you have lost track -of the review page, `git cl issue` will remind you of its URL. Alternatively, -you can request review when uploading to Gerrit by using `git cl upload ---send-mail`. - -Git branches maintain their association with Gerrit reviews, so if you need to -make changes based on review feedback, you can do so on the correct Git branch, -committing your changes locally with `git commit`. You can then upload a new -patch set with `git cl upload` and let your reviewer know you’ve addressed the -feedback. - -=== Landing Changes - -After code review is complete and “Code-Review: +1” has been received from all -reviewers, project members can commit the patch themselves: - -[subs="verbatim,quotes"] ----- -$ *cd ~/crashpad/crashpad* -$ *git checkout work_branch* -$ *git cl land* ----- - -Alternatively, patches can be committed by clicking the “Submit” button in the -Gerrit UI. - -Crashpad does not currently have a -https://dev.chromium.org/developers/testing/commit-queue[commit queue], so -contributors who are not project members will have to ask a project member to -commit the patch for them. Project members can commit changes on behalf of -external contributors by clicking the “Submit” button in the Gerrit UI. - -=== External Contributions - -Copyright holders must complete the -https://developers.google.com/open-source/cla/individual[Individual Contributor -License Agreement] or -https://developers.google.com/open-source/cla/corporate[Corporate Contributor -License Agreement] as appropriate before any submission can be accepted, and -must be listed in the `AUTHORS` file. Contributors may be listed in the -`CONTRIBUTORS` file. - -== Buildbot - -The https://build.chromium.org/p/client.crashpad/[Crashpad Buildbot] performs -automated builds and tests of Crashpad. Before checking out or updating the -Crashpad source code, and after checking in a new change, it is prudent to check -the Buildbot to ensure that “the tree is green.” diff --git a/doc/developing.md b/doc/developing.md new file mode 100644 index 00000000..71e10404 --- /dev/null +++ b/doc/developing.md @@ -0,0 +1,310 @@ + + +# Developing Crashpad + +## Status + +[Project status](status.md) information has moved to its own page. + +## Introduction + +Crashpad is a [Chromium project](https://dev.chromium.org/Home). Most of its +development practices follow Chromium’s. In order to function on its own in +other projects, Crashpad uses +[mini_chromium](https://chromium.googlesource.com/chromium/mini_chromium/), a +small, self-contained library that provides many of Chromium’s useful low-level +base routines. [mini_chromium’s +README](https://chromium.googlesource.com/chromium/mini_chromium/+/master/README) +provides more detail. + +## Prerequisites + +To develop Crashpad, the following tools are necessary, and must be +present in the `$PATH` environment variable: + + * Chromium’s + [depot_tools](https://dev.chromium.org/developers/how-tos/depottools). + * [Git](https://git-scm.com/). This is provided by Xcode on macOS and by + depot_tools on Windows. + * [Python](https://www.python.org/). This is provided by the operating system + on macOS, and by depot_tools on Windows. + * Appropriate development tools. For macOS, this is + [Xcode](https://developer.apple.com/xcode/) and for Windows, it’s [Visual + Studio](https://www.visualstudio.com/). + +## Getting the Source Code + +The main source code repository is a Git repository hosted at +https://chromium.googlesource.com/crashpad/crashpad. Although it is possible to +check out this repository directly with `git clone`, Crashpad’s dependencies are +managed by +[`gclient`](https://dev.chromium.org/developers/how-tos/depottools#TOC-gclient) +instead of Git submodules, so to work on Crashpad, it is best to use `fetch` to +get the source code. + +`fetch` and `gclient` are part of the +[depot_tools](https://dev.chromium.org/developers/how-tos/depottools). There’s +no need to install them separately. + +### Initial Checkout + +``` +$ mkdir ~/crashpad +$ cd ~/crashpad +$ fetch crashpad +``` + +`fetch crashpad` performs the initial `git clone` and `gclient sync`, +establishing a fully-functional local checkout. + +### Subsequent Checkouts + +``` +$ cd ~/crashpad/crashpad +$ git pull -r +$ gclient sync +``` + +## Building + +Crashpad uses [GYP](https://gyp.gsrc.io/) to generate +[Ninja](https://ninja-build.org/) build files. The build is described by `.gyp` +files throughout the Crashpad source code tree. The +[`build/gyp_crashpad.py`](https://chromium.googlesource.com/crashpad/crashpad/+/master/build/gyp_crashpad.py) +script runs GYP properly for Crashpad, and is also called when you run `fetch +crashpad`, `gclient sync`, or `gclient runhooks`. + +The Ninja build files and build output are in the `out` directory. Both debug- +and release-mode configurations are available. The examples below show the debug +configuration. To build and test the release configuration, substitute `Release` +for `Debug`. + +``` +$ cd ~/crashpad/crashpad +$ ninja -C out/Debug +``` + +Ninja is part of the +[depot_tools](https://dev.chromium.org/developers/how-tos/depottools). There’s +no need to install it separately. + +### Android + +Crashpad’s Android port is in its early stages. This build relies on +cross-compilation. It’s possible to develop Crashpad for Android on any platform +that the [Android NDK (Native Development +Kit)](https://developer.android.com/ndk/) runs on. + +If it’s not already present on your system, [download the NDK package for your +system](https://developer.android.com/ndk/downloads/) and expand it to a +suitable location. These instructions assume that it’s been expanded to +`~/android-ndk-r13`. + +To build Crashpad, portions of the NDK must be reassembled into a [standalone +toolchain](https://developer.android.com/ndk/guides/standalone_toolchain.html). +This is a repackaged subset of the NDK suitable for cross-compiling for a single +Android architecture (such as `arm`, `arm64`, `x86`, and `x86_64`) targeting a +specific [Android API +level](https://source.android.com/source/build-numbers.html). The standalone +toolchain only needs to be built from the NDK one time for each set of options +desired. To build a standalone toolchain targeting 64-bit ARM and API level 21 +(Android 5.0 “Lollipop”), run: + +``` +$ cd ~ +$ python android-ndk-r13/build/tools/make_standalone_toolchain.py \ + --arch=arm64 --api=21 --install-dir=android-ndk-r13_arm64_api21 +``` + +Note that Chrome uses Android API level 21 for 64-bit platforms and 16 for +32-bit platforms. See Chrome’s +[`build/config/android/config.gni`](https://chromium.googlesource.com/chromium/src/+/master/build/config/android/config.gni) +which sets `_android_api_level` and `_android64_api_level`. + +To configure a Crashpad build for Android using this standalone toolchain, set +several environment variables directing the build to the standalone toolchain, +along with GYP options to identify an Android build. This must be done after any +`gclient sync`, or instead of any `gclient runhooks` operation. The environment +variables only need to be set for this `gyp_crashpad.py` invocation, and need +not be permanent. + +``` +$ cd ~/crashpad/crashpad +$ CC_target=~/android-ndk-r13_arm64_api21/bin/clang \ + CXX_target=~/android-ndk-r13_arm64_api21/bin/clang++ \ + AR_target=~/android-ndk-r13_arm64_api21/bin/aarch64-linux-android-ar \ + NM_target=~/android-ndk-r13_arm64_api21/bin/aarch64-linux-android-nm \ + READELF_target=~/android-ndk-r13_arm64_api21/bin/aarch64-linux-android-readelf \ + python build/gyp_crashpad.py \ + -DOS=android -Dtarget_arch=arm64 -Dclang=1 \ + --generator-output=out_android_arm64_api21 -f ninja-android +``` + +Target “triplets” to use for `ar`, `nm`, and `readelf` are: + +| Architecture | Target “triplet” | +|:-------------|:------------------------| +| `arm` | `arm-linux-androideabi` | +| `arm64` | `aarch64-linux-android` | +| `x86` | `i686-linux-android` | +| `x86_64` | `x86_64-linux-android` | + +The port is incomplete, but targets known to be working include `crashpad_util`, +`crashpad_test`, and `crashpad_test_test`. This list will grow over time. To +build, direct `ninja` to the specific `out` directory chosen by +`--generator-output` above. + +``` +$ ninja -C out_android_arm64_api21/out/Debug crashpad_test_test +``` + +## Testing + +Crashpad uses [Google Test](https://github.com/google/googletest/) as its +unit-testing framework, and some tests use [Google +Mock](https://github.com/google/googletest/tree/master/googlemock/) as well. Its +tests are currently split up into several test executables, each dedicated to +testing a different component. This may change in the future. After a successful +build, the test executables will be found at `out/Debug/crashpad_*_test`. + +``` +$ cd ~/crashpad/crashpad +$ out/Debug/crashpad_minidump_test +$ out/Debug/crashpad_util_test +``` + +A script is provided to run all of Crashpad’s tests. It accepts a single +argument that tells it which configuration to test. + +``` +$ cd ~/crashpad/crashpad +$ python build/run_tests.py Debug +``` + +### Android + +To test on Android, use [ADB (Android Debug +Bridge)](https://developer.android.com/studio/command-line/adb.html) to `adb +push` test executables and test data to a device or emulator, then use `adb +shell` to get a shell to run the test executables from. ADB is part of the +[Android SDK](https://developer.android.com/sdk/). Note that it is sufficient to +install just the command-line tools. The entire Android Studio IDE is not +necessary to obtain ADB. + +This example runs `crashpad_test_test` on a device. This test executable has a +run-time dependency on a second executable and a test data file, which are also +transferred to the device prior to running the test. + +``` +$ cd ~/crashpad/crashpad +$ adb push out_android_arm64_api21/out/Debug/crashpad_test_test /data/local/tmp/ +[100%] /data/local/tmp/crashpad_test_test +$ adb push \ + out_android_arm64_api21/out/Debug/crashpad_test_test_multiprocess_exec_test_child \ + /data/local/tmp/ +[100%] /data/local/tmp/crashpad_test_test_multiprocess_exec_test_child +$ adb shell mkdir -p /data/local/tmp/crashpad_test_data_root/test +$ adb push test/paths_test_data_root.txt \ + /data/local/tmp/crashpad_test_data_root/test/ +[100%] /data/local/tmp/crashpad_test_data_root/test/paths_test_data_root.txt +$ adb shell +device:/ $ cd /data/local/tmp +device:/data/local/tmp $ CRASHPAD_TEST_DATA_ROOT=crashpad_test_data_root \ + ./crashpad_test_test +``` + +## Contributing + +Crashpad’s contribution process is very similar to [Chromium’s contribution +process](https://dev.chromium.org/developers/contributing-code). + +### Code Review + +A code review must be conducted for every change to Crashpad’s source code. Code +review is conducted on [Chromium’s +Gerrit](https://chromium-review.googlesource.com/) system, and all code reviews +must be sent to an appropriate reviewer, with a Cc sent to +[crashpad-dev](https://groups.google.com/a/chromium.org/group/crashpad-dev). The +[`codereview.settings`](https://chromium.googlesource.com/crashpad/crashpad/+/master/codereview.settings) +file specifies this environment to `git-cl`. + +`git-cl` is part of the +[depot_tools](https://dev.chromium.org/developers/how-tos/depottools). There’s +no need to install it separately. + +``` +$ cd ~/crashpad/crashpad +$ git checkout -b work_branch origin/master +…do some work… +$ git add … +$ git commit +$ git cl upload +``` + +The [PolyGerrit interface](https://polygerrit.appspot.com/) to Gerrit, +undergoing active development, is recommended. To switch from the classic +GWT-based Gerrit UI to PolyGerrit, click the PolyGerrit link in a Gerrit review +page’s footer. + +Uploading a patch to Gerrit does not automatically request a review. You must +select a reviewer on the Gerrit review page after running `git cl upload`. This +action notifies your reviewer of the code review request. If you have lost track +of the review page, `git cl issue` will remind you of its URL. Alternatively, +you can request review when uploading to Gerrit by using `git cl upload +--send-mail`. + +Git branches maintain their association with Gerrit reviews, so if you need to +make changes based on review feedback, you can do so on the correct Git branch, +committing your changes locally with `git commit`. You can then upload a new +patch set with `git cl upload` and let your reviewer know you’ve addressed the +feedback. + +### Landing Changes + +After code review is complete and “Code-Review: +1” has been received from all +reviewers, project members can commit the patch themselves: + +``` +$ cd ~/crashpad/crashpad +$ git checkout work_branch +$ git cl land +``` + +Alternatively, patches can be committed by clicking the “Submit” button in the +Gerrit UI. + +Crashpad does not currently have a [commit +queue](https://dev.chromium.org/developers/testing/commit-queue), so +contributors who are not project members will have to ask a project member to +commit the patch for them. Project members can commit changes on behalf of +external contributors by clicking the “Submit” button in the Gerrit UI. + +### External Contributions + +Copyright holders must complete the [Individual Contributor License +Agreement](https://developers.google.com/open-source/cla/individual) or +[Corporate Contributor License +Agreement](https://developers.google.com/open-source/cla/corporate) as +appropriate before any submission can be accepted, and must be listed in the +`AUTHORS` file. Contributors may be listed in the `CONTRIBUTORS` file. + +## Buildbot + +The [Crashpad Buildbot](https://build.chromium.org/p/client.crashpad/) performs +automated builds and tests of Crashpad. Before checking out or updating the +Crashpad source code, and after checking in a new change, it is prudent to check +the Buildbot to ensure that “the tree is green.” diff --git a/doc/index.ad b/doc/index.ad deleted file mode 100644 index 3b06292e..00000000 --- a/doc/index.ad +++ /dev/null @@ -1,42 +0,0 @@ -// Copyright 2015 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: article - -= Crashpad - -https://crashpad.chromium.org/[Crashpad] is a crash-reporting system. - -== Documentation - - * link:status.html[Project status] - * link:developing.html[Developing Crashpad]: instructions for getting the - source code, building, testing, and contributing to the project. - * https://crashpad.chromium.org/doxygen/index.html[Crashpad interface - documentation] - * https://crashpad.chromium.org/man/index.html[Crashpad tool man pages] - -== Source Code - -Crashpad’s source code is hosted in a Git repository at -https://chromium.googlesource.com/crashpad/crashpad. - -== Other Links - - * Bugs can be reported at the https://crashpad.chromium.org/bug/[Crashpad issue - tracker]. - * The https://build.chromium.org/p/client.crashpad[Crashpad Buildbot] performs - automated builds and tests. - * https://groups.google.com/a/chromium.org/group/crashpad-dev[crashpad-dev] is - the Crashpad developers’ mailing list. diff --git a/doc/status.ad b/doc/status.ad deleted file mode 100644 index 6d45dd45..00000000 --- a/doc/status.ad +++ /dev/null @@ -1,42 +0,0 @@ -// Copyright 2015 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: article - -= Project Status - -== Completed - -Crashpad currently consists of a crash-reporting client and some related tools -for Mac OS X and Windows. The core client work for both platforms is -substantially complete. Crashpad became the crash reporter client for -https://dev.chromium.org/Home[Chromium] on Mac OS X as of -https://chromium.googlesource.com/chromium/src/\+/d413b2dcb54d523811d386f1ff4084f677a6d089[March -2015], and on Windows as of -https://chromium.googlesource.com/chromium/src/\+/cfa5b01bb1d06bf96967bd37e21a44752801948c[November -2015]. - -== In Progress - -Initial work on a Crashpad client for -https://crashpad.chromium.org/bug/30[Android] has begun. This is currently in -the early implementation phase. - -== Future - -There are plans to bring Crashpad clients to other operating systems in the -future, including a more generic non-Android Linux implementation. There are -also plans to implement a https://crashpad.chromium.org/bug/29[crash report -processor] as part of Crashpad. No timeline for completing this work has been -set yet. diff --git a/doc/status.md b/doc/status.md new file mode 100644 index 00000000..be4503a1 --- /dev/null +++ b/doc/status.md @@ -0,0 +1,41 @@ + + +# Project Status + +## Completed + +Crashpad currently consists of a crash-reporting client and some related tools +for macOS and Windows. The core client work for both platforms is substantially +complete. Crashpad became the crash reporter client for +[Chromium](https://dev.chromium.org/Home) on macOS as of [March +2015](https://chromium.googlesource.com/chromium/src/\+/d413b2dcb54d523811d386f1ff4084f677a6d089), +and on Windows as of [November +2015](https://chromium.googlesource.com/chromium/src/\+/cfa5b01bb1d06bf96967bd37e21a44752801948c). + +## In Progress + +Initial work on a Crashpad client for +[Android](https://crashpad.chromium.org/bug/30) has begun. This is currently in +the early implementation phase. + +## Future + +There are plans to bring Crashpad clients to other operating systems in the +future, including a more generic non-Android Linux implementation. There are +also plans to implement a [crash report +processor](https://crashpad.chromium.org/bug/29) as part of Crashpad. No +timeline for completing this work has been set yet. diff --git a/doc/support/asciidoc.conf b/doc/support/asciidoc.conf deleted file mode 100644 index a4ab2c4c..00000000 --- a/doc/support/asciidoc.conf +++ /dev/null @@ -1,58 +0,0 @@ -# Copyright 2015 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. - -[miscellaneous] -# AsciiDoc uses \r\n by default. -newline=\n - -# The default AsciiDoc lang-en.conf uses docdate and doctime for the -# last-updated line in footer-text. These attributes are taken from the file’s -# mtime and cannot be overridden. For a git-based project, the date of the last -# revision is desirable, so change this to use git_date, an attribute that can -# be computed and passed in by the script that runs AsciiDoc. For man pages, use -# the mansource and manversion attributes instead of the hard-coded “Version” -# string and revnumber attribute, so that the version will appear as “Crashpad -# 0.7.0” as it does in “man” output. -ifdef::basebackend-html[] -[footer-text] -ifdef::doctype-manpage[] -{mansource=Version} {manversion={revnumber}}{basebackend-xhtml11?
}{basebackend-xhtml11=
} -endif::doctype-manpage[] -ifndef::doctype-manpage[] -Version {revnumber}{basebackend-xhtml11?
}{basebackend-xhtml11=
} -endif::doctype-manpage[] -Last updated {git_date} -endif::basebackend-html[] - -# The man_link macro was inspired by git’s linkgit macro. See -# https://github.com/git/git/blob/master/Documentation/asciidoc.conf. -ifdef::doctype-manpage[] - -[macros] -(?su)[\\]?(?Pman_link):(?P\S*?)\[(?P.*?)\]= - -ifdef::backend-docbook[] -[man_link-inlinemacro] -{0%{target}} -{0#} -{0#{target}{0}} -{0#} -endif::backend-docbook[] - -ifdef::basebackend-html[] -[man_link-inlinemacro] -{target}{0?({0})} -endif::basebackend-html[] - -endif::doctype-manpage[] diff --git a/doc/support/asciidoc.css b/doc/support/asciidoc.css deleted file mode 100644 index 9808c216..00000000 --- a/doc/support/asciidoc.css +++ /dev/null @@ -1,20 +0,0 @@ -/* Copyright 2015 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. */ - -/* The default AsciiDoc asciidoc.css specifies fuchsia as the visited link - * color. This has a dated appearance. Replace it with blue, the same color used - * for unvisited links. */ -a:visited { - color: blue; -} diff --git a/doc/support/generate.sh b/doc/support/generate.sh index 0a2be484..0f77a4a8 100755 --- a/doc/support/generate.sh +++ b/doc/support/generate.sh @@ -29,31 +29,44 @@ cd "$(dirname "${0}")/../.." source doc/support/compat.sh doc/support/generate_doxygen.sh -doc/support/generate_asciidoc.sh output_dir=doc/generated maybe_mkdir "${output_dir}" -for subdir in doc doxygen man ; do - output_subdir="${output_dir}/${subdir}" - maybe_mkdir "${output_subdir}" - rsync -Ilr --delete --exclude .git "out/doc/${subdir}/html/" \ - "${output_subdir}/" -done +maybe_mkdir "${output_dir}/doxygen" +rsync -Ilr --delete --exclude .git "out/doc/doxygen/html/" \ + "${output_dir}/doxygen" -# Move doc/index.html to index.html, adjusting relative paths to other files in -# doc. -base_url=https://crashpad.chromium.org/ -${sed_ext} -e 's%%%g' \ - -e 's%%%g' \ - -e 's% "${output_dir}/index.html" -rm "${output_dir}/doc/index.html" +# Remove old things that used to be present +rm -rf "${output_dir}/doc" +rm -rf "${output_dir}/man" +rm -f "${output_dir}/index.html" # Ensure a favicon exists at the root since the browser will always request it. cp doc/favicon.ico "${output_dir}/" -# Create man/index.html +# Create man/index.html. Do this in two steps so that the built-up list of man +# pages can be sorted according to the basename, not the entire path. +list_file=$(mktemp) +for man_path in $(find . -name '*.md' | + ${sed_ext} -e 's%^\./%%' | + grep -Ev '^(README.md$|(third_party|doc)/)'); do + # These should show up in all man pages, but probably not all together in any + # other Markdown documents. + if ! (grep -q '^## Name$' "${man_path}" && + grep -q '^## Synopsis$' "${man_path}" && + grep -q '^## Description$' "${man_path}"); then + continue + fi + + man_basename=$(${sed_ext} -e 's/\.md$//' <<< $(basename "${man_path}")) + cat >> "${list_file}" << __EOF__ +${man_basename} +__EOF__ +done + +maybe_mkdir "${output_dir}/man" + cd "${output_dir}/man" cat > index.html << __EOF__ @@ -62,18 +75,17 @@ cat > index.html << __EOF__
    __EOF__ -for html_file in *.html; do - if [[ "${html_file}" = "index.html" ]]; then - continue - fi - basename=$(${sed_ext} -e 's/\.html$//' <<< "${html_file}") +sort "${list_file}" | while read line; do + line=$(${sed_ext} -e 's/^//' <<< "${line}") cat >> index.html << __EOF__
  • - ${basename} +${line}
    • __EOF__ done +rm -f "${list_file}" + cat >> index.html << __EOF__
__EOF__ diff --git a/doc/support/generate_asciidoc.sh b/doc/support/generate_asciidoc.sh deleted file mode 100755 index 54a57349..00000000 --- a/doc/support/generate_asciidoc.sh +++ /dev/null @@ -1,111 +0,0 @@ -#!/bin/bash - -# Copyright 2015 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. - -set -e - -# Generating AsciiDoc documentation requires AsciiDoc, -# http://www.methods.co.nz/asciidoc/. For “man” and PDF output, a DocBook -# toolchain including docbook-xml and docbook-xsl is also required. - -# Run from the Crashpad project root directory. -cd "$(dirname "${0}")/../.." - -source doc/support/compat.sh - -output_dir=out/doc - -rm -rf \ - "${output_dir}/doc" \ - "${output_dir}/man" -mkdir -p \ - "${output_dir}/doc/html" \ - "${output_dir}/man/html" \ - "${output_dir}/man/man" - -# Get the version from package.h. -version=$(${sed_ext} -n -e 's/^#define PACKAGE_VERSION "(.*)"$/\1/p' package.h) - -generate() { - input="$1" - type="$2" - - case "${type}" in - doc) - doctype="article" - ;; - man) - doctype="manpage" - ;; - *) - echo "${0}: unknown type ${type}" >& 2 - exit 1 - ;; - esac - - echo "${input}" - - base=$(${sed_ext} -e 's%^.*/([^/]+)\.ad$%\1%' <<< "${input}") - - # Get the last-modified date of $input according to Git, in UTC. - git_time_t="$(git log -1 --format=%at "${input}")" - git_date="$(LC_ALL=C ${date_time_t}"${git_time_t}" -u '+%B %-d, %Y')" - - # Create HTML output. - asciidoc \ - --attribute mansource=Crashpad \ - --attribute manversion="${version}" \ - --attribute manmanual="Crashpad Manual" \ - --attribute git_date="${git_date}" \ - --conf-file doc/support/asciidoc.conf \ - --doctype "${doctype}" \ - --backend html5 \ - --attribute stylesheet="${PWD}/doc/support/asciidoc.css" \ - --out-file "${output_dir}/${type}/html/${base}.html" \ - "${input}" - - if [[ "${type}" = "man" ]]; then - # Create “man” output. - # - # AsciiDoc 8.6.9 produces harmless incorrect warnings each time this is run: - # “a2x: WARNING: --destination-dir option is only applicable to HTML based - # outputs”. https://github.com/asciidoc/asciidoc/issues/44 - a2x \ - --attribute mansource=Crashpad \ - --attribute manversion="${version}" \ - --attribute manmanual="Crashpad Manual" \ - --attribute git_date="${git_date}" \ - --asciidoc-opts=--conf-file=doc/support/asciidoc.conf \ - --doctype "${doctype}" \ - --format manpage \ - --destination-dir "${output_dir}/${type}/man" \ - "${input}" - fi - - # For PDF output, use an a2x command like the one above, with these options: - # --format pdf --fop --destination-dir "${output_dir}/${type}/pdf" -} - -for input in \ - doc/*.ad; do - generate "${input}" "doc" -done - -for input in \ - handler/crashpad_handler.ad \ - tools/*.ad \ - tools/mac/*.ad; do - generate "${input}" "man" -done diff --git a/doc/support/man_footer.ad b/doc/support/man_footer.ad deleted file mode 100644 index 2dd84fcc..00000000 --- a/doc/support/man_footer.ad +++ /dev/null @@ -1,40 +0,0 @@ -// 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. - -== Resources - -Crashpad home page: https://crashpad.chromium.org/. - -Report bugs at https://crashpad.chromium.org/bug/new. - -== Copyright - -Copyright 2016 -https://chromium.googlesource.com/crashpad/crashpad/+/master/AUTHORS[The -Crashpad 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 - -[subs="macros"] - 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. diff --git a/handler/crashpad_handler.ad b/handler/crashpad_handler.ad deleted file mode 100644 index a4918d6f..00000000 --- a/handler/crashpad_handler.ad +++ /dev/null @@ -1,183 +0,0 @@ -// 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\+. 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[] diff --git a/handler/crashpad_handler.md b/handler/crashpad_handler.md new file mode 100644 index 00000000..914d7be4 --- /dev/null +++ b/handler/crashpad_handler.md @@ -0,0 +1,223 @@ + + +# 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 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 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\`. 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. diff --git a/navbar.md b/navbar.md new file mode 100644 index 00000000..e3c3d97b --- /dev/null +++ b/navbar.md @@ -0,0 +1,21 @@ + + +* [Home](/README.md) +* [Developing](/doc/developing.md) +* [Doxygen](https://crashpad.chromium.org/doxygen/) +* [Man Pages](https://crashpad.chromium.org/man/) +* [Source Code](https://chromium.googlesource.com/crashpad/crashpad/) diff --git a/tools/crashpad_database_util.ad b/tools/crashpad_database_util.ad deleted file mode 100644 index 78107ee3..00000000 --- a/tools/crashpad_database_util.ad +++ /dev/null @@ -1,163 +0,0 @@ -// Copyright 2015 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_database_util(1) - -== Name - -crashpad_database_util - Operate on Crashpad crash report databases - -== Synopsis - -[verse] -*crashpad_database_util* ['OPTION…'] - -== Description - -Operates on Crashpad crash report databases. The database’s settings can be -queried and modified, and information about crash reports stored in the -database can be displayed. - -When this program is requested to both show and set information in a single -invocation, all “show” operations will be completed prior to beginning any “set” -operation. - -Programs that use the Crashpad client library directly will not normally use -this tool, but may use the database through the programmatic interfaces in the -client library. This tool exists to allow developers to manipulate a Crashpad -database. - -== Options -*--create*:: -Creates the database identified by *--database* if it does not exist, provided -that the parent directory of 'PATH' exists. - -*-d*, *--database*='PATH':: -Use 'PATH' as the path to the Crashpad crash report database. This option is -required. The database must already exist unless *--create* is also specified. - -*--show-client-id*:: -Show the client ID stored in the database’s settings. The client ID is formatted -as a UUID. The client ID is set when the database is created. -man_link:crashpad_handler[8] retrieves the client ID and stores it in crash -reports as they are written. - -*--show-uploads-enabled*:: -Show the status of the uploads-enabled bit stored in the database’s settings. -man_link:crashpad_handler[8] does not upload reports when this bit is false. -This bit is false when a database is created, and is under an application’s -control via the Crashpad client library interface. -+ -See also *--set-uploads-enabled*. - -*--show-last-upload-attempt-time*:: -Show the last-upload-attempt time stored in the database’s settings. This value -is +0+, meaning “never,” when the database is created. -man_link:crashpad_handler[8] consults this value before attempting an upload to -implement its rate-limiting behavior. The database updates this value whenever -an upload is attempted. -+ -See also *--set-last-upload-attempt-time*. - -*--show-pending-reports*:: -Show reports eligible for upload. - -*--show-completed-reports*:: -Show reports not eligible for upload. A report is moved from the “pending” state -to the “completed” state by man_link:crashpad_handler[8]. This may happen when a -report is successfully uploaded, when a report is not uploaded because uploads -are disabled, or when a report upload attempt fails and will not be retried. - -*--show-all-report-info*:: -With *--show-pending-reports* or *--show-completed-reports*, show all metadata -for each report displayed. Without this option, only report IDs will be shown. - -*--show-report*='UUID':: -Show a report from the database looked up by its identifier, 'UUID', which must -be formatted in string representation per RFC 4122 §3. All metadata for each -report found via a *--show-report* option will be shown. If 'UUID' is not found, -the string +"not found"+ will be printed. If this program is only requested to -show a single report and it is not found, it will treat this as a failure for -the purposes of determining its exit status. This option may appear multiple -times. - -*--set-report-uploads-enabled*='BOOL':: -Enable or disable report upload in the database’s settings. 'BOOL' is a string -representation of a boolean value, such as +"0"+ or +"true"+. -+ -See also *--show-uploads-enabled*. - -*--set-last-upload-attempt-time*='TIME':: -Set the last-upload-attempt time in the database’s settings. 'TIME' is a string -representation of a time, which may be in 'yyyy-mm-dd hh:mm:ss' format, a -numeric +time_t+ value, or the special string +"never"+. -+ -See also *--show-last-upload-attempt-time*. - -*--new-report*='PATH':: -Submit a new report located at 'PATH' to the database. If 'PATH' is +"-"+, the -new report will be read from standard input. The new report will be in the -“pending” state. The UUID assigned to the new report will be printed. This -option may appear multiple times. - -*--utc*:: -When showing times, do so in UTC as opposed to the local time zone. When setting -times, interpret ambiguous time strings in UTC as opposed to the local time -zone. - -*--help*:: -Display help and exit. - -*--version*:: -Output version information and exit. - -== Examples - -Shows all crash reports in a crash report database that are in the “completed” -state. -[subs="quotes"] ----- -$ *crashpad_database_util --database /tmp/crashpad_database \ - --show-completed-reports* -23f9512b-63e1-4ead-9dcd-e2e21fbccc68 -4bfca440-039f-4bc6-bbd4-6933cef5efd4 -56caeff8-b61a-43b2-832d-9e796e6e4a50 ----- - -Disables report upload in a crash report database’s settings, and then verifies -that the change was made. -[subs="quotes"] ----- -$ *crashpad_database_util --database /tmp/crashpad_database \ - --set-uploads-enabled false* -$ *crashpad_database_util --database /tmp/crashpad_database \ - --show-uploads-enabled* -false ----- - -== Exit Status - -*0*:: -Success. - -*1*:: -Failure, with a message printed to the standard error stream. - -== See Also - -man_link:crashpad_handler[8] - -include::../doc/support/man_footer.ad[] diff --git a/tools/crashpad_database_util.md b/tools/crashpad_database_util.md new file mode 100644 index 00000000..610731dd --- /dev/null +++ b/tools/crashpad_database_util.md @@ -0,0 +1,207 @@ + + +# crashpad_database_util(1) + +## Name + +crashpad_database_util—Operate on Crashpad crash report databases + +## Synopsis + +**crashpad_database_util** [_OPTION…_] + +## Description + +Operates on Crashpad crash report databases. The database’s settings can be +queried and modified, and information about crash reports stored in the database +can be displayed. + +When this program is requested to both show and set information in a single +invocation, all “show” operations will be completed prior to beginning any “set” +operation. + +Programs that use the Crashpad client library directly will not normally use +this tool, but may use the database through the programmatic interfaces in the +client library. This tool exists to allow developers to manipulate a Crashpad +database. + +## Options + + * **--create** + + Creates the database identified by **--database** if it does not exist, + provided that the parent directory of _PATH_ exists. + + * **-d**, **--database**=_PATH_ + + Use _PATH_ as the path to the Crashpad crash report database. This option is + required. The database must already exist unless **--create** is also + specified. + + * **--show-client-id** + + Show the client ID stored in the database’s settings. The client ID is + formatted as a UUID. The client ID is set when the database is created. + [crashpad_handler(8)](../handler/crashpad_handler.md) retrieves the client ID + and stores it in crash reports as they are written. + + * **--show-uploads-enabled** + + Show the status of the uploads-enabled bit stored in the database’s settings. + [crashpad_handler(8)](../handler/crashpad_handler.md) does not upload reports + when this bit is false. This bit is false when a database is created, and is + under an application’s control via the Crashpad client library interface. + + See also **--set-uploads-enabled**. + + * **--show-last-upload-attempt-time** + + Show the last-upload-attempt time stored in the database’s settings. This + value is `0`, meaning “never,” when the database is created. + [crashpad_handler(8)](../handler/crashpad_handler.md) consults this value + before attempting an upload to implement its rate-limiting behavior. The + database updates this value whenever an upload is attempted. + + See also **--set-last-upload-attempt-time**. + + * **--show-pending-reports** + + Show reports eligible for upload. + + * **--show-completed-reports** + + Show reports not eligible for upload. A report is moved from the “pending” + state to the “completed” state by + [crashpad_handler(8)](../handler/crashpad_handler.md). This may happen when a + report is successfully uploaded, when a report is not uploaded because + uploads are disabled, or when a report upload attempt fails and will not be + retried. + + * **--show-all-report-info** + + With **--show-pending-reports** or **--show-completed-reports**, show all + metadata for each report displayed. Without this option, only report IDs will + be shown. + + * **--show-report**=_UUID_ + + Show a report from the database looked up by its identifier, _UUID_, which + must be formatted in string representation per RFC 4122 §3. All metadata for + each report found via a **--show-report** option will be shown. If _UUID_ is + not found, the string `"not found"` will be printed. If this program is only + requested to show a single report and it is not found, it will treat this as + a failure for the purposes of determining its exit status. This option may + appear multiple times. + + * **--set-report-uploads-enabled**=_BOOL_ + + Enable or disable report upload in the database’s settings. _BOOL_ is a + string representation of a boolean value, such as `"0"` or `"true"`. + + See also **--show-uploads-enabled**. + + * **--set-last-upload-attempt-time**=_TIME_ + + Set the last-upload-attempt time in the database’s settings. _TIME_ is a + string representation of a time, which may be in _yyyy-mm-dd hh:mm:ss_ + format, a numeric `time_t` value, or the special string `"never"`. + + See also **--show-last-upload-attempt-time**. + + * **--new-report**=_PATH_ + + Submit a new report located at _PATH_ to the database. If _PATH_ is `"-"`, + the new report will be read from standard input. The new report will be in + the “pending” state. The UUID assigned to the new report will be printed. + This option may appear multiple times. + + * **--utc** + + When showing times, do so in UTC as opposed to the local time zone. When + setting times, interpret ambiguous time strings in UTC as opposed to the + local time zone. + + * **--help** + + Display help and exit. + + * **--version** + + Output version information and exit. + +## Examples + +Shows all crash reports in a crash report database that are in the “completed” +state. + +``` +$ crashpad_database_util --database /tmp/crashpad_database \ + --show-completed-reports +23f9512b-63e1-4ead-9dcd-e2e21fbccc68 +4bfca440-039f-4bc6-bbd4-6933cef5efd4 +56caeff8-b61a-43b2-832d-9e796e6e4a50 +``` + +Disables report upload in a crash report database’s settings, and then verifies +that the change was made. + +``` +$ crashpad_database_util --database /tmp/crashpad_database \ + --set-uploads-enabled false +$ crashpad_database_util --database /tmp/crashpad_database \ + --show-uploads-enabled +false +``` + +## Exit Status + + * **0** + + Success. + + * **1** + + Failure, with a message printed to the standard error stream. + +## See Also + +[crashpad_handler(8)](../handler/crashpad_handler.md) + +## Resources + +Crashpad home page: https://crashpad.chromium.org/. + +Report bugs at https://crashpad.chromium.org/bug/new. + +## Copyright + +Copyright 2015 [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. diff --git a/tools/generate_dump.ad b/tools/generate_dump.ad deleted file mode 100644 index d8a53c8d..00000000 --- a/tools/generate_dump.ad +++ /dev/null @@ -1,96 +0,0 @@ -// 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 - -= generate_dump(1) - -== Name - -generate_dump - Generate a minidump file containing a snapshot of a running -process - -== Synopsis - -[verse] -*generate_dump* ['OPTION…'] 'PID' - -== Description - -Generates a minidump file containing a snapshot of a running process whose -process identifier is 'PID'. By default, the target process will be suspended -while the minidump is generated, and the minidump file will be written to -+minidump.PID+. After the minidump file is generated, the target process resumes -running. - -The minidump file will contain information about the process, its threads, its -modules, and the system. It will not contain any exception information because -it will be generated from a live running process, not as a result of an -exception occurring. - -This program uses +task_for_pid()+ to access the process’ task port. This -operation may be restricted to use by the superuser, executables signed by an -authority trusted by the system, and processes otherwise permitted by -taskgated(8). Consequently, this program must normally either be signed or be -invoked by root. It is possible to install this program as a setuid root -executable to overcome this limitation. - -This program is similar to the gcore(1) program available on some operating -systems. - -== Options - -*-r*, *--no-suspend*:: -The target process will continue running while the minidump file is generated. -Normally, the target process is suspended during this operation, which -guarantees that the minidump file will contain an atomic snapshot of the -process. -+ -This option may be useful when attempting to generate a minidump from a process -that dump generation has an interprocess dependency on, such as a system server -like launchd(8) or opendirectoryd(8). Deadlock could occur if any portion of the -dump generation operation blocks while waiting for a response from one of these -servers while they are suspended. - -*-o*, *--output*='FILE':: -The minidump will be written to 'FILE' instead of +minidump.PID+. - -*--help*:: -Display help and exit. - -*--version*:: -Output version information and exit. - -== Examples - -Generate a minidump file in +/tmp/minidump+ containing a snapshot of the process -with PID 1234. -[subs="quotes"] ----- -$ *generate_dump --output=/tmp/minidump 1234* ----- - -== Exit Status - -*0*:: -Success. - -*1*:: -Failure, with a message printed to the standard error stream. - -== See Also - -man_link:catch_exception_tool[1] - -include::../doc/support/man_footer.ad[] diff --git a/tools/generate_dump.md b/tools/generate_dump.md new file mode 100644 index 00000000..c58ecbc3 --- /dev/null +++ b/tools/generate_dump.md @@ -0,0 +1,127 @@ + + +# generate_dump(1) + +## Name + +generate_dump—Generate a minidump file containing a snapshot of a running +process + +## Synopsis + +**generate_dump** [_OPTION…_] _PID_ + +## Description + +Generates a minidump file containing a snapshot of a running process whose +process identifier is _PID_. By default, the target process will be suspended +while the minidump is generated, and the minidump file will be written to +`minidump.PID`. After the minidump file is generated, the target process resumes +running. + +The minidump file will contain information about the process, its threads, its +modules, and the system. It will not contain any exception information because +it will be generated from a live running process, not as a result of an +exception occurring. + +On macOS, this program uses `task_for_pid()` to access the process’ task port. +This operation may be restricted to use by the superuser, executables signed by +an authority trusted by the system, and processes otherwise permitted by +taskgated(8). Consequently, this program must normally either be signed or be +invoked by root. It is possible to install this program as a setuid root +executable to overcome this limitation, although it will remain impossible to +generate dumps for processes protected by [System Integrity Protection +(SIP)](https://support.apple.com/HT204899), including those whose “restrict” +codesign(1) option is respected. + +This program is similar to the gcore(1) program available on some operating +systems. + +## Options + + * **-r**, **--no-suspend** + + The target process will continue running while the minidump file is + generated. Normally, the target process is suspended during this operation, + which guarantees that the minidump file will contain an atomic snapshot of + the process. + + This option may be useful when attempting to generate a minidump from a + process that dump generation has an interprocess dependency on, such as a + system server like launchd(8) or opendirectoryd(8) on macOS. Deadlock could + occur if any portion of the dump generation operation blocks while waiting + for a response from one of these servers while they are suspended. + + * **-o**, **--output**=_FILE_ + + The minidump will be written to _FILE_ instead of `minidump.PID`. + + * **--help** + + Display help and exit. + + * **--version** + + Output version information and exit. + +## Examples + +Generate a minidump file in `/tmp/minidump` containing a snapshot of the process +with PID 1234. + +``` +$ generate_dump --output=/tmp/minidump 1234 +``` + +## Exit Status + + * **0** + + Success. + + * **1** + + Failure, with a message printed to the standard error stream. + +## See Also + +[catch_exception_tool(1)](mac/catch_exception_tool.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. diff --git a/tools/mac/catch_exception_tool.ad b/tools/mac/catch_exception_tool.ad deleted file mode 100644 index a639de4c..00000000 --- a/tools/mac/catch_exception_tool.ad +++ /dev/null @@ -1,117 +0,0 @@ -// 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 - -= catch_exception_tool(1) - -== Name - -catch_exception_tool - Catch Mach exceptions and display information about them - -== Synopsis - -[verse] -*catch_exception_tool* *-m* 'SERVICE' ['OPTION…'] - -== Description - -Runs a Mach exception server registered with the bootstrap server under the name -'SERVICE'. The exception server is capable of receiving exceptions for -“behavior” values of +EXCEPTION_DEFAULT+, +EXCEPTION_STATE+, and -+EXCEPTION_STATE_IDENTITY+, with or without +MACH_EXCEPTION_CODES+ set. - -== Options - -*-f*, *--file*='FILE':: -Information about the exception will be appended to 'FILE' instead of the -standard output stream. - -*-m*, *--mach-service*='SERVICE':: -Check in with the bootstrap server under the name 'SERVICE'. This service name -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. - -*-p*, *--persistent*:: -Continue processing exceptions after the first one. The default mode is -one-shot, where this tool exits after processing the first exception. - -*-t*, *--timeout*='TIMEOUT':: -Run for a maximum of 'TIMEOUT' seconds. Specify +0+ to request non-blocking -operation, in which the tool exits immediately if no exception is received. In -*--persistent* mode, 'TIMEOUT' applies to the overall duration that this tool -will run, not to the processing of individual exceptions. When *--timeout* is -not specified, this tool will block indefinitely while waiting for an exception. - -*--help*:: -Display help and exit. - -*--version*:: -Output version information and exit. - -== Examples - -Run a one-shot blocking exception server registered with the bootstrap server -under the name +svc+: -[subs="quotes"] ----- -$ *catch_exception_tool --mach-service=svc --file=out &* -[1] 1233 -$ *exception_port_tool --set-handler=handler=bootstrap:svc crasher* -Illegal instruction: 4 -[1]+ Done catch_exception_tool --mach-service=svc --file=out -$ *cat out* -catch_exception_tool: -behavior EXCEPTION_DEFAULT|MACH_EXCEPTION_CODES, -pid 1234, thread 56789, exception EXC_CRASH, codes[2] 0x4200001, 0, -original exception EXC_BAD_INSTRUCTION, original code[0] 1, -signal SIGILL ----- - -Run an on-demand exception server started by launchd(5) available via the -bootstrap server under the name +svc+: -[subs="quotes"] ----- -$ *on_demand_service_tool --load --label=catch_exception \ - --mach-service=svc \ - $(which catch_exception_tool) --mach-service=svc \ - --file=/tmp/out --persistent --timeout=0* -$ *exception_port_tool --set-handler=handler=bootstrap:svc crasher* -Illegal instruction: 4 -$ *on_demand_service_tool --unload --label=catch_exception* -$ *cat /tmp/out* -catch_exception_tool: -behavior EXCEPTION_DEFAULT|MACH_EXCEPTION_CODES, -pid 2468, thread 13579, exception EXC_CRASH, codes[2] 0x4200001, 0, -original exception EXC_BAD_INSTRUCTION, original code[0] 1, -signal SIGILL ----- - -== Exit Status - -*0*:: -Success. In *--persistent* mode with a *--timeout* set, it is considered -successful if at least one exception was caught when the timer expires. - -*1*:: -Failure, with a message printed to the standard error stream. - -== See Also - -man_link:exception_port_tool[1], -man_link:on_demand_service_tool[1] - -include::../../doc/support/man_footer.ad[] diff --git a/tools/mac/catch_exception_tool.md b/tools/mac/catch_exception_tool.md new file mode 100644 index 00000000..fc357dc6 --- /dev/null +++ b/tools/mac/catch_exception_tool.md @@ -0,0 +1,140 @@ + + +# catch_exception_tool(1) + +## Name + +catch_exception_tool—Catch Mach exceptions and display information about them + +## Synopsis + +**catch_exception_tool** **-m** _SERVICE_ [_OPTION…_] + +## Description + +Runs a Mach exception server registered with the bootstrap server under the name +_SERVICE_. The exception server is capable of receiving exceptions for +“behavior” values of `EXCEPTION_DEFAULT`, `EXCEPTION_STATE`, and +`EXCEPTION_STATE_IDENTITY`, with or without `MACH_EXCEPTION_CODES` set. + +## Options + + * **-f**, **--file**=_FILE_ + + Information about the exception will be appended to _FILE_ instead of the + standard output stream. + + * **-m**, **--mach-service**=_SERVICE_ + + Check in with the bootstrap server under the name _SERVICE_. This service + name 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. + + * **-p**, **--persistent** + + Continue processing exceptions after the first one. The default mode is + one-shot, where this tool exits after processing the first exception. + + * **-t**, **--timeout**=_TIMEOUT_ + + Run for a maximum of _TIMEOUT_ seconds. Specify `0` to request non-blocking + operation, in which the tool exits immediately if no exception is received. + In **--persistent** mode, _TIMEOUT_ applies to the overall duration that this + tool will run, not to the processing of individual exceptions. When + **--timeout** is not specified, this tool will block indefinitely while + waiting for an exception. + + * **--help** + + Display help and exit. + + * **--version** + + Output version information and exit. + +## Examples + +Run a one-shot blocking exception server registered with the bootstrap server +under the name `svc`: + +``` +$ catch_exception_tool --mach-service=svc --file=out & +[1] 1233 +$ exception_port_tool --set-handler=handler=bootstrap:svc crasher +Illegal instruction: 4 +[1]+ Done catch_exception_tool --mach-service=svc --file=out +$ cat out +catch_exception_tool: behavior EXCEPTION_DEFAULT|MACH_EXCEPTION_CODES, pid 1234, thread 56789, exception EXC_CRASH, codes[2] 0x4200001, 0, original exception EXC_BAD_INSTRUCTION, original code[0] 1, signal SIGILL +``` + +Run an on-demand exception server started by launchd(5) available via the +bootstrap server under the name `svc`: + +``` +$ `on_demand_service_tool --load --label=catch_exception \ + --mach-service=svc \ + $(which catch_exception_tool) --mach-service=svc \ + --file=/tmp/out --persistent --timeout=0 +$ exception_port_tool --set-handler=handler=bootstrap:svc crasher +Illegal instruction: 4 +$ on_demand_service_tool --unload --label=catch_exception +$ cat /tmp/out +catch_exception_tool: behavior EXCEPTION_DEFAULT|MACH_EXCEPTION_CODES, pid 2468, thread 13579, exception EXC_CRASH, codes[2] 0x4200001, 0, original exception EXC_BAD_INSTRUCTION, original code[0] 1, signal SIGILL +``` + +## Exit Status + + * **0** + + Success. In **--persistent** mode with a **--timeout** set, it is considered + successful if at least one exception was caught when the timer expires. + + * **1** + + Failure, with a message printed to the standard error stream. + +## See Also + +[exception_port_tool(1)](exception_port_tool.md), +[exception_port_tool(1)](on_demand_service_tool.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. diff --git a/tools/mac/exception_port_tool.ad b/tools/mac/exception_port_tool.ad deleted file mode 100644 index e102cc00..00000000 --- a/tools/mac/exception_port_tool.ad +++ /dev/null @@ -1,188 +0,0 @@ -// 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 - -= exception_port_tool(1) - -== Name - -exception_port_tool - Show and change Mach exception ports - -== Synopsis - -[verse] -*exception_port_tool* ['OPTION…'] ['COMMAND' ['ARG…']] - -== Description - -Shows Mach exception ports registered for a thread, task, or host target with a -*--show-** option, changes Mach exception ports with *--set-handler*, shows -changes with a *--show-new-** option, and executes 'COMMAND' along with any -arguments specified ('ARG…') with the changed exception ports in effect. - -== Options -*-s*, *--set-handler*='DESCRIPTION':: -Set an exception port to 'DESCRIPTION'. This option may appear zero, one, or -more times. -+ -'DESCRIPTION' is formatted as a comma-separated sequence of tokens, where each -token consists of a key and value separated by an equals sign. These keys are -recognized: -+ -*target*='TARGET'::: -'TARGET' defines which target’s exception ports to set: *host*, *task*, or -*thread*. The default value of 'TARGET' is *task*. Operations on *host* are -restricted to the superuser. -+ -*mask*='MASK'::: -'MASK' defines the mask of exception types to handle, from -++. This can be *BAD_ACCESS*, *BAD_INSTRUCTION*, -*ARITHMETIC*, *EMULATION*, *SOFTWARE*, *BREAKPOINT*, *SYSCALL*, *MACH_SYSCALL*, -*RPC_ALERT*, *CRASH*, *RESOURCE*, *GUARD*, or *CORPSE_NOTIFY*. Different -exception types may be combined by combining them with pipe characters (*|*). -The special value *ALL* includes each exception type except for *CRASH*. To -truly specify all exception types including *CRASH*, use *ALL|CRASH*. The -default value of 'MASK' is *CRASH*. -+ -*behavior*='BEHAVIOR'::: -'BEHAVIOR' defines the specific exception handler routine to be called when an -exception occurs. This can be *DEFAULT*, *STATE*, or *STATE_IDENTITY*. *MACH* -may also be specified by combining them with pipe characters (*|*). The most -complete set of exception information is provided with *STATE_IDENTITY|MACH*. -Not all exception servers implement all possible behaviors. The default value of -'BEHAVIOR' is *DEFAULT|MACH*. -+ -*flavor*='FLAVOR'::: -For state-carrying values of 'BEHAVIOR' (those including *STATE* or -*STATE_IDENTITY*), 'FLAVOR' specifies the architecture-specific thread state -flavor to be provided to the exception handler. For the x86 family, this can be -*THREAD*, *THREAD32*, *THREAD64*, *FLOAT*, *FLOAT32*, *FLOAT64*, *DEBUG*, -*DEBUG32*, or *DEBUG64*. The default value of 'FLAVOR' is *NONE*, which is not -valid for state-carrying values of 'BEHAVIOR'. -+ -*handler*='HANDLER'::: -'HANDLER' defines the exception handler. *NULL* indicates that any existing -exception port should be cleared. 'HANDLER' may also take the form -*bootstrap*:__SERVICE__, which will look 'SERVICE' up with the bootstrap server -and set that service as the exception handler. The default value of 'HANDLER' is -*NULL*. - -*--show-bootstrap*='SERVICE':: -Looks up 'SERVICE' with the bootstrap server and shows it. Normally, the handler -port values displayed by the other *--show-** options are meaningless -handles, but by comparing them to the port values for known bootstrap services, -it is possible to verify that they are set as intended. - -*-p*, *--pid*='PID':: -For operations on the task target, including *--set-handler* with 'TARGET' set -to *task*, *--show-task*, and *--show-new-task*, operates on the task associated -with process id 'PID' instead of the current task associated with the tool. When -this option is supplied, 'COMMAND' must not be specified. -+ -This option uses +task_for_pid()+ to access the process’ task port. This -operation may be restricted to use by the superuser, executables signed by an -authority trusted by the system, and processes otherwise permitted by -taskgated(8). Consequently, this program must normally either be signed or be -invoked by root to use this option. It is possible to install this program as a -setuid root executable to overcome this limitation. - -*-h*, *--show-host*:: -Shows the original host exception ports before making any changes requested by -*--set-handler*. This option is restricted to the superuser. - -*-t*, *--show-task*:: -Shows the original task exception ports before making any changes requested by -*--set-handler*. - -*--show-thread*:: -Shows the original thread exception ports before making any changes requested by -*--set-handler*. - -*-H*, *--show-new-host*:: -Shows the modified host exception ports after making any changes requested by -*--set-handler*. This option is restricted to the superuser. - -*-T*, *--show-new-task*:: -Shows the modified task exception ports after making any changes requested by -*--set-handler*. - -*--show-new-thread*:: -Shows the modified thread exception ports after making any changes requested by -*--set-handler*. - -*-n*, *--numeric*:: -For *--show-** options, all values will be displayed numerically only. The -default is to decode numeric values and display them symbolically as well. - -*--help*:: -Display help and exit. - -*--version*:: -Output version information and exit. - -== Examples - -Sets a new task-level exception handler for +EXC_CRASH+-type exceptions to the -handler registered with the bootstrap server as +svc+, showing the task-level -exception ports before and after the change. The old and new exception handlers -are verified by their service names as registered with the bootstrap server. -With the new task-level exception ports in effect, a program is run. -[subs="quotes"] ----- -$ *exception_port_tool --show-task --show-new-task \ - --show-bootstrap=com.apple.ReportCrash --show-bootstrap=svc \ - --set-handler=behavior=DEFAULT,handler=bootstrap:svc crash* -service com.apple.ReportCrash 0xe03 -service svc 0x1003 -task exception port 0, mask 0x400 (CRASH), port 0xe03, -behavior 0x80000003 (STATE_IDENTITY|MACH), flavor 7 (THREAD) -new task exception port 0, mask 0x400 (CRASH), port 0x1003, -behavior 0x1 (DEFAULT), flavor 13 (NONE) -Illegal instruction: 4 ----- - -Shows the task-level exception ports for the process with PID 1234. This -requires superuser permissions or the approval of taskgated(8). -[subs="quotes"] ----- -# *exception_port_tool --pid=1234 --show-task* -task exception port 0, mask 0x4e -(BAD_ACCESS|BAD_INSTRUCTION|ARITHMETIC|BREAKPOINT), port 0x1503, -behavior 0x1 (DEFAULT), flavor 13 (NONE) -task exception port 1, mask 0x1c00 (CRASH|RESOURCE|GUARD), -port 0x1403, behavior 0x80000003 (STATE_IDENTITY|MACH), -flavor 7 (THREAD) ----- - -== Exit Status - -*0*:: -Success. - -*125*:: -Failure, with a message printed to the standard error stream. - -*126*:: -The program specified by 'COMMAND' was found, but could not be invoked. - -*127*:: -The program specified by 'COMMAND' could not be found. - -== See Also - -man_link:catch_exception_tool[1], -man_link:on_demand_service_tool[1] - -include::../../doc/support/man_footer.ad[] diff --git a/tools/mac/exception_port_tool.md b/tools/mac/exception_port_tool.md new file mode 100644 index 00000000..37cbb265 --- /dev/null +++ b/tools/mac/exception_port_tool.md @@ -0,0 +1,234 @@ + + +# exception_port_tool(1) + +## Name + +exception_port_tool—Show and change Mach exception ports + +## Synopsis + +**exception_port_tool** [_OPTION…_] [_COMMAND_ [_ARG…_]] + +## Description + +Shows Mach exception ports registered for a thread, task, or host target with a +__--show-*__ option, changes Mach exception ports with **--set-handler**, shows +changes with a __--show-new-*__ option, and executes _COMMAND_ along with any +arguments specified (_ARG…_) with the changed exception ports in effect. + +## Options + + * **-s**, **--set-handler**=_DESCRIPTION_ + + Set an exception port to _DESCRIPTION_. This option may appear zero, one, or + more times. + + _DESCRIPTION_ is formatted as a comma-separated sequence of tokens, where + each token consists of a key and value separated by an equals sign. These + keys are recognized: + + * **target**=_TARGET_ + + _TARGET_ defines which target’s exception ports to set: **host**, + **task**, or **thread**. The default value of _TARGET_ is **task**. + Operations on **host** are restricted to the superuser. + + * **mask**=_MASK_ + + _MASK_ defines the mask of exception types to handle, from + ``. This can be **BAD_ACCESS**, + **BAD_INSTRUCTION**, **ARITHMETIC**, **EMULATION**, **SOFTWARE**, + **BREAKPOINT**, **SYSCALL**, **MACH_SYSCALL**, **RPC_ALERT**, **CRASH**, + **RESOURCE**, **GUARD**, or **CORPSE_NOTIFY**. Different exception types + may be combined by combining them with pipe characters (**|**). The + special value **ALL** includes each exception type except for **CRASH** + and **CORPSE_NOTIFY**. To truly specify all exception types including + these, use **ALL|CRASH|CORPSE_NOTIFY**. The default value of _MASK_ is + **CRASH**. + + * **behavior**=_BEHAVIOR_ + + _BEHAVIOR_ defines the specific exception handler routine to be called + when an exception occurs. This can be **DEFAULT**, **STATE**, or + **STATE_IDENTITY**. **MACH** may also be specified by combining them with + pipe characters (**|**). The most complete set of exception information is + provided with **STATE_IDENTITY|MACH**. Not all exception servers implement + all possible behaviors. The default value of _BEHAVIOR_ is + **DEFAULT|MACH**. + + * **flavor**=_FLAVOR_ + + For state-carrying values of _BEHAVIOR_ (those including **STATE** or + **STATE_IDENTITY**), _FLAVOR_ specifies the architecture-specific thread + state flavor to be provided to the exception handler. For the x86 family, + this can be **THREAD**, **THREAD32**, **THREAD64**, **FLOAT**, + **FLOAT32**, **FLOAT64**, **DEBUG**, **DEBUG32**, or **DEBUG64**. The + default value of _FLAVOR_ is **NONE**, which is not valid for + state-carrying values of _BEHAVIOR_. + + * **handler**=_HANDLER_ + + _HANDLER_ defines the exception handler. **NULL** indicates that any + existing exception port should be cleared. _HANDLER_ may also take the + form **bootstrap**:_SERVICE_, which will look _SERVICE_ up with the + bootstrap server and set that service as the exception handler. The + default value of _HANDLER_ is **NULL**. + + * **--show-bootstrap**=_SERVICE_ + + Looks up _SERVICE_ with the bootstrap server and shows it. Normally, the + handler port values displayed by the other __--show-*__ options are + meaningless handles, but by comparing them to the port values for known + bootstrap services, it is possible to verify that they are set as intended. + + * **-p**, **--pid**=_PID_ + + For operations on the task target, including **--set-handler** with _TARGET_ + set to **task**, **--show-task**, and **--show-new-task**, operates on the + task associated with process id _PID_ instead of the current task associated + with the tool. When this option is supplied, _COMMAND_ must not be specified. + + This option uses `task_for_pid()` to access the process’ task port. This + operation may be restricted to use by the superuser, executables signed by an + authority trusted by the system, and processes otherwise permitted by + taskgated(8). Consequently, this program must normally either be signed or be + invoked by root to use this option. It is possible to install this program as + a setuid root executable to overcome this limitation. However, it is not + possible to use this option to operate on processes protected by [System + Integrity Protection (SIP)](https://support.apple.com/HT204899), including + those whose “restrict” codesign(1) option is respected. + + * **-h**, **--show-host** + + Shows the original host exception ports before making any changes requested + by **--set-handler**. This option is restricted to the superuser. + + * **-t**, **--show-task** + + Shows the original task exception ports before making any changes requested + by **--set-handler**. + + * **--show-thread** + + Shows the original thread exception ports before making any changes requested + by **--set-handler**. + + * **-H**, **--show-new-host** + + Shows the modified host exception ports after making any changes requested by + **--set-handler**. This option is restricted to the superuser. + + * **-T**, **--show-new-task** + + Shows the modified task exception ports after making any changes requested by + **--set-handler**. + + * **--show-new-thread** + + Shows the modified thread exception ports after making any changes requested + by **--set-handler** + + * **-n**, **--numeric** + + For __--show-*__ options, all values will be displayed numerically only. The + default is to decode numeric values and display them symbolically as well. + + * **--help** + + Display help and exit. + + * **--version** + + Output version information and exit. + +## Examples + +Sets a new task-level exception handler for `EXC_CRASH`-type exceptions to the +handler registered with the bootstrap server as `svc`, showing the task-level +exception ports before and after the change. The old and new exception handlers +are verified by their service names as registered with the bootstrap server. +With the new task-level exception ports in effect, a program is run. + +``` +$ exception_port_tool --show-task --show-new-task \ + --show-bootstrap=com.apple.ReportCrash --show-bootstrap=svc \ + --set-handler=behavior=DEFAULT,handler=bootstrap:svc crash +service com.apple.ReportCrash 0xe03 +service svc 0x1003 +task exception port 0, mask 0x400 (CRASH), port 0xe03, behavior 0x80000003 (STATE_IDENTITY|MACH), flavor 7 (THREAD) +new task exception port 0, mask 0x400 (CRASH), port 0x1003, behavior 0x1 (DEFAULT), flavor 13 (NONE) +Illegal instruction: 4 +``` + +Shows the task-level exception ports for the process with PID 1234. This +requires superuser permissions or the approval of taskgated(8), and the process +must not be SIP-protected. + +``` +# exception_port_tool --pid=1234 --show-task +task exception port 0, mask 0x4e (BAD_ACCESS|BAD_INSTRUCTION|ARITHMETIC|BREAKPOINT), port 0x1503, behavior 0x1 (DEFAULT), flavor 13 (NONE) +task exception port 1, mask 0x1c00 (CRASH|RESOURCE|GUARD), port 0x1403, behavior 0x80000003 (STATE_IDENTITY|MACH), flavor 7 (THREAD) +``` + +## Exit Status + + * **0** + + Success. + + * **125** + + Failure, with a message printed to the standard error stream. + + * **126** + + The program specified by _COMMAND_ was found, but could not be invoked. + + * **127** + + The program specified by _COMMAND_ could not be found. + +## See Also + +[catch_exception_tool(1)](catch_exception_tool.md), +[on_demand_service_tool(1)](on_demand_service_tool.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. diff --git a/tools/mac/on_demand_service_tool.ad b/tools/mac/on_demand_service_tool.ad deleted file mode 100644 index 5db4713f..00000000 --- a/tools/mac/on_demand_service_tool.ad +++ /dev/null @@ -1,102 +0,0 @@ -// 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 - -= on_demand_service_tool(1) - -== Name - -on_demand_service_tool - Load and unload on-demand Mach services registered with -launchd(8) - -== Synopsis - -[verse] -*on_demand_service_tool* *-L* *-l* 'LABEL' ['OPTION…'] 'COMMAND' ['ARG…'] -*on_demand_service_tool* *-U* *-l* 'LABEL' - -== Description - -On-demand services may be registered with launchd(8) by using the *--load* form. -One or more service names may be registered with the bootstrap server by -specifying *--mach-service*. When a Mach message is sent to any of these -services, launchd(8) will invoke 'COMMAND' along with any arguments specified -('ARG…'). 'COMMAND' must be an absolute pathname. - -The *--unload* form unregisters jobs registered with launchd(8). - -== Options - -*-L*, *--load*:: -Registers a job with launchd(8). *--label*='LABEL' and 'COMMAND' are required. -This operation may also be referred to as “load” or “submit”. - -*-U*, *--unload*:: -Unregisters a job with launchd(8). *--label*='LABEL' is required. This operation -may also be referred to as “unload” or “remove”. - -*-l*, *--label*='LABEL':: -'LABEL' is used as the job label to identify the job to launchd(8). 'LABEL' must -be unique within a launchd(8) context. - -*-m*, *--mach-service*='SERVICE':: -In conjunction with *--load*, registers 'SERVICE' with the bootstrap server. -Clients will be able to obtain a send right by looking up the 'SERVICE' name -with the bootstrap server. When a message is sent to such a Mach port, -launchd(8) will invoke 'COMMAND' along with any arguments specified ('ARG…') if -it is not running. This forms the “on-demand” nature referenced by this tool’s -name. This option may appear zero, one, or more times. 'SERVICE' must be unique -within a bootstrap context. - -*--help*:: -Display help and exit. - -*--version*:: -Output version information and exit. - -== Examples - -Registers an on-demand server that will execute man_link:catch_exception_tool[1] -when a Mach message is sent to a Mach port obtained from the bootstrap server by -looking up the name +svc+: -[subs="quotes"] ----- -$ *on_demand_service_tool --load --label=catch_exception \ - --mach-service=svc \ - $(which catch_exception_tool) --mach-service=svc \ - --file=/tmp/out --persistent --timeout=0* ----- - -Unregisters the on-demand server installed above: -[subs="quotes"] ----- -$ *on_demand_service_tool --unload --label=catch_exception* ----- - -== 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:exception_port_tool[1], -launchctl(1) - -include::../../doc/support/man_footer.ad[] diff --git a/tools/mac/on_demand_service_tool.md b/tools/mac/on_demand_service_tool.md new file mode 100644 index 00000000..5a850352 --- /dev/null +++ b/tools/mac/on_demand_service_tool.md @@ -0,0 +1,133 @@ + + +# on_demand_service_tool(1) + +## Name + +on_demand_service_tool—Load and unload on-demand Mach services registered with +launchd(8) + +## Synopsis + +**on_demand_service_tool** **-L** **-l** _LABEL_ [_OPTION…_] _COMMAND_ +[_ARG…_]
+**on_demand_service_tool** **-U** **-l** _LABEL_ + +## Description + +On-demand services may be registered with launchd(8) by using the **--load** +form. One or more service names may be registered with the bootstrap server by +specifying **--mach-service**. When a Mach message is sent to any of these +services, launchd(8) will invoke _COMMAND_ along with any arguments specified +(_ARG…_). _COMMAND_ must be an absolute pathname. + +The **--unload** form unregisters jobs registered with launchd(8). + +## Options + + * **-L**, **--load** + + Registers a job with launchd(8). **--label**=_LABEL_ and _COMMAND_ are + required. This operation may also be referred to as “load” or “submit”. + + * **-U**, **--unload** + + Unregisters a job with launchd(8). **--label**=_LABEL_ is required. This + operation may also be referred to as “unload” or “remove”. + + * **-l**, **--label**=_LABEL_ + + _LABEL_ is used as the job label to identify the job to launchd(8). _LABEL_ + must be unique within a launchd(8) context. + + * **-m**, **--mach-service**=_SERVICE_ + + In conjunction with **--load**, registers _SERVICE_ with the bootstrap + server. Clients will be able to obtain a send right by looking up the + _SERVICE_ name with the bootstrap server. When a message is sent to such a + Mach port, launchd(8) will invoke _COMMAND_ along with any arguments + specified (_ARG…_) if it is not running. This forms the “on-demand” nature + referenced by this tool’s name. This option may appear zero, one, or more + times. _SERVICE_ must be unique within a bootstrap context. + + * **--help** + + Display help and exit. + + * **--version** + + Output version information and exit. + +## Examples + +Registers an on-demand server that will execute +[catch_exception_tool(1)](catch_exception_tool.md) when a Mach message is sent +to a Mach port obtained from the bootstrap server by looking up the name `svc`: + +``` +$ on_demand_service_tool --load --label=catch_exception \ + --mach-service=svc \ + $(which catch_exception_tool) --mach-service=svc \ + --file=/tmp/out --persistent --timeout=0 +``` + +Unregisters the on-demand server installed above: + +``` +$ on_demand_service_tool --unload --label=catch_exception +``` + +## Exit Status + + * **0** + + Success. + + * **1** + + Failure, with a message printed to the standard error stream. + +## See Also + +[catch_exception_tool(1)](catch_exception_tool.md), +[exception_port_tool(1)](exception_port_tool.md), +launchctl(1) + +## 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. diff --git a/tools/mac/run_with_crashpad.ad b/tools/mac/run_with_crashpad.ad deleted file mode 100644 index 129488a3..00000000 --- a/tools/mac/run_with_crashpad.ad +++ /dev/null @@ -1,112 +0,0 @@ -// 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 - -= run_with_crashpad(1) - -== Name - -run_with_crashpad - Run a program with a Crashpad exception handler - -== Synopsis - -[verse] -*run_with_crashpad* ['OPTION…'] 'COMMAND' ['ARG…'] - -== Description - -Starts a Crashpad exception handler server such as crashpad_handler(8) and -becomes its client, setting an exception port referencing the handler. Then, -executes 'COMMAND' along with any arguments specified ('ARG…') with the new -exception port in effect. - -The exception port is configured to receive exceptions of type +EXC_CRASH+, -+EXC_RESOURCE+, and +EXC_GUARD+. The exception behavior is configured as -+EXCEPTION_STATE_IDENTITY | MACH_EXCEPTION_CODES+. The thread state flavor is -set to +MACHINE_THREAD_STATE+. - -Programs that use the Crashpad client library directly will not normally use -this tool. This tool exists to allow programs that are unaware of Crashpad to be -run with a Crashpad exception handler. - -== Options -*-h*, *--handler*='HANDLER':: -Invoke 'HANDLER' as the Crashpad handler program instead of the default, -*crashpad_handler*. - -*--annotation*='KEY=VALUE':: -Passed to the Crashpad handler program as an *--annotation* argument. - -*--database*='PATH':: -Passed to the Crashpad handler program as its *--database* argument. - -*--url*='URL':: -Passed to the Crashpad handler program as its *--url* argument. - -*-a*, *--argument*='ARGUMENT':: -Invokes the Crashpad handler program with 'ARGUMENT' as one of its arguments. -This option may appear zero, one, or more times. If this program has a specific -option such as *--database* matching the desired Crashpad handler program -option, the specific option should be used in preference to *--argument*. -Regardless of this option’s presence, the handler will always be invoked with -the necessary arguments to perform a handshake. - -*--help*:: -Display help and exit. - -*--version*:: -Output version information and exit. - -== Examples - -Starts a Crashpad exception handler server by its default name, -*crashpad_handler*, and runs a program with this handler in effect. -[subs="quotes"] ----- -$ *run_with_crashpad --database=/tmp/crashpad_database crash* -Illegal instruction: 4 ----- - -Starts a Crashpad exception handler server at a nonstandard path, and runs -man_link:exception_port_tool[1] to show the task-level exception ports. -[subs="quotes"] ----- -$ *run_with_crashpad --handler=/tmp/crashpad_handler \ - --database=/tmp/crashpad_database exception_port_tool \ - --show-task* -task exception port 0, mask 0x1c00 (CRASH|RESOURCE|GUARD), port -0x30b, behavior 0x80000003 (STATE_IDENTITY|MACH), flavor 7 (THREAD) ----- - -== Exit Status - -*0*:: -Success. - -*125*:: -Failure, with a message printed to the standard error stream. - -*126*:: -The program specified by 'COMMAND' was found, but could not be invoked. - -*127*:: -The program specified by 'COMMAND' could not be found. - -== See Also - -man_link:crashpad_handler[8], -man_link:exception_port_tool[1] - -include::../../doc/support/man_footer.ad[] diff --git a/tools/mac/run_with_crashpad.md b/tools/mac/run_with_crashpad.md new file mode 100644 index 00000000..0efcc371 --- /dev/null +++ b/tools/mac/run_with_crashpad.md @@ -0,0 +1,147 @@ + + +# run_with_crashpad(1) + +## Name + +run_with_crashpad—Run a program with a Crashpad exception handler + +## Synopsis + +**run_with_crashpad** [_OPTION…_] _COMMAND_ [_ARG…_] + +## Description + +Starts a Crashpad exception handler server such as +[crashpad_handler(8)](../../handler/crashpad_handler.md) and becomes its client, +setting an exception port referencing the handler. Then, executes _COMMAND_ +along with any arguments specified (_ARG…_) with the new exception port in +effect. + +The exception port is configured to receive exceptions of type `EXC_CRASH`, +`EXC_RESOURCE`, and `EXC_GUARD`. The exception behavior is configured as +`EXCEPTION_STATE_IDENTITY | MACH_EXCEPTION_CODES`. The thread state flavor is +set to `MACHINE_THREAD_STATE`. + +Programs that use the Crashpad client library directly will not normally use +this tool. This tool exists to allow programs that are unaware of Crashpad to be +run with a Crashpad exception handler. + +## Options + + * **-h**, **--handler**=_HANDLER_ + + Invoke 'HANDLER' as the Crashpad handler program instead of the default, + **crashpad_handler**. + + * **--annotation**=_KEY=VALUE_ + + Passed to the Crashpad handler program as an **--annotation** argument. + + * **--database**=_PATH_ + + Passed to the Crashpad handler program as its **--database** argument. + + * **--url**=_URL_ + + Passed to the Crashpad handler program as its **--url** argument. + + * **-a**, **--argument**=_ARGUMENT_ + + Invokes the Crashpad handler program with _ARGUMENT_ as one of its arguments. + This option may appear zero, one, or more times. If this program has a + specific option such as **--database** matching the desired Crashpad handler + program option, the specific option should be used in preference to + **--argument**. Regardless of this option’s presence, the handler will always + be invoked with the necessary arguments to perform a handshake. + + * **--help** + + Display help and exit. + + * **--version** + + Output version information and exit. + +## Examples + +Starts a Crashpad exception handler server by its default name, +**crashpad_handler**, and runs a program with this handler in effect. + +``` +$ run_with_crashpad --database=/tmp/crashpad_database crasher +Illegal instruction: 4 +``` + +Starts a Crashpad exception handler server at a nonstandard path, and runs +[exception_port_tool(1)](exception_port_tool.md) to show the task-level +exception ports. + +``` +$ run_with_crashpad --handler=/tmp/crashpad_handler \ + --database=/tmp/crashpad_database exception_port_tool \ + --show-task +task exception port 0, mask 0x1c00 (CRASH|RESOURCE|GUARD), port 0x30b, behavior 0x80000003 (STATE_IDENTITY|MACH), flavor 7 (THREAD) +``` + +## Exit Status + + * **0** + + Success. + + * **125** + + Failure, with a message printed to the standard error stream. + + * **126** + + The program specified by 'COMMAND' was found, but could not be invoked. + + * **127** + + The program specified by 'COMMAND' could not be found. + +## See Also + +[crashpad_handler(8)](../../handler/crashpad_handler.md), +[exception_port_tool(1)](exception_port_tool.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.