minidumpwritedump詳細解析

一、基本介紹

Windows平台提供了一個API函數名為minidumpwritedump，是一個非常有用的函數。

它可以幫助我們生成一個dump文件，這個文件能夠記錄下程序崩潰時的一些關鍵信息，例如call stack，CPU的寄存器狀態等等，這個文件對於解決問題非常有幫助。

下面我們就來詳細說明一下這個函數的使用方法。

二、函數參數

下面是函數的定義：

BOOL WINAPI MiniDumpWriteDump(
  HANDLE                            hProcess,
  DWORD                             ProcessId,
  HANDLE                            hFile,
  MINIDUMP_TYPE                     DumpType,
  PMINIDUMP_EXCEPTION_INFORMATION  ExceptionParam,
  PMINIDUMP_USER_STREAM_INFORMATION UserStreamParam,
  PMINIDUMP_CALLBACK_INFORMATION   CallbackParam
);

我們來逐一介紹這些參數：

1、hProcess

這個參數代表著Dump的進程句柄，一般這個參數填NULL，表示當前進程。

2、ProcessId

如果hProcess是NULL，那麼這個參數用來指定進程的ID，注意這個進程必須與當前進程在同一Session。

3、hFile

代表著Dump文件的句柄，可以把Dump文件寫入磁碟或任何支持寫入的非易失性存儲設備中。如果想直接列印到控制台，可以填入代表標準輸出的handle。

4、DumpType

這個參數指定生成Dump文件的類型，具體類型如下:

• MiniDumpNormal: 生成最基本的dump文件，不包含Secondary Memory.
• MiniDumpWithDataSegs: 同樣也僅包含主模塊、Call Stack和寄存器狀態，同時也有Secondary Memory的一部分（Data Sections），但是不包含堆的全量數據。
• MiniDumpWithFullMemory: 全量dump，包含了進程地址空間中的所有部分，要求調用進程需要以管理員身份運行。
• MiniDumpWithHandleData: 包含所有句柄對象的詳細信息，比較適合用來分析句柄泄露。
• MiniDumpWithUnloadedModules: 可以包含主模塊、附加模塊和卸載的模塊的明細信息。

5、ExceptionParam

這個參數是一個PMINIDUMP_EXCEPTION_INFORMATION類型指針，簡單說法它提供了一個指針，指向了一個可選的MINIDUMP_EXCEPTION_INFORMATION結構，其中包含了一個指向當前異常的指針，不能為NULL。

6、UserStreamParam

這個參數是一個PMINIDUMP_USER_STREAM_INFORMATION類型指針，支持往Dump文件添加自定義Stream。這個參數也可以為NULL，表示不給Dump文件添加用戶Stream。

7、CallbackParam

這個參數是一個PMINIDUMP_CALLBACK_INFORMATION類型指針，支持在生成Dump文件時傳入一個回調函數指針，在dump文件生成過程中可以定製一些行為，這個參數也可以為NULL，表示不需要回調函數。

三、使用示例

#include "windows.h"
#include "DbgHelp.h"

#pragma comment(lib, "Dbghelp.lib")

int Foo(int x)
{
  char* p;
  *p = 0;
  return x;
}

int main(int argc, char* argv[])
{
  LONG retVal = EXCEPTION_EXECUTE_HANDLER;
  __try
  {
    Foo(1);
  }
  __except(MiniDumpWriteDump(GetCurrentProcess(), GetCurrentProcessId(),
        CreateFile("D:/dump.dmp", GENERIC_WRITE, 0, NULL, CREATE_ALWAYS, FILE_ATTRIBUTE_NORMAL, NULL),
        MiniDumpWithFullMemory, NULL, NULL, NULL))
  {
    retVal = EXCEPTION_CONTINUE_SEARCH;
  }

  return retVal;
}

上述代碼會在main函數中調用Foo函數，而Foo函數會發生exception，然後__except中的代碼會被執行，這個時候我們就可以在__except的代碼中調用MiniDumpWriteDump。我們調用這個函數時，傳入GetCurrentProcess()和GetCurrentProcessId()即可。

如果__except捕捉到了Exception，函數返回的值為EXCEPTION_CONTINUE_SEARCH，否則返回EXCEPTION_EXECUTE_HANDLER。

四、注意事項

Dump文件大小會隨進程的大小而增長，並且可以阻止代碼執行，因此應該小心地使用。

在開發過程中只需要生成一個最小的Dump文件，然後追蹤進一步的信息即可。

生成Dump文件的性能較差，因此不應該在高頻率的代碼路徑中使用它。