SymInitialize 函数 (dbghelp.h)

项目
03/11/2023

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

语法

BOOL IMAGEAPI SymInitialize(
  [in]           HANDLE hProcess,
  [in, optional] PCSTR  UserSearchPath,
  [in]           BOOL   fInvadeProcess
);

参数

[in] hProcess

标识调用方的句柄。此值应是唯一且不为零的，但不需要是进程句柄。但是，如果使用进程句柄，请务必使用正确的句柄。如果应用程序是调试器，请使用正在调试的进程的进程句柄。请勿使用 GetCurrentProcess 返回的句柄。使用的句柄必须是唯一的，以避免与其他组件共享会话，并且当多个组件尝试使用 dbghelp 检查当前进程时，使用 GetCurrentProcess 可能会产生意外结果。调试另一个进程时使用 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 。如果对 SymInitialize 的调用将 fInvadeProcess 设置为 TRUE ，并且只需重新加载模块列表，请使用 SymRefreshModuleList 函数。

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

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