Generate Dump File from a Process Snapshot

  • Article

[Some information relates to pre-released product which may be substantially modified before it's commercially released. Microsoft makes no warranties, express or implied, with respect to the information provided here.]

You can generate a process snapshot dump file by using the MiniDumpWriteDump function provided by the Debug help library. The contents of a dump file are mostly identical to a dump generated by calling MiniDumpWriteDump on a live process. Specify the type of information the function dumps by using the MINIDUMP_TYPE enumeration.

To save the process snapshot, first get a process snapshot by using the PssCaptureSnapshot function.

Specify the process snapshot handle and process ID of the result to MiniDumpWriteDump.

The following example creates a constant that contains capture flag values. For more information, see the PSS_CAPTURE_FLAGS enumeration.

DWORD CaptureFlags = (DWORD)PSS_CAPTURE_VA_CLONE
                            | PSS_CAPTURE_HANDLES
                            | PSS_CAPTURE_HANDLE_NAME_INFORMATION
                            | PSS_CAPTURE_HANDLE_BASIC_INFORMATION
                            | PSS_CAPTURE_HANDLE_TYPE_SPECIFIC_INFORMATION
                            | PSS_CAPTURE_HANDLE_TRACE
                            | PSS_CAPTURE_THREADS
                            | PSS_CAPTURE_THREAD_CONTEXT
                            | PSS_CAPTURE_THREAD_CONTEXT_EXTENDED
                            | PSS_CREATE_BREAKAWAY
                            | PSS_CREATE_BREAKAWAY_OPTIONAL
                            | PSS_CREATE_USE_VM_ALLOCATIONS
                            | PSS_CREATE_RELEASE_SECTION;

The following example captures a process snapshot for the process handle specified by the ProcessHandle variable.

HANDLE SnapshotHandle;
DWORD dwResultCode = PssCaptureSnapshot (ProcessHandle,
                                         CaptureFlags,
                                         CONTEXT_ALL,
                                         &SnapshotHandle);

// Error handling omitted. Check that dwResultCode is ERROR_SUCCESS.

To tell the MiniDumpWriteDump function that the dump should be generated based on snapshot handle SnapshotHandle, respond to the IsProcessSnapshotCallback message from the MiniDumpWriteDump callback. The numeric value of IsProcessSnapshotCallback is 16.

A callback for MiniDumpWriteDump can be set up as in the following example:

ZeroMemory (&CallbackInfo, sizeof (MINIDUMP_CALLBACK_INFORMATION));
CallbackInfo.CallbackRoutine = MyMiniDumpWriteDumpCallback;
CallbackInfo.CallbackParam = NULL;

The following example shows a minimal callback implementation to respond with the snapshot handle.

BOOL CALLBACK MyMiniDumpWriteDumpCallback(
  __in     PVOID CallbackParam,
  __in     const PMINIDUMP_CALLBACK_INPUT CallbackInput,
  __inout  PMINIDUMP_CALLBACK_OUTPUT CallbackOutput
)
{
    switch (CallbackInput->CallbackType)
    {
        case 16: // IsProcessSnapshotCallback
            CallbackOutput->Status = S_FALSE;
            break;
    }
    return TRUE;
}

Case 16 of the switch sets the output status to S_FALSE. This informs MiniDumpWriteDump that the handle is a PSS snapshot handle, not a process handle. For more information about the IsProcessSnapshotCallback value, see the MINIDUMP_CALLBACK_TYPE enumeration.

The following example dumps the captured process snapshot stored at SnapshotHandle.

BOOL Success MiniDumpWriteDump ((HANDLE) SnapshotHandle,
                            ProcessId,
                            FileHandle,
                            DumpType,
                            NULL,
                            NULL,
                            &CallbackInfo);

Note

On failure, MiniDumpWriteDump sets the last error to an HRESULT.

 

The function saves the results to the file specified by the FileHandle variable. The MINIDUMP_TYPE structure specified by the DumpType variable determines what process snapshot information the function saves.

After this function saves the process snapshot information, use the PssFreeSnapshot function to release the resource, as in the following example:

PssFreeSnapshot (GetCurrentProcess(), SnapshotHandle);

For more information, see the MiniDumpWriteDump function reference and the MINIDUMP_CALLBACK_TYPE enumeration.

PSS_CAPTURE_FLAGS

MINIDUMP_CALLBACK_TYPE

MINIDUMP_TYPE

MiniDumpWriteDump

PssCaptureSnapshot

PssFreeSnapshot