沒畫完的畫

本文內容摘自MSDN，如有翻譯不當之處，敬請指正

BOOL WINAPI SymInitialize
(
  __in      HANDLE hProcess,
  __in_opt  PCTSTR UserSearchPath,
  __in      BOOL fInvadeProcess
);

參數:

hProcess [in]

A handle that identifies the caller. This value should be unique and nonzero, but need not be a process handle. However, if you do use a process handle, be sure to use the correct handle. If the application is a debugger, use the process handle for the process being debugged. Do not use the handle returned by GetCurrentProcess when debugging another process, because calling functions like SymLoadModuleEx can have unexpected results.

This parameter cannot be NULL.

調用者的句柄識別符. 這個值是獨一無二而且非零，可以不是進程的句柄.然而，如果你用進程的句柄的話,必須確定它是一個合法的句柄.如果你寫的應用程序是一個調試器，在進程調試的時候使用進程名柄.  在調試其它進程時不要使用GetCurrentProcess()返回的句柄，不然在調用像 SymLoadModuleEx 這些函數時會有異想不到的后果.

 

UserSearchPath [in, optional]

The path, or series of paths separated by a semicolon (;), that is used to search for symbol files. If this parameter is NULL, the library attempts to form a symbol path from the following sources:

• The current working directory of the application
• The _NT_SYMBOL_PATH environment variable
• The _NT_ALTERNATE_SYMBOL_PATH environment variable

Note that the search path can also be set using the SymSetSearchPath function.

路徑, 也可以是用分號隔開的多個路徑, 用來搜索符號文件(.pdb). 如果這個參數為 NULL, 那么搜索符號文件的路徑時會按照這樣的順序來找

. 當前應用程序的工作目錄

. 環境變量 _NT_SYMBOL_PATH  指向的路徑

. 環境變量 _NT_ALTERNATE_SYMBOL_PATH 指向的路徑 

 

fInvadeProcess [in]

If this value is TRUE, enumerates the loaded modules for the process and effectively calls the SymLoadModule64 function for each module.
如果這個參數為TRUE， 將列出進程所調用的模塊和保證每個模塊有效地調用 SymLoadModule64 函數

  Return Value

If the function succeeds, the return value is TRUE.

If the function fails, the return value is FALSE. To retrieve extended error information, call GetLastError.
返回TRUE，表示成功，返回FALSE，表示失敗，調用 GetLastError() 獲取更多信息

Remarks

The SymInitialize function is used to initialize the symbol handler for a process. In the context of the symbol handler, a process is a convenient object to use when collecting symbol information. Usually, symbol handlers are used by debuggers and other tools that need to load symbols for a process being debugged.

SymInitialize用來為進程初始化符號處理器, 在符號處理器收集符號信息時，一個進程需要使用一個合適的對象.
通常, 符號處理器用于 調試器 和 其它加載另一個正在調試的進程的符號的工具

The handle passed to SymInitialize must be the same value passed to all other symbol handler functions called by the process. It is the handle that the functions use to identify the caller and locate the correct symbol information. When you have finished using the symbol information, call the SymCleanup function to deallocate all resources associated with the process for which symbols are loaded.
傳遞給SymInitialize 函數的句柄必須與調用其它 符號處理器函數時所傳遞的句柄相同. 這個句柄用于識別調用者和定位正確的符號信息. 當使用完符號處理后，調用
SymCleanup 函數釋放加載符號的進程的相關資源

The search for symbols files is performed recursively for all paths specified in the UserSearchPath parameter. Therefore, if you specify the root directory in a search, the whole drive is searched, which can take significant time. Note that the directory that contains the executable file for the process is not automatically part of the search path. To include this directory in the search path, call the GetModuleFileNameEx function, then add the path returned to UserSearchPath.
 查找符號文件(.pdb) 需要 UserSearchPath 參數提供的所有路徑. 然而, 如果指定根目錄查找, 將搜索所有的驅動器，這會花很多時間.
需要注意可執行文件所在的目錄，并非自動搜索的范圍. 可以通過調用 GetModuleFileNameEx 把程序所在的路徑包含進去

A process that calls SymInitialize should not call it again unless it calls SymCleanup first. If the call to SymInitialize set fInvadeProcess to TRUE and you simply need to reload the module list, use the SymRefreshModuleList function.
一個進程在調用 SymCleanup 之前不能再調用 SymInitialize. 如果調用 SymInitialize 時設置  fInvadeProcess 為 TRUE, 你只需要調用 SymRefreshModuleList 就可以重新加載模塊列表

All DbgHelp functions, such as this one, are single threaded. Therefore, calls from more than one thread to this function will likely result in unexpected behavior or memory corruption. To avoid this, call SymInitialize only when your process starts and SymCleanup only when your process ends. It is not necessary for each thread in the process to call these functions.

To call the Unicode version of this function, define DBGHELP_TRANSLATE_TCHAR.
所有的 DbgHelp 函數都是單線程的, 像本函數也是，然而, 在多個線程里調用本函數會造成不可遇知的后果或內存崩潰.
只在進程開始時調用 SymInitialize且只在進程結束時調用 SymCleanUp 就可以避免了.沒必要每個線程都調用這些函數.