沒畫完的畫

本文內(nèi)容摘自MSDN，如有翻譯不當(dāng)之處，敬請(qǐng)指正

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

參數(shù):

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.

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

 

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.

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

. 當(dāng)前應(yīng)用程序的工作目錄

. 環(huán)境變量 _NT_SYMBOL_PATH  指向的路徑

. 環(huán)境變量 _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.
如果這個(gè)參數(shù)為TRUE， 將列出進(jìn)程所調(diào)用的模塊和保證每個(gè)模塊有效地調(diào)用 SymLoadModule64 函數(shù)

  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，表示失敗，調(diào)用 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用來為進(jìn)程初始化符號(hào)處理器, 在符號(hào)處理器收集符號(hào)信息時(shí)，一個(gè)進(jìn)程需要使用一個(gè)合適的對(duì)象.
通常, 符號(hào)處理器用于 調(diào)試器 和 其它加載另一個(gè)正在調(diào)試的進(jìn)程的符號(hào)的工具

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 函數(shù)的句柄必須與調(diào)用其它 符號(hào)處理器函數(shù)時(shí)所傳遞的句柄相同. 這個(gè)句柄用于識(shí)別調(diào)用者和定位正確的符號(hào)信息. 當(dāng)使用完符號(hào)處理后，調(diào)用
SymCleanup 函數(shù)釋放加載符號(hào)的進(jìn)程的相關(guān)資源

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.
 查找符號(hào)文件(.pdb) 需要 UserSearchPath 參數(shù)提供的所有路徑. 然而, 如果指定根目錄查找, 將搜索所有的驅(qū)動(dòng)器，這會(huì)花很多時(shí)間.
需要注意可執(zhí)行文件所在的目錄，并非自動(dòng)搜索的范圍. 可以通過調(diào)用 GetModuleFileNameEx 把程序所在的路徑包含進(jìn)去

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.
一個(gè)進(jìn)程在調(diào)用 SymCleanup 之前不能再調(diào)用 SymInitialize. 如果調(diào)用 SymInitialize 時(shí)設(shè)置  fInvadeProcess 為 TRUE, 你只需要調(diào)用 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 函數(shù)都是單線程的, 像本函數(shù)也是，然而, 在多個(gè)線程里調(diào)用本函數(shù)會(huì)造成不可遇知的后果或內(nèi)存崩潰.
只在進(jìn)程開始時(shí)調(diào)用 SymInitialize且只在進(jìn)程結(jié)束時(shí)調(diào)用 SymCleanUp 就可以避免了.沒必要每個(gè)線程都調(diào)用這些函數(shù).