Debugging Tools for Windows

SymStore

SymStore (symstore.exe) 是用于创建符号存储的工具。它被包含在Windows调试工具包中。

SymStore按照某种格式存储符号,使得调试器可以通过时间戳、映像大小(对于.dbg或可执行文件)、签名和寿命(.pdb文件)来查找符号。 使用符号存储而不是常规的符号存储格式的好处是,所有符号都可以在同一个服务器上进行存储或引用,而调试器不需要知道具有哪些产品对应的符号。

注意,不同版本的.pdb符号文件(例如共有和私有符号)不能保存在相同的符号服务器中,因为他们具有相同的签名和寿命。

SymStore事务

每个对SymStore的调用都被记录为事务。有两种不同的事务:添加和删除。

当创建符号存储时,一个称为"000admin"的目录会在服务器根目录下被创建。000admin 为每个事务都包含一个文件,和日志文件server.txthistory.txt一样。server.txt 文件包含当前服务器上的所有事务的列表。history.txt 文件包含所有历史事务,按时间排序。

每次SymStore存储或移除符号文件时,都会创建一个新的事务号。然后,一个以事务号为名字的文件会在000admin中创建。文件中包含所有在该事务中添加到符号存储的文件或指针地列表。如果某个事务被删除,SymStore会读取它的事务文件来决定哪些文件和指针需要删除。

adddel 选项用来指定是否进行事务添加或删除。在添加操作中包含/p 选项表示添加一个指针;忽略掉/p指定添加实际的符号文件。

也可以通过分来的两个步骤来创建符号存储。第一步,使用SymStore 和/x 选项来创建一个索引文件。第二步,使用SymStore 和/y选项通过索引文件中的信息来实际的存储文件或指针。

由于各种原因,这是一种很有用的技术。例如,这样使得符号存储由于某些原因丢失的时候能够方便的重建,只要索引文件还存在。或者包含符号文件的计算机和创建符号存储的计算机之间网络连接速度很慢时。这种情况下,可以在符号文件所在机器上创建索引文件,并将该文件传输到第二台机器,在第二台机器上创建符号存储。

SymStore参数的完整列表,查看SymStore命令行选项

注意 SymStore不支持多个用户同时发起事务。建议指派一个用户作为符号存储的"管理员"并处理所有的adddel事务。

事务示例

这里有两个SymStore在\\MyDir\symsrv 中添加Windows 2000 build 2195符号指针的示例:

symstore add /r /p /f \\BuildServer\BuildShare\2195free\symbols\*.* /s \\MyDir\symsrv /t "Windows 2000" /v "Build 2195 x86 free" /c "Sample add"
symstore add /r /p /f \\BuildServer\BuildShare\2195free\symbols\*.* /s \\MyDir\symsrv /t "Windows 2000" /v "Build 2195 x86 checked" /c "Sample add"

下面的示例中,SymStore将\\largeapp\appserver\bins 中的项目的实际的符号文件添加到\\MyDir\symsrv

symstore add /r /f \\largeapp\appserver\bins\*.* /s \\MyDir\symsrv /t "Large Application" /v "Build 432" /c "Sample add"

这是使用索引文件的示例。首先创建\\largeapp\appserver\bins\上的符号文件的索引文件。这种情况下,索引文件放在第三台计算机\\hubserver\hubshare上。 使用/g 选项来指定前缀"\\largeapp\appserver"可能会在未来改变:

symstore add /r /p /g \\largeapp\appserver /f \\largeapp\appserver\bins\*.* /x \\hubserver\hubshare\myindex.txt

假设现在将\\largeapp\appserver 机器上的所有符号文件移动到\\myarchive\appserver 上。可以使用如下方法从\\hubserver\hubshare\myindex.txt 上的索引文件创建符号存储本身:

symstore add /y \\hubserver\hubshare\myindex.txt /g \\myarchive\appserver /s \\MyDir\symsrv /p /t "Large Application" /v "Build 432" /c "Sample Add from Index"

