SymInitialize 函數(shù)
本文內(nèi)容摘自MSDN，如有翻譯不當(dāng)之處，敬請指正
Initializes the symbol handler for a process.
為某個進(jìn)程初始化符號處理器
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)用者的句柄識別符. 這個值是獨一無二而且非零，可以不是進(jìn)程的句柄.然而，如果你用進(jìn)程的句柄的話,必須確定它是一個合法的句柄.如果你寫的應(yīng)用程序是一個調(diào)試器，在進(jìn)程調(diào)試的時候使用進(jìn)程名柄. 在調(diào)試其它進(jìn)程時不要使用GetCurrentProcess()返回的句柄，不然在調(diào)用像 SymLoadModuleEx 這些函數(shù)時會有異想不到的后果.
-
- 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). 如果這個參數(shù)為 NULL, 那么搜索符號文件的路徑時會按照這樣的順序來找
- . 當(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.
如果這個參數(shù)為TRUE， 將列出進(jìn)程所調(diào)用的模塊和保證每個模塊有效地調(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)程初始化符號處理器, 在符號處理器收集符號信息時，一個進(jìn)程需要使用一個合適的對象.
通常, 符號處理器用于 調(diào)試器 和 其它加載另一個正在調(diào)試的進(jìn)程的符號的工具
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)用其它 符號處理器函數(shù)時所傳遞的句柄相同. 這個句柄用于識別調(diào)用者和定位正確的符號信息. 當(dāng)使用完符號處理后，調(diào)用
SymCleanup 函數(shù)釋放加載符號的進(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.
查找符號文件(.pdb) 需要 UserSearchPath 參數(shù)提供的所有路徑. 然而, 如果指定根目錄查找, 將搜索所有的驅(qū)動器，這會花很多時間.
需要注意可執(zhí)行文件所在的目錄，并非自動搜索的范圍. 可以通過調(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.
一個進(jìn)程在調(diào)用 SymCleanup 之前不能再調(diào)用 SymInitialize. 如果調(diào)用 SymInitialize 時設(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ù)也是，然而, 在多個線程里調(diào)用本函數(shù)會造成不可遇知的后果或內(nèi)存崩潰.
只在進(jìn)程開始時調(diào)用 SymInitialize且只在進(jìn)程結(jié)束時調(diào)用 SymCleanUp 就可以避免了.沒必要每個線程都調(diào)用這些函數(shù).