Struct minidump::Minidump

pub struct Minidump<'a, T>
where
    T: Deref<Target = [u8]> + 'a,
{
    pub header: MINIDUMP_HEADER,
    pub endian: Endian,
    /* private fields */
}

An index into the contents of a minidump.

The Minidump struct represents the parsed header and indices contained at the start of a minidump file. It can be instantiated by calling the Minidump::read or Minidump::read_path methods.

Examples

use minidump::Minidump;

let dump = Minidump::read_path("../testdata/test.dmp")?;

Fields

header: MINIDUMP_HEADER

The raw minidump header from the file.

endian: Endian

The endianness of this minidump file.

Implementations

impl Minidump<'static, Mmap>

pub fn read_path<P>(path: P) -> Result<MmapMinidump, Error>

where P: AsRef<Path>,

Read a Minidump from a Path to a file on disk.

See the type definition for an example.

impl<'a, T> Minidump<'a, T>

where T: Deref<Target = [u8]> + 'a,

pub fn read(data: T) -> Result<Minidump<'a, T>, Error>

Read a Minidump from the provided data.

Typically this will be a Vec<u8> or &[u8] with the full contents of the minidump, but you can also use something like memmap::Mmap.

pub fn get_stream<S>(&'a self) -> Result<S, Error>

where S: MinidumpStream<'a>,

Read and parse the specified MinidumpStream S from the Minidump, if it exists.

Because Minidump Streams can have totally different formats and meanings, the only way to coherently access one is by specifying a static type that provides an interpretation and interface of that format.

As such, typical usage of this interface is to just statically request every stream your care about. Depending on what analysis you’re trying to perform, you may:

• Consider it an error for a stream to be missing (using ? or unwrap)
• Branch on the presence of stream to conditionally refine your analysis
• Use a stream’s Default implementation to make progress (with unwrap_or_default)

use minidump::*;

fn main() -> Result<(), Error> {
    // Read the minidump from a file
    let mut dump = minidump::Minidump::read_path("../testdata/test.dmp")?;

    // Statically request (and require) several streams we care about:
    let system_info = dump.get_stream::<MinidumpSystemInfo>()?;
    let exception = dump.get_stream::<MinidumpException>()?;

    // Combine the contents of the streams to perform more refined analysis
    let crash_reason = exception.get_crash_reason(system_info.os, system_info.cpu);

    // Conditionally analyze a stream
    if let Ok(threads) = dump.get_stream::<MinidumpThreadList>() {
        // Use `Default` to try to make some progress when a stream is missing.
        // This is especially natural for MinidumpMemoryList because
        // everything needs to handle memory lookups failing anyway.
        let mem = dump.get_memory().unwrap_or_default();

        for thread in &threads.threads {
           let stack = thread.stack_memory(&mem);
           // ...
        }
    }

    Ok(())
}

Some streams are impossible to fully parse/interpret without the contents of other streams (for instance, many things require MinidumpSystemInfo to interpret hardware-specific details). As a result, some parsing of the stream may be further deferred to methods on the Stream type where those dependencies can be provided (e.g. MinidumpException::get_crash_reason).

Note that the lifetime of the returned stream is bound to the lifetime of the Minidump struct itself and not to the lifetime of the data backing this minidump. This is a consequence of how this struct relies on Deref to access the data.

Currently Supported Streams

• MinidumpAssertion
• MinidumpBreakpadInfo
• MinidumpCrashpadInfo
• MinidumpException
• MinidumpLinuxCpuInfo
• MinidumpLinuxEnviron
• MinidumpLinuxLsbRelease
• MinidumpLinuxMaps
• MinidumpLinuxProcStatus
• MinidumpMacCrashInfo
• MinidumpMacBootargs
• MinidumpMemoryList
• MinidumpMemory64List
• MinidumpMemoryInfoList
• MinidumpMiscInfo
• MinidumpModuleList
• MinidumpSystemInfo
• MinidumpThreadList
• MinidumpThreadNames
• MinidumpUnloadedModuleList
• MinidumpHandleDataStream

pub fn get_raw_stream(&'a self, stream_type: u32) -> Result<&'a [u8], Error>

Get a stream of raw data from the minidump.

This can be used to get the contents of arbitrary minidump streams. For streams of known types you almost certainly want to use Minidump::get_stream instead.

Note that the lifetime of the returned stream is bound to the lifetime of the this Minidump struct itself and not to the lifetime of the data backing this minidump. This is a consequence of how this struct relies on Deref to access the data.

pub fn get_memory(&'a self) -> Option<UnifiedMemoryList<'a>>

Get whichever of the two MemoryLists are available in the minidump, preferring MinidumpMemory64List.

pub fn unimplemented_streams( &self ) -> impl Iterator<Item = MinidumpUnimplementedStream> + '_

A listing of all the streams in the Minidump that this library is aware of, but has no further analysis for.

If there are multiple copies of the same stream type (which should not happen for well-formed Minidumps), then only one of them will be yielded, arbitrarily.

pub fn unknown_streams( &self ) -> impl Iterator<Item = MinidumpUnknownStream> + '_

A listing of all the streams in the Minidump that this library has no knowledge of.

If there are multiple copies of the same stream (which should not happen for well-formed Minidumps), then only one of them will be yielded, arbitrarily.

pub fn all_streams(&self) -> impl Iterator<Item = &MINIDUMP_DIRECTORY> + '_

A listing of all the streams in the Minidump.

If there are multiple copies of the same stream (which should not happen for well-formed Minidumps), then only one of them will be yielded, arbitrarily.

pub fn print<W: Write>(&self, f: &mut W) -> Result<()>

Write a verbose description of the Minidump to f.

Trait Implementations

impl<'a, T> Debug for Minidump<'a, T>

where T: Deref<Target = [u8]> + 'a + Debug,

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.