最后,这是一个SymStore删除之前的事务中添加的文件的示例。查看后面的server.txthistory.txt文件小节获得关于事务ID的说明。(本例中为0000000096)。

symstore del /i 0000000096 /s \\MyDir\symsrv

压缩文件

SymStore可以使用两种方法使用压缩文件:

  1. 使用SymStore和/p选项来保存符号文件的指针。SymStore 完成之后,压缩指针指向的文件。
  2. 使用SymStore和/x选项来创建索引文件。SymStore完成之后,压缩索引文件中列出的文件。然后,使用SymStore和/y选项(如果愿意,也可以使用/p)来将这些文件或指针保存到符号存储。 (SymStore在这个操作中不需要解压文件。)

符号服务器会负责在适当的时候解压这些文件。

如果使用SymSrv作为符号服务器,必须使用随Microsoft Windows SDK发布的 compress.exe 工具来进行压缩。压缩文件扩展名的最后一个字符必须是下划线 (例如module1.pd_module2.db_)。详细信息,查看SymSrv

server.txt history.txt 文件

添加事务之后,会在server.txt history.txt 中添加一些信息为未来使用。下面是一次添加事务在server.txt history.txt 中产生的行的示例:

0000000096,add,ptr,10/09/99,00:08:32,Windows NT 4.0 SP 4,x86 fre 1.156c-RTM-2,Added from \\mybuilds\symbols,

这是用逗号分隔的行。下面是每个部分的说明:

字段 说明
0000000096 事务ID号,由SymStore创建
add 事务类型,这个字段可以是adddel
ptr 添加的是文件或指针。该字段可以是fileptr
10/09/99 事务发生的日期。
00:08:32 事务开始的时间。
Windows NT 产品
x86 fre 版本(可选)。
Added from 注释(可选)。
Unused (保留为以后使用)。

这是事务文件0000000096中的一些示例行。每行都记录了添加到目录中的文件或指针的目录和位置。

canon800.dbg\35d9fd51b000,\\mybuilds\symbols\sp4\dll\canon800.dbg
canonlbp.dbg\35d9fd521c000,\\mybuilds\symbols\sp4\dll\canonlbp.dbg
certadm.dbg\352bf2f48000,\\mybuilds\symbols\sp4\dll\certadm.dbg
certcli.dbg\352bf2f1b000,\\mybuilds\symbols\sp4\dll\certcli.dbg
certcrpt.dbg\352bf04911000,\\mybuilds\symbols\sp4\dll\certcrpt.dbg
certenc.dbg\352bf2f7f000,\\mybuilds\symbols\sp4\dll\certenc.dbg

如果使用del事务来撤销以前的add事务,这些行会从server.txt中删除,并添加下面这行到history.txt中:

0000000105,del,0000000096

删除事务的字段说明如下。

字段 说明
0000000105 事务ID号,SymStore创建。
del 事务类型。该字段可以是adddel
0000000096 被删除的事务。

符号存储格式

SymStore使用文件系统本身作为数据库。它创建一个大的目录树,目录名基于符号文件的时间戳、签名、寿命和其他数据。

例如一些不同的acpi.dbg添加到服务器之后,目录可能像下面一样:

Directory of \\mybuilds\symsrv\acpi.dbg
10/06/1999  05:46p      <DIR>          .
10/06/1999  05:46p      <DIR>          ..
10/04/1999  01:54p      <DIR>          37cdb03962040
10/04/1999  01:49p      <DIR>          37cdb04027740
10/04/1999  12:56p      <DIR>          37e3eb1c62060
10/04/1999  12:51p      <DIR>          37e3ebcc27760
10/04/1999  12:45p      <DIR>          37ed151662060
10/04/1999  12:39p      <DIR>          37ed15dd27760
10/04/1999  11:33a      <DIR>          37f03ce962020
10/04/1999  11:21a      <DIR>          37f03cf7277c0
10/06/1999  05:38p      <DIR>          37fa7f00277e0
10/06/1999  05:46p      <DIR>          37fa7f01620a0

