bp、bu、bm (ブレークポイントの設定)

  • [アーティクル]

bp、bu、および bm コマンドは、1 つ以上のソフトウェア ブレークポイントを設定します。 位置、条件、オプションを組み合わせて、さまざまな種類のソフトウェア ブレークポイントを設定できます。

ユーザー モード

[~Thread] bp[ID] [Options] [Address [Passes]] ["CommandString"] 
[~Thread] bu[ID] [Options] [Address [Passes]] ["CommandString"] 
[~Thread] bm [Options] SymbolPattern [Passes] ["CommandString"]

カーネル モード

bp[ID] [Options] [Address [Passes]] ["CommandString"] 
bu[ID] [Options] [Address [Passes]] ["CommandString"] 
bm [Options] SymbolPattern [Passes] ["CommandString"]

パラメーター

スレッド
ブレークポイントが適用されるスレッドを指定します。 構文については、「スレッドの構文」を参照してください。 スレッドは、ユーザー モードでのみ指定できます。 スレッドを指定しない場合、ブレークポイントはすべてのスレッドに適用されます。

ID
ブレークポイントを識別する 10 進数を指定します。

デバッガーはブレークポイントの作成時に ID を割り当てますが、br (ブレークポイント番号の再割り当て) コマンドを使用して変更できます。 ID を使用して、後のデバッガー コマンドでブレークポイントを参照できます。 ブレークポイントの ID を表示するには、bl (ブレークポイントの一覧) コマンドを使用します。

コマンドで ID を使用する場合、コマンド (bp または bu) と ID 番号の間にスペースを入力しないでください。

ID パラメーターは常に省略可能です。 ID を指定しない場合、デバッガーは最初に使用可能なブレークポイント番号を使用します。 カーネル モードでは、最大 32 個のブレークポイントを設定できます。 ユーザー モードでは、任意の数のブレークポイントを設定できます。 いずれの場合も、ID 番号の値に制限はありません。 ID を角かっこ ([ ]) で囲むと、ID に任意の式を含めることができます。 構文の詳細については、「数値式の構文」を参照してください。

Options ブレークポイント オプションを指定します。 指定されている場合を除き、任意の数の次のオプションを使用できます。

/1
"ワンショット" ブレークポイントを作成します。 このブレークポイントがトリガーされた後、ブレークポイント リストから削除されます。

/pEProcess
(カーネル モードのみ) このブレークポイントに関連付けられているプロセスを指定します。 EProcess は、PID ではなく EPROCESS 構造体の実際のアドレスになります。 ブレークポイントは、このプロセスのコンテキストで到達された場合のみトリガーされます。

/tEThread
(カーネル モードのみ) このブレークポイントに関連付けられているスレッドを指定します。 EThread は、スレッド ID ではなく、ETHREAD 構造体の実際のアドレスになります。 ブレークポイントは、このスレッドのコンテキストで到達された場合のみトリガーされます。 /pEProcess と /tEThread を使用する場合は、順序に関係なく入力できます。

/cMaxCallStackDepth
ブレークポイントがアクティブになるのは、呼び出しスタックの深さが MaxCallStackDepth を下回る場合のみです。 このオプションを /C と共に使用することはできません。

/CMinCallStackDepth
ブレークポイントがアクティブになるのは、呼び出しスタックの深さが MinCallStackDepth を上回る場合のみです。 このオプションを /c と共に使用することはできません。

/a
(bm のみ) データ空間内かコード空間内かに関わらず、指定したすべての位置にブレークポイントを設定します。 データのブレークポイントによりプログラムのエラーが発生する可能性があるため、このオプションは安全であることがわかっている位置でのみ使用してください。

/d
(bm のみ) ブレークポイントの位置をアドレスに変換します。 したがって、コードが移動された場合、ブレークポイントは SymbolPattern に従って設定されるのではなく、同じアドレスに残ります。 /d を使用すると、モジュールが読み込まれたかアンロードされたときにブレークポイントへの変更が再評価されなくなります。

