SymInitializeW 函数（dbghelp.h）

项目
11/20/2024

初始化进程的符号处理程序。

语法

BOOL IMAGEAPI SymInitializeW(
  [in]           HANDLE hProcess,
  [in, optional] PCWSTR UserSearchPath,
  [in]           BOOL   fInvadeProcess
);

参数

[in] hProcess

标识调用方句柄。此值应是唯一且非零的，但不需要是进程句柄。但是，如果使用进程句柄，请务必使用正确的句柄。如果应用程序是调试器，请使用正在调试的进程的进程句柄。调试另一个进程时，请勿使用由 GetCurrentProcess 返回的句柄，因为调用 SymLoadModuleEx 等函数可能会产生意外的结果。

此参数不能 NULL。

[in, optional] UserSearchPath

用分号（;)）分隔的路径或一系列路径，用于搜索符号文件。如果此参数 NULL，则库将尝试形成来自以下源的符号路径：

应用程序的当前工作目录
_NT_SYMBOL_PATH环境变量
_NT_ALTERNATE_SYMBOL_PATH环境变量

请注意，也可以使用 SymSetSearchPath 函数设置搜索路径。

[in] fInvadeProcess

如果此值 TRUE，则枚举进程的已加载模块，并有效地为每个模块调用 SymLoadModule64 函数。

返回值

如果函数成功，则返回值 TRUE。

如果函数失败，则返回值 FALSE。若要检索扩展的错误信息，请调用 GetLastError。

言论

SymInitialize 函数用于初始化进程的符号处理程序。在符号处理程序的上下文中，在收集符号信息时，进程是一个方便的对象。通常，符号处理程序由调试程序和其他工具使用，这些工具需要为正在调试的进程加载符号。

传递给 SymInitialize 的句柄必须与传递给进程调用的所有其他符号处理程序函数的值相同。函数用于标识调用方并找到正确的符号信息的句柄。使用符号信息完成后，调用 SymCleanup 函数以解除分配与加载符号的进程关联的所有资源。

搜索符号文件以递归方式对 UserSearchPath 参数中指定的所有路径执行。因此，如果在搜索中指定根目录，则会搜索整个驱动器，这可能需要很长时间。请注意，包含进程的可执行文件的目录不会自动属于搜索路径。若要将此目录包含在搜索路径中，请调用 GetModuleFileNameEx 函数，然后添加返回给 UserSearchPath的路径。

调用 SymInitialize 的进程不应再次调用它，除非它首先调用 SymCleanup。如果调用 SymInitializefInvadeProcess 设置为 TRUE，并且只需重新加载模块列表，请使用 SymRefreshModuleList 函数。

所有 DbgHelp 函数（如此函数）都是单线程的。因此，从多个线程调用此函数可能会导致意外行为或内存损坏。为了避免这种情况，请仅在进程启动时调用 symInitialize ，并且仅在进程结束时 SymCleanup。进程中的每个线程都不需要调用这些函数。

若要调用此函数的 Unicode 版本，请定义DBGHELP_TRANSLATE_TCHAR。