シンボル パス

  • [アーティクル]

DbgHelp ライブラリは、シンボル検索パスを使用してデバッグ シンボル (.pdb ファイルと .dbg ファイル) を検索します。 検索パスは、セミコロンで区切られた 1 つ以上のパス要素で構成できます。

検索パスの指定

シンボル ハンドラーがディスク ディレクトリでシンボル ファイルを検索する場所を指定するには、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 ファイルへの絶対パスが埋め込まれます。 _NT_SYMBOL_PATH または _NT_ALT_SYMBOL_PATH 環境変数を設定すると、シンボル ハンドラーは次の順序でシンボル ファイルを検索します。

パス要素の種類

パス要素には 3 種類あります。

Standard Path 要素

標準パス要素は、path 要素で指定されたディレクトリのルートを調べることで検索されます。 シンボル ハンドラーは、シンボルが検索されているモジュールのファイル拡張子と一致する「symbols」のサブディレクトリも検索します。 これは通常、「dll」、「exe」、または「sys」です。 最後に、拡張子と同じ名前のディレクトリを持つ「symbols」というサブディレクトリを検索します。 たとえば、シンボル パス要素が「c:\mySymbols」で、シンボルが検索されるファイルが「boo.dll」の場合、次のディレクトリが検索されます。

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

シンボル ハンドラーは、このロジックを使用して、条件を満たしていないパス要素をシンボル サーバーまたは キャッシュとして検索します (後述)。

Symbol Server Path 要素

シンボル サーバー パス要素は、対象のモジュールと完全に一致するシンボルを見つけ出すことができる特別なテクノロジを使用します。 詳細については、「SymSrv の使用」を参照してください。

シンボル ハンドラーは、パス要素がテキスト「srv*」で始まる場合、そのパス要素をシンボル サーバーとして扱います。

Note

「srv*」テキストが指定されていないが、実際のパス要素がシンボル サーバー ストアである場合、シンボル ハンドラーは「srv*」が指定されているかのように動作します。 シンボル ハンドラーは、指定されたパスのルート ディレクトリで「pingme.txt」というファイルの存在を検索することによってこの判断を行います。

 

Cache Path 要素

キャッシュ パス要素は、シンボル サーバー パス要素のバリエーションです。

このディレクトリは、他のシンボル サーバーと同様に検索されます。 ただし、シンボルがここで見つからず、シンボル パスのチェーンのさらに下流のパス要素で見つかった場合、シンボルはコピーされ、この要素で指定されたシンボル サーバーに保存されます。

シンボル ハンドラーは、パス要素がテキスト「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

出力の最初の 3 行は、. の最初のパス要素を処理するシンボル ハンドラーを示しています。 これは標準のパス要素です。

4 行目は、シンボル サーバーを使用して、キャッシュ パス要素である cache*c:\myCache の 2 番目のパス要素内のファイルを検索するシンボル ハンドラーを示しています。

5 行目は、ファイルが srv*\\symbols\symbols の 3 番目のパス要素 (シンボル サーバー パス要素) で見つかったことを示しています。

6 行目は、ファイルがキャッシュにコピーされることを示しています。

ファイルがキャッシュから開かれる最後の 2 行。