/(
(bm のみ) SymbolString が定義するシンボル文字列にパラメーター リスト情報を含めます。

この機能を使用すると、名前は同じでもパラメーター リストが異なるオーバーロードされた関数にブレークポイントを設定できます。 たとえば、bm /( myFunc は、myFunc(int a) と myFunc(char a) の両方にブレークポイントを設定します。 「/(」がないと、myFunc に設定されたブレークポイントは、どの myFunc 関数を対象としているのかを示さないため、失敗します。

/w dx オブジェクト式 dx オブジェクト式によって返されるブール値に基づいて条件付きブレークポイントを設定します。 引数はデータ モデル (dx) 式で、true (条件に一致する - 中断) または false (条件に一致しない - 中断しない) に評価されます。

次の例は、localVariable の値に基づいて条件付きブレークポイントを設定します。

bp /w "localVariable == 4" mymodule!myfunction

この例は、JavaScript を使用してブレークポイントを設定する方法を示します。

bp /w "@$scriptContents.myFunc(localVariable)" @rip

デバッガー オブジェクトの詳細については、「dx (デバッガー オブジェクト モデル式の表示)」を参照してください。

条件付きブレークポイントの詳細については、「条件付きブレークポイントの設定」を参照してください。

アドレス
ブレークポイントが設定される命令の先頭のバイトを指定します。 Address を省略すると、現在の命令ポインターが使用されます。 構文の詳細については、「アドレスとアドレス範囲の構文」を参照してください。

Passes
ブレークポイントがアクティブになるまでの実行回数を指定します。 デバッガーは、指定した回数に達するまで、ブレークポイントの位置をスキップします。 Passes には、16 ビットまたは 32 ビットの値を指定できます。

既定では、ブレークポイントが初めてアクティブになるのは、アプリケーションが、ブレークポイントの位置を含むコードを初めて実行するときです。 この既定の状況は、Passes の値が 1 であるときです。 アプリケーションがコードを 1 回以上実行した後にのみブレークポイントを有効にするには、2 以上の値を入力します。 たとえば、値が 2 の場合、コードが 2 回目に実行されたときにブレークポイントがアクティブになります。

このパラメーターにより、コードが実行されるたびにデクリメントするカウンターが作成されます。 Passes カウンターの初期値と現在の値を確認するには、bl (ブレークポイントの一覧) を使用します。

Passes カウンターは、g (Go) コマンドに応答してアプリケーションがブレークポイントを越えて実行された場合にのみ、デクリメントします。 コードをステップ実行したりトレースしたりしている場合、カウンターはデクリメントしません。 Passes カウンターのカウントが 1 になると、ブレークポイントをクリアしてリセットすることでのみ、カウンターをリセットできます。

CommandString
ブレークポイントが、指定された回数、到達されるたびに実行されるコマンドのリストを指定します。 CommandString パラメーターは引用符で囲む必要があります。 複数のコマンドを区切るには、セミコロンを使用します。

CommandString のデバッガー コマンドにはパラメーターを含めることができます。 標準の C 制御文字 (\n や \" など) を使用できます。 第 2 レベルの引用符 (\") に含まれるセミコロンは、埋め込まれ引用符で囲まれた文字列の一部として解釈されます。

CommandString コマンドは、g (Go) コマンドに応答してアプリケーションが実行中にブレークポイントに到達した場合にのみ実行されます。 コードをステップ実行したり、このポイントを超えてトレースしたりしている場合、コマンドは実行されません。

ブレークポイント後にプログラム実行を再開するコマンド (g や t など) は、コマンド リストの実行を終了させます。

SymbolPattern
パターンを指定します。 デバッガーはこのパターンを既存のシンボルと照合し、パターンに一致したものすべてにブレークポイントを設定しようとします。 SymbolPattern には、さまざまなワイルドカード文字と指定子を含めることができます。 この構文の詳細については、「文字列ワイルドカードの構文」を参照してください。 これらの文字はシンボルと照合されるため、照合では大文字と小文字は区別されず、先頭の 1 つのアンダースコア (_) は任意の数の先頭のアンダースコアを表します。

環境

アイテム 説明
モード ユーザー モード、カーネル モード
ターゲット ライブ デバッグのみ
プラットフォーム すべて

追加情報

ブレークポイントの使用方法、他のブレークポイント コマンドとブレークポイントの制御方法、カーネル デバッガーからユーザー空間でのブレークポイントの設定方法の詳細と例については、「ブレークポイントの使用」を参照してください。 条件付きブレークポイントの詳細については、「条件付きブレークポイントの設定」を参照してください。

解説

bp、bu、および bm コマンドは新しいブレークポイントを設定しますが、それぞれ異なる特徴があります。

  • bp (ブレークポイントの設定) コマンドは、コマンドで指定したブレークポイントの位置のアドレスに新しいブレークポイントを設定します。 ブレークポイントの設定時にデバッガーがブレークポイントの位置のアドレス式を解決できない場合、bp ブレークポイントは自動的に bu ブレークポイントに変換されます。 bp コマンドを使用して、モジュールがアンロードされるとアクティブでなくなるブレークポイントを作成します。

  • bu (未解決のブレークポイントの設定) コマンドは、遅延ブレークポイントまたは未解決のブレークポイントを設定します。 bu ブレークポイントは、(アドレスではなく) コマンドで指定されたブレークポイントの位置へのシンボリック参照に設定され、その参照を含むモジュールが解決されるたびにアクティブになります。 これらのブレークポイントの詳細については、「未解決のブレークポイント (bu ブレークポイント)」を参照してください。

  • bm (シンボル ブレークポイントの設定) コマンドは、指定したパターンに一致するシンボルに新しいブレークポイントを設定します。 このコマンドは複数のブレークポイントを作成できます。 既定では、パターンに一致した後、bm ブレークポイントは bu ブレークポイントと同じになります。 つまり、bm ブレークポイントは、シンボリック参照に設定される遅延ブレークポイントです。 ただし、bm /d コマンドは 1 つ以上の bp ブレークポイントを作成します。 各ブレークポイントは、一致した位置のアドレスに設定され、モジュールの状態は追跡されません。

既存のブレークポイントがどのコマンドを使用して設定されたか不明な場合は、.bpcmds (ブレークポイント コマンドの表示) を使用して、すべてのブレークポイントとそれらを作成するのに使用されたコマンドを一覧表示できます。

bp ブレークポイントと bu ブレークポイントには、主に 3 つの違いがあります。

  • bp ブレークポイントの位置は常にアドレスに変換されます。 モジュールの変更により、bp ブレークポイントが設定されたコードが移動した場合でも、ブレークポイントは同じアドレスに残ります。 一方、bu ブレークポイントは、使用されたシンボリック値 (通常はシンボルとオフセット) に関連付けられたままであり、アドレスが変更されてもこのシンボリック位置を追跡します。

  • 読み込まれたモジュールで bp ブレークポイントのアドレスが見つかり、そのモジュールが後でアンロードされた場合、ブレークポイントはブレークポイント リストから削除されます。 一方、bu ブレークポイントは、アンロードとロードを繰り返しても残ります。

  • bp で設定したブレークポイントは WinDbg ワークスペースには保存されません。 bu で設定したブレークポイントはワークスペースに保存されます。

bm コマンドは、ブレークポイントのシンボル パターンでワイルドカード文字を使用する場合に便利です。 bmSymbolPattern 構文は、x SymbolPattern を使用してから各結果に bu を使用するのと同等です。 たとえば、「mem」という文字列で始まる Myprogram モジュールのすべてのシンボルにブレークポイントを設定するには、次のコマンドを使用します。

例

0:000> bm myprogram!mem* 
  4: 0040d070 MyProgram!memcpy
 5: 0040c560 MyProgram!memmove
  6: 00408960 MyProgram!memset

bm コマンドは (プロセッサ ブレークポイントではなく) ソフトウェア ブレークポイントを設定するため、データの破損を避けるためにブレークポイントを設定するときにデータの位置を自動的に除外します。

bp または bm /a コマンドを使用するときは、プログラム アドレスではなくデータ アドレスを指定できます。 ただし、データの位置が指定されていても、これらのコマンドはプロセッサ ブレークポイントではなく、ソフトウェア ブレークポイントを作成します。 ソフトウェア ブレークポイントが実行可能コードではなくプログラム データに配置されている場合、データの破損につながる可能性があります。 したがって、これらのコマンドをデータの位置で使用するのは、その位置に格納されたメモリがプログラム データとしてではなく、実行可能コードとして使用されることが確実である場合のみです。 それ以外の場合は、代わりに ba (アクセス時に中断) コマンドを使用する必要があります。 詳細については、「プロセッサ ブレークポイント (ba ブレークポイント)」を参照してください。

C++ パブリック クラスのメンバや制限文字を含む任意のテキスト文字列など、より複雑な構文を使用して、指定した位置にブレークポイントを設定する方法の詳細については、「ブレークポイント構文」を参照してください。

1 つの論理ソース行が複数の物理行にまたがる場合、ブレークポイントはステートメントまたは呼び出しの最後の物理行に設定されます。 デバッガーが要求された位置にブレークポイントを設定できない場合は、次に許可される位置にブレークポイントを設定します。

Thread を指定した場合、指定したスレッドにブレークポイントが設定されます。 たとえば、~*bp コマンドはすべてのスレッドにブレークポイントを設定し、~#bp は現在の例外の原因となったスレッドにブレークポイントを設定し、~123bp はスレッド 123 にブレークポイントを設定します。 ~bp コマンドと ~.bp コマンドはどちらも現在のスレッドにブレークポイントを設定します。

カーネル モードでマルチ プロセッサ システムをデバッグする場合、bp または ba (アクセス時に中断) を使用して設定したブレークポイントは、すべてのプロセッサに適用されます。 たとえば、現在のプロセッサが 3 で、「bp MemoryAddress」と入力して、MemoryAddress にブレークポイントを設定するとします。 そのアドレスで実行中のいずれのプロセッサ (プロセッサ 3 だけでない) によっても、ブレークポイント トラップが発生します。

bp、bu、および bm コマンドは、プロセッサ命令をブレーク命令に置き換えることで、ソフトウェア ブレークポイントを設定します。 読み取り専用コードまたは変更できないコードをデバッグするには、ba e コマンドを使用します。ここで、e は実行専用アクセスを表します。

次のコマンドは、MyTest 関数の開始から 12 バイト先の位置にブレークポイントを設定します。 このブレークポイントは、コードの最初の 6 回は無視されますが、コードの 7 回目で実行が停止します。

0:000> bp MyTest+0xb 7

次のコマンドは、RtlRaiseException にブレークポイントを設定し、eax レジスタの値を表示し、シンボル MyVar の値を表示して、処理を続けます。

kd> bp ntdll!RtlRaiseException "r eax; dt MyVar; g"

次の 2 つの bm コマンドは 3 つのブレークポイントを設定します。 コマンドを実行すると、表示される結果では、/d スイッチを使用して作成されたブレークポイントと、そのスイッチを使用せずに作成されたブレークポイントが区別されません。 .bpcmds (ブレークポイントの表示コマンド) を使用すると、これら 2 種類のブレークポイントを区別できます。 /d スイッチなしで bm を使用してブレークポイントを作成した場合、.bpcmds の表示ではそのブレークポイントのタイプが bu として示され、その後に評価されたシンボルが @!"" トークンで囲まれて続きます (そのシンボルが数値式やレジスタではなくリテラル シンボルであることが示されます)。 /d スイッチありで bm を使用してブレークポイントを作成した場合、.bpcmds の表示にはブレークポイントのタイプが bp として示されます。

0:000> bm myprog!openf* 
  0: 00421200 @!"myprog!openFile"
  1: 00427800 @!"myprog!openFilter"

0:000> bm /d myprog!closef* 
  2: 00421600 @!"myprog!closeFile"

0:000> .bpcmds
bu0 @!"myprog!openFile";
bu1 @!"myprog!openFilter";
bp2 0x00421600 ;