这个例子中,acpi.dbg的查找路径可能像这样:\\mybuilds\symsrv\acpi.dbg\37cdb03962040

在查找目录中可能有三个文件:

  1. acpi.dbg,如果保存了该文件的话
  2. 如果保存的是指针,file.ptr 包含实际的符号文件路径。
  3. refs.ptr,包含当前被添加到符号存储中的,具有该时间戳和映像大小的acpi.dbg的当前位置的完整列表。

显示\\mybuilds\symsrv\acpi.dbg\37cdb03962040 中的目录列表如下:

10/04/1999  01:54p                  52 file.ptr
10/04/1999  01:54p                  67 refs.ptr

file.ptr 文件包含字符串"\\mybuilds\symbols\x86\2128.chk\symbols\sys\acpi.dbg"。因为该目录中没有acpi.dbg 文件,所以调试器会试图从\\mybuilds\symbols\x86\2128.chk\symbols\sys\acpi.dbg中去查找。

refs.ptr 中的内容仅被SymStore使用,而不会被调试器使用。这个文件记录该目录中发生过的所有事务的记录。refs.ptr 中的一个示例行可能像这样:

0000000026,ptr,\\mybuilds\symbols\x86\2128.chk\symbols\sys\acpi.dbg

这表明指向\\mybuilds\symbols\x86\2128.chk\symbols\sys\acpi.dbg 的指针由事务"0000000026"添加。

一些符号文件在各种产品、版本或特殊产品中保持不变。这样的一个例子是Windows 2000的文件msvcrt.pdb。列举\\mybuilds\symsrv\msvcrt.pdb 目录显示只有两个版本的msvcrt.pdb 被添加到了符号服务器上:

Directory of \\mybuilds\symsrv\msvcrt.pdb
10/06/1999  05:37p      <DIR>          .
10/06/1999  05:37p      <DIR>          ..
10/04/1999  11:19a      <DIR>          37a8f40e2
10/06/1999  05:37p      <DIR>          37f2c2272

但是,列举\\mybuilds\symsrv\msvcrt.pdb\37a8f40e2 目录表明refs.ptr 中有一些指针。

Directory of \\mybuilds\symsrv\msvcrt.pdb\37a8f40e2
10/05/1999  02:50p              54     file.ptr
10/05/1999  02:50p           2,039     refs.ptr

\\mybuilds\symsrv\msvcrt.pdb\37a8f40e2\refs.ptr的内容如下:

