| // 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[] |
