SymStore の使用

SymStore (symstore.exe) は、シンボル ストアを作成するためのツールです。 これは、Debugging Tools for Windows パッケージに含まれています。

SymStore は、デバッガがイメージのタイムスタンプとサイズ (.dbg または実行可能ファイルの場合)、または署名と経過時間 (.pdb ファイルの場合) に基づいてシンボルを検索できる形式でシンボルを保存します。 従来のシンボル ストレージ形式に対するシンボル ストアの利点は、対応するシンボルがどの製品に含まれているかを事前に知らなくても、すべてのシンボルを同じサーバー上に保存または参照でき、デバッガーによって取得できることです。

.pdb シンボル ファイルの複数のバージョン (パブリック バージョンとプライベート バージョンなど) は、それぞれに同じ署名と経過時間が含まれるため、同じサーバーに保存できないことに注意してください。

SymStore のトランザクション

SymStore の呼び出しはすべてトランザクションとして記録されます。 トランザクションには、追加と削除の 2 種類があります。

シンボル ストアが作成されると、「000admin」という名前のディレクトリがサーバーのルートの下に作成されます。 000admin ディレクトリには、トランザクションごとに 1 つのファイルと、ログ ファイル Server.txt および History.txt が含まれています。 Server.txt ファイルには、現在サーバー上にあるすべてのトランザクションの一覧が含まれています。 History.txt ファイルには、すべてのトランザクションの時系列履歴が含まれています。

SymStore がシンボル ファイルを格納または削除するたびに、新しいトランザクション番号が作成されます。 次に、このトランザクション番号を名前とするファイルが 000admin に作成されます。 このファイルには、このトランザクション中にシンボル ストアに追加されたすべてのファイルまたはポインターの一覧が含まれています。 トランザクションが削除されると、SymStore はトランザクション ファイルを読み取り、削除する必要があるファイルとポインターを決定します。

add オプションと del オプションは、追加または削除トランザクションを実行するかどうかを指定します。 /p オプションを追加操作と共に含めると、ポインターの追加を指定します。/p オプションを省略すると、実際のシンボル ファイルが追加されます。

シンボル ストアは、2 つの異なるステージで作成することもできます。 最初のステージでは、/x オプションと共に SymStore を使用してインデックス ファイルを作成します。 2 番目のステージでは、/y オプションを指定して SymStore を使用して、インデックス ファイル内の情報からファイルまたはポインターの実際のストアを作成します。

これは、さまざまな理由で便利な手法です。 たとえば、これにより、シンボル ストアが何らかの理由で失われた場合でも、インデックス ファイルがまだ存在する限り、シンボル ストアを簡単に再作成できます。 あるいは、シンボル ファイルを含むコンピューターとシンボル ストアが作成されるコンピューターへのネットワーク接続が遅い可能性があります。 この場合、シンボル ファイルと同じマシンにインデックス ファイルを作成し、そのインデックス ファイルを 2 台目のマシンに転送して、2 台目のマシンにストアを作成できます。

すべての SymStore パラメーターの完全な一覧については、「SymStore コマンド ライン オプション」を参照してください。

トランザクションの例

次に、SymStore が Windows Server 2003 のビルド 3790 のシンボル ポインターを \\sampledir\symsrv に追加する 2 つの例を示します。

symstore add /r /p /f \\BuildServer\BuildShare\3790free\symbols\*.*
   /s \\sampledir\symsrv /t "Windows Server 2003" /v "Build 3790 x86 free"
   /c "Sample add"
symstore add /r /p /f \\BuildServer\BuildShare\3790Chk\symbols\*.* 
   /s \\sampledir\symsrv /t "Windows Server 2003" /v "Build 3790 x86 checked"
   /c "Sample add"

次の例では、SymStore は、\\largeapp\appserver\bins にあるアプリケーション プロジェクトの実際のシンボル ファイルを \\testdir\symsrv に追加します。

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

インデックス ファイルの使用方法の例を次に示します。 最初に、SymStore は \\largeapp\appserver\bins\ のシンボル ファイルのコレクションに基づいてインデックス ファイルを作成します。 この場合、インデックス ファイルは 3 番目のコンピューター \\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 \\sampledir\symsrv /p 
   /t "Large Application" /v "Build 432" /c "Sample Add from Index"

最後に、前のトランザクションによって追加されたファイルを削除する SymStore の例を次に示します。 トランザクション ID (この場合は 0000000096) を決定する方法については、次のセクションを参照してください。

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

圧縮ファイル

SymStore は、2 つの異なる方法で圧縮ファイルと共に使用できます。

1. シンボル ファイルへのポインターを格納するには、/p オプションを付けて SymStore を使用します。 SymStore が完了したら、ポインターが参照するファイルを圧縮します。
2. インデックス ファイルを作成するには、/x オプションを付けて SymStore を使用します。 SymStore が完了したら、インデックス ファイルに一覧表示されているファイルを圧縮します。 次に、/y オプション (必要に応じて /p オプション) で SymStore を使用して、シンボル ストア内のファイルまたはファイルへのポインターを格納します。 (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 XP,x86 fre 1.156c-RTM-2,Added from \\mybuilds\symbols,

これはコンマ区切りの行です。 フィールドは次のように定義されています。

次に、トランザクション ファイル 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

削除トランザクションのフィールドは次のように定義されます。

シンボル ストレージの形式

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 のようになります。

ルックアップ ディレクトリ内に次の 3 つのファイルが存在する場合があります。

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」で追加されたことを示しています。

一部のシンボル ファイルは、さまざまな製品やビルド、または特定の製品を通じて一定の状態を維持します。 この例の 1 つは、msvcrt.pdb ファイルです。 \\mybuilds\symsrv\msvcrt.pdb のディレクトリを実行すると、msvcrt.pdb の 2 つのバージョンのみがシンボル サーバーに追加されていることがわかります。

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

これは、\\mybuilds\symsrv に保存されているシンボルの複数のビルドに同じ msvcrt.pdb が使用されたことを示しています。

ファイルとポインターの追加の組み合わせが含まれるディレクトリの例を次に示します。

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,\\sampledir\bin\symbols\retail\dll\dbghelp.dbg
0000000047,ptr,\\sampledir2\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 には「\\sampledir2\bin\symbols\retail\dll\dbghelp.dbg」が含まれ、refs.ptr には次のものが含まれます

0000000046,ptr,\\sampledir\bin\symbols\retail\dll\dbghelp.dbg
0000000047,ptr,\\sampledir2\bin\symbols\retail\dll\dbghelp.dbg

refs.ptr の最後のエントリがポインタである場合は常に、ファイル file.ptr が存在し、関連するファイルへのパスが含まれます。 refs.ptr の最後のエントリがファイルである場合、このディレクトリには file.ptr は存在しません。 したがって、refs.ptr の最後のエントリを削除する削除操作を行うと、file.ptr が作成、削除、または変更される可能性があります。