0000000001,ptr,\\mybuilds\symbols\x86\2137\symbols\dll\msvcrt.pdb
0000000002,ptr,\\mybuilds\symbols\x86\2137.chk\symbols\dll\msvcrt.pdb
0000000003,ptr,\\mybuilds\symbols\x86\2138\symbols\dll\msvcrt.pdb
0000000004,ptr,\\mybuilds\symbols\x86\2138.chk\symbols\dll\msvcrt.pdb
0000000005,ptr,\\mybuilds\symbols\x86\2139\symbols\dll\msvcrt.pdb
0000000006,ptr,\\mybuilds\symbols\x86\2139.chk\symbols\dll\msvcrt.pdb
0000000007,ptr,\\mybuilds\symbols\x86\2140\symbols\dll\msvcrt.pdb
0000000008,ptr,\\mybuilds\symbols\x86\2140.chk\symbols\dll\msvcrt.pdb
0000000009,ptr,\\mybuilds\symbols\x86\2136\symbols\dll\msvcrt.pdb
0000000010,ptr,\\mybuilds\symbols\x86\2136.chk\symbols\dll\msvcrt.pdb
0000000011,ptr,\\mybuilds\symbols\x86\2135\symbols\dll\msvcrt.pdb
0000000012,ptr,\\mybuilds\symbols\x86\2135.chk\symbols\dll\msvcrt.pdb
0000000013,ptr,\\mybuilds\symbols\x86\2134\symbols\dll\msvcrt.pdb
0000000014,ptr,\\mybuilds\symbols\x86\2134.chk\symbols\dll\msvcrt.pdb
0000000015,ptr,\\mybuilds\symbols\x86\2133\symbols\dll\msvcrt.pdb
0000000016,ptr,\\mybuilds\symbols\x86\2133.chk\symbols\dll\msvcrt.pdb
0000000017,ptr,\\mybuilds\symbols\x86\2132\symbols\dll\msvcrt.pdb
0000000018,ptr,\\mybuilds\symbols\x86\2132.chk\symbols\dll\msvcrt.pdb
0000000019,ptr,\\mybuilds\symbols\x86\2131\symbols\dll\msvcrt.pdb
0000000020,ptr,\\mybuilds\symbols\x86\2131.chk\symbols\dll\msvcrt.pdb
0000000021,ptr,\\mybuilds\symbols\x86\2130\symbols\dll\msvcrt.pdb
0000000022,ptr,\\mybuilds\symbols\x86\2130.chk\symbols\dll\msvcrt.pdb
0000000023,ptr,\\mybuilds\symbols\x86\2129\symbols\dll\msvcrt.pdb
0000000024,ptr,\\mybuilds\symbols\x86\2129.chk\symbols\dll\msvcrt.pdb
0000000025,ptr,\\mybuilds\symbols\x86\2128\symbols\dll\msvcrt.pdb
0000000026,ptr,\\mybuilds\symbols\x86\2128.chk\symbols\dll\msvcrt.pdb
0000000027,ptr,\\mybuilds\symbols\x86\2141\symbols\dll\msvcrt.pdb
0000000028,ptr,\\mybuilds\symbols\x86\2141.chk\symbols\dll\msvcrt.pdb
0000000029,ptr,\\mybuilds\symbols\x86\2142\symbols\dll\msvcrt.pdb
0000000030,ptr,\\mybuilds\symbols\x86\2142.chk\symbols\dll\msvcrt.pdb

这表明相同的msvcrt.pdb 在保存在\\mybuilds\symsrv 上的几个Windows 2000符号版本中都使用了。

这是同时包含了文件和附加指针的目录示例:

Directory of E:\symsrv\dbghelp.dbg\38039ff439000
10/12/1999  01:54p         141,232     dbghelp.dbg
10/13/1999  04:57p              49     file.ptr
10/13/1999  04:57p             306     refs.ptr

这种情况下, refs.ptr 有下面这样的内容:

0000000043,file,e:\binaries\symbols\retail\dll\dbghelp.dbg
0000000044,file,f:\binaries\symbols\retail\dll\dbghelp.dbg
0000000045,file,g:\binaries\symbols\retail\dll\dbghelp.dbg
0000000046,ptr,\\MyDir\bin\symbols\retail\dll\dbghelp.dbg
0000000047,ptr,\\foo2\bin\symbols\retail\dll\dbghelp.dbg

这样,事务43、44和45向服务器添加了同样的文件,事务46和47添加了指针。如果事务43、44和45被删除,dbghelp.dbg 文件也会从目录中删除掉。这时,目录具有如下内容:

Directory of e:\symsrv\dbghelp.dbg\38039ff439000
10/13/1999  05:01p                   49 file.ptr
10/13/1999  05:01p                 130 refs.ptr

新的file.ptr 包含"\\foo2\bin\symbols\retail\dll\dbghelp.dbg",而refs.ptr 包含:

0000000046,ptr,\\MyDir\bin\symbols\retail\dll\dbghelp.dbg
0000000047,ptr,\\foo2\bin\symbols\retail\dll\dbghelp.dbg

只要refs.ptr 的最后一项为指针,就会存在file.ptr文件,并且包含相关文件的路径。当refs.ptr 最后一项为文件时,目录中不会存在file.ptr。因此,任何对refs.ptr中最后一项的删除操作都可能使得file.ptr 被创建、删除或修改。

Build machine: CAPEBUILD