符号路径

  • 项目

DbgHelp 库使用符号搜索路径查找调试符号（.pdb 和 .dbg 文件）。 搜索路径可以由一个或多个由分号分隔的路径元素组成。

指定搜索路径

若要指定符号处理程序将在磁盘目录中搜索符号文件的位置，请调用 SymSetSearchPath 函数。 或者，可以在 SymInitialize 函数的 UserSearchPath 参数中指定符号搜索路径。

SymInitialize 中的 UserSearchPath 参数和 SymSetSearchPath 中的 SearchPath 参数将获取一个指向以 null 结尾的字符串的指针，该字符串指定一个路径或一系列由分号分隔的路径。 符号处理程序使用这些路径搜索符号文件。 如果此参数为 NULL，则符号处理程序会搜索包含要对其搜索符号的模块的目录。 否则，如果此参数被指定为非 NULL 值，则符号处理程序会首先在搜索模块目录之前搜索应用程序设置的路径。 如果设置 _NT_SYMBOL_PATH 或 _NT_ALT_SYMBOL_PATH 环境变量，则符号处理程序将按以下顺序搜索符号文件：

  1. _NT_SYMBOL_PATH 环境变量。
  2. _NT_ALT_SYMBOL_PATH 环境变量。
  3. 包含相应模块的目录。

若要检索搜索路径，请调用 SymGetSearchPath 函数。

程序数据库 (.pdb) 文件的搜索路径不同于调试 (.dbg) 文件的路径。 符号库的功能确定了该算法。 默认情况下，Microsoft Visual C/C++ 会创建 Microsoft 格式符号，从映像中去除这些符号，并将其放置在单独的 .pdb 文件中。 通常，.pdb 文件将位于包含可执行映像的目录中。 Visual C/C++ 会在可执行映像中嵌入 .pdb 文件的绝对路径。 如果符号处理程序在该位置找不到 .pdb 文件，或者如果 .pdb 文件移动到了另一个目录，则符号处理程序将使用针对 .dbg 文件描述的搜索路径查找 .pdb 文件。

路径元素类型

有三种类型的路径元素。

标准路径元素

通过查找路径元素指定的目录的根目录来搜索标准路径元素。 符号处理程序还会在“symbols”的子目录中查找，此子目录与正在查找符号的模块的文件扩展名匹配。 这通常是“dll”、“exe”或“sys”。 最后，它会在目录与扩展名称相同且名为“symbols”的子目录中查找。 例如，如果符号路径元素为“c：\mySymbols”，并且要搜索的符号的文件为“boo.dll”，则会搜索以下目录。

  • c:\mySymbols
  • c:\mySymbols\dll
  • c:\mySymbols\symbols\dll

符号处理程序使用此逻辑来搜索任何不满足符号服务器或缓存条件的路径元素（如下所述）。

符号服务器路径元素

符号服务器路径元素会使用特殊技术来查找与所述模块完全匹配的符号。 请参阅使用 SymSrv 了解更多详细信息。

如果路径元素以文本“srv*”开头，则符号处理程序会将路径元素视为符号服务器。

注意

如果未指定“srv*”文本，但实际路径元素是符号服务器存储，则符号处理程序的行为方式就像指定了“srv*”一样。 符号处理程序通过在指定路径的根目录中搜索名为“pingme.txt”的文件的存在性来做出此决定。

 

缓存路径元素

缓存路径元素是符号服务器路径元素的变体。

系统会像搜索其他任何符号服务器一样搜索此目录。 但是，如果在此处找不到符号，并且该符号位于符号路径链中更远处的路径元素中，则将复制符号并将其存储在此元素中指定的符号服务器中。

如果路径元素以文本“cache*”开头，符号处理程序会将路径元素视为缓存元素。 若要在“c:\myCache”中指定缓存，请使用“cache*c:\myCache”的符号路径元素。

示例搜索路径

若要查看其工作原理，请设置此搜索路径。

cache*c:\myCache;srv*\\symbols\symbols

下面是使用上面列出的搜索路径搜索 ntdll.pdb 时符号处理程序的详细输出的列表。

DBGHELP: .\ntdll.pdb - file not found
DBGHELP: .\dll\ntdll.pdb - file not found
DBGHELP: .\symbols\dll\ntdll.pdb - file not found
SYMSRV: c:\myCache\ntdll.pdb\0F7FCF88442F4B0E9FB51DC4A754D9DE2\ntdll.pdb not found
SYMSRV: ntdll.pdb from \\symbols\symbols: 10497024 bytes - copied
DBGHELP: c:\myCache\ntdll.pdb\0F7FCF88442F4B0E9FB51DC4A754D9DE2\ntdll.pdb already cached
DBGHELP: ntdll - private symbols & lines
c:\myCache\ntdll.pdb\0F7FCF88442F4B0E9FB51DC4A754D9DE2\ntdll.pdb

前三行输出显示处理 . 的第一个路径元素的符号处理程序。 这是标准的路径元素。

第四行表明符号处理程序使用符号服务器在 cache*c:\myCache 的第二个路径元素（缓存路径元素）中查找文件。

第五行表明该文件位于 srv*\\symbols\symbols 的第三个路径元素（符号服务器路径元素）中。

第六行表明文件已复制到缓存。

最后两行表明从缓存中打开了文件。