minidumper

minidumper --pid=<PID> --output=<PATH> [OPTIONS]

--pid=<PID>
    Specifies the Process ID (PID) of the target process from which the minidump will be created.

--output=<PATH>
    Defines the full path and filename for the generated minidump file.

--annotation=<KEY>=<VALUE>
    Adds a custom annotation to the minidump file. This can be used to store arbitrary key-value pairs, providing additional context relevant to the dump (e.g., version info, user ID).

--exception-info=<KEY>=<VALUE>
    Provides information about an exception if the dump is being taken in response to a crash. Used internally or for specific debugging scenarios.

--user-stream-data=<KEY>=<VALUE>
    Includes custom user-defined stream data in the minidump. Similar to annotations but typically for larger binary blobs or structured data.

--exception-code=<CODE>
    Specifies the exception code (e.g., signal number for Linux) that caused the crash, if applicable.

--exception-address=<ADDRESS>
    Indicates the memory address where the exception occurred, if applicable.

--thread-id=<ID>
    Specifies the ID of the thread that encountered the exception or is considered the 'crashing' thread.

The minidumper command is a utility designed to capture a condensed snapshot of a running process's memory, threads, and modules, saving it as a minidump file. This file format, often associated with Windows crash reporting, is cross-platform compatible and widely used for post-mortem debugging of application crashes or hangs.

Developed as part of projects like Google's Breakpad and its successor Crashpad, minidumper enables developers to collect crucial debugging information from client applications without requiring a full memory dump, which can be prohibitively large. It attaches to a target process using Linux's ptrace system call, extracts relevant state, and writes it to the specified output file. This allows for offline analysis of application failures, providing stack traces, module information, and register states, which are vital for identifying the root cause of issues in deployed software.

The minidumper command typically requires elevated privileges (e.g., root access or the CAP_SYS_PTRACE capability) to attach to and inspect other processes. It is not a standard utility bundled with all Linux distributions and is usually found as part of applications that integrate Google's Breakpad or Crashpad for crash reporting. The target process may experience a brief pause or performance degradation while the minidump is being generated. Analyzing minidumps requires specialized tools like minidump_stackwalk (from Breakpad) or a debugger configured to understand the minidump format.

Minidumps generated by minidumper are not human-readable directly. They are binary files that require specific tools for analysis. On Linux, the minidump_stackwalk utility (part of Breakpad) is commonly used to extract stack traces from the minidump, providing insights into the execution flow at the time the dump was taken. For more in-depth analysis, debuggers like GDB can be configured with extensions to load and inspect minidumps, allowing for examination of threads, modules, and memory regions.

To successfully create a minidump, minidumper relies on the Linux ptrace system call, which allows one process to control another. This typically means the user running minidumper must have the necessary permissions, such as being root, or having the CAP_SYS_PTRACE capability. Additionally, the target process must be debuggable; for instance, it should not be a kernel thread or a process that has explicitly disallowed ptrace. The command itself is not a standard part of core Linux utilities and must be installed via a package manager or compiled from source, usually as a dependency of a larger application framework.

The concept behind minidumper originated with Google's Breakpad project, an open-source cross-platform crash reporting library primarily developed for the Google Chrome browser. Breakpad aimed to provide robust crash reporting capabilities, especially for C++ applications. minidumper is a component or a similar utility used within or alongside Breakpad/Crashpad to directly capture the minidump.

Breakpad was later succeeded by Crashpad, another open-source crash-reporting system that improved upon Breakpad's design, offering better support for asynchronous crash handling and security. While the specific executable name might vary or be internal to a larger crash handler, the function of dumping process state into a minidump file is central to both projects' methodologies, making this command-line utility a direct descendant of these efforts to enable effective post-mortem debugging across operating systems.

gdb(1), ptrace(2), kill(1), proc(5)