没画完的画

本文内容摘自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 就可以避免了.没必要每个线程都调用这些函数.