イベント指定は、stop コマンド、stopi コマンド、when コマンド、wheni コマンド、trace コマンド、tracei コマンドで、イベントタイプとパラメータを表すために使用します。書式は、イベントタイプを表すキーワードとオプションのパラメータで構成されます。イベント指定の意味は、一般に 3 つすべてのコマンドで同じです。例外は付録 D のコマンドの説明に記載されています。
ブレークポイントとは、アクションが発生する位置であり、その位置でプログラムは実行を停止します。このセクションでは、ブレークポイントイベントのイベント指定について説明します。
in イベント指定の構文:
in function
関数に入り、先頭行が実行される直前です。先行ログ後の最初の実行可能コードは、実際のブレークポイントの位置として使用されます。この行は、局所変数を初期化する行である場合があります。C++ のコンストラクタの場合、すべてのベースクラスのコンストラクタの実行後に実行されます。–instr 修飾子が使用された場合、それは関数の最初の命令が実行される直前です。function 仕様は、仮パラメータを含むことができるため、多重定義関数名、またはテンプレートインスタンスの指定に役立ちます。例:
stop in mumble(int, float, struct Node *)
at イベント指定の構文:
at [filename:]line-number
指定の行が実行される直前。filename を指定した場合は、指定したファイルの指定の行が実行される直前です。ファイル名には、ソースファイル名またはオブジェクトファイル名を指定します。引用符は不要ですが、ファイル名に特殊文字が含まれる場合は、必要な場合があります。指定の行がテンプレートコードに含まれる場合、ブレークポイントは、そのテンプレートのすべてのインスタンス上に置かれます。
at address-expression
指定のアドレスの指示が実行される直前。このイベントは stopi コマンドまたは –instr イベント修飾子でのみ使用できます。
infile イベント指定の構文:
infile filename
このイベントにより、ファイルで定義されたすべての関数にブレークポイントが設定されます。stop infile コマンドは、funcs –f filename コマンドと同じ関数のリストを繰り返します。
.h ファイル内のメソッド定義、テンプレートファイル、または .h ファイル内のプレーン C コード (regexp コマンドで使用される種類など) は、ファイルの関数定義に寄与する場合がありますが、これらの定義は除外されます。
指定されたファイル名が、オブジェクトファイルの名前の場合 (その場合、名前は .o で終了する)、ブレークポイントは、そのオブジェクトファイルで発生する関数すべてに設定されます。
stop infile list.h コマンドは、list.h ファイルで定義されたメソッドのすべてのインスタンスにブレークポイントを設定することはしません。そうするためには、inclass または inmethod のようなイベントを使用します。
fix コマンドは、関数をファイルから削除する、または追加する場合があります。stop infile コマンドは、ファイル内の関数のすべての古いバージョンと、将来追加されるすべての関数にブレークポイントを設定します。
ネストされた関数や Fortran ファイルのサブルーチンには、ブレークポイントは設定されません。
clear コマンドを使用して、infile イベントによって作成された組にある単一のブレークポイントを無効にできます。
infunction イベント指定の構文:
infunction function
この指定は、function という名前のすべての多重定義関数またはそれのすべてのテンプレートインスタンスに対する in function と同等です。
inmember イベント指定の構文:
inmember function
この指定は inmethod イベント指定のエイリアスです。
inmethod イベント指定の構文は次のとおりです。
inmethod function
この指定は、in function、またはすべてのクラスの function という名前のメンバーメソッドと同等です。
inclass イベント指定の構文:
inclass classname [-recurse | -norecurse]
この指定は、classname のメンバーであるが、classname のベースのメンバーではない、すべてのメンバー関数に対する in function と同等です。デフォルトは –norecurse です。–recurse が指定された場合、基底クラスが含まれます。
inobject イベント指定の構文:
inobject object-expression [-recurse | -norecurse]
object-expression で示されるアドレスにある特定のオブジェクトに対して呼び出されたメンバー関数が呼び出されました。stop inobject ox はほぼ次と同じですが、inclass とは異なり、ox の動的タイプのベースが含まれます。–recurse はデフォルトです。–norecurse が指定された場合、基底クラスが含まれます。
stop inclass dynamic_type(ox) -if this==ox
このセクションでは、メモリーアドレスの内容へのアクセスや変更に関するイベントのイベント指定について説明します。
access イベント指定の構文:
access mode address-expression [,byte-size-expression]
address-expression で指定されたメモリーがアクセスされたとき。
mode はメモリーのアクセス方法を指定します。有効な値は次のいずれかまたはすべての文字です。
指定したアドレスのメモリーが読み取られたことを示します。
メモリーへの書き込みが実行されたことを示します。
メモリーが実行されたことを示します。
さらに mode には、次のいずれかの文字も指定することができます。
アクセス後にプロセスを停止します (デフォルト)。
アクセス前にプロセスを停止します。
いずれの場合も、プログラムカウンタは副作用アクションの前後で違反している命令をポイントします。「前」と「後」は副作用を指しています。
address-expression は、その評価によりアドレスを生成できる任意の式です。記号式を指定すると、監視対象領域のサイズが自動的に推定されます。byte-size-expression を指定して、それをオーバーライドすることができます。さらに、シンボルを使用しない、型を持たないアドレス式を使用することもできますが、その場合はサイズが必須です。例:
stop access w 0x5678, sizeof(Complex)
access コマンドには、2 つの一致する領域が重複しない、という制限があります。
change イベント指定の構文:
change variable
variable の値は変更されました。change イベントは、次とほぼ同等です。
when step { if [ $last_value !=$[variable]]
then
stop
else
last_value=$[variable]
fi
}
このイベントはシングルステップを使用して実装されます。パフォーマンスの向上のため、access イベントを使用してください。
最初に variable がチェックされると、変更が検出されない場合でも 1 つのイベントが発生します。この最初のイベントによって variable の最初の値にアクセスできるようになります。あとから検出された variable の値への変更によって別のイベントが発生します。
cond イベント指定の構文:
cond condition-expression
condition-expression で示された条件は true に評価されます。condition-expression には任意の式を使用できますが、整数型に評価されなければなりません。cond イベントは次の stop コマンドとほぼ同等です。
stop step -if conditional-expression
このセクションでは、システムイベントのイベント指定について説明します。
dlopen() および dlopen() イベント指定の構文:
dlopen [ lib-path ]
dlclose [ lib-path ]
システムイベントは、dlopen() の呼び出しまたは dlclose() の呼び出しが成功したあとに発生します。dlopen() の呼び出しまたは dlclose() の呼び出しにより、複数のライブラリがロードされることがあります。これらのライブラリのリストは、事前定義済み変数 $dllist でいつでも入手できます。$dllist の中の最初のシェルの単語は + (プラス記号) または - (マイナス記号) で、ライブラリのリストに追加されているか、削除されているかを示します。
lib-path は、該当する共有ライブラリの名前です。これを指定した場合、そのライブラリが読み込まれたり、読み込みが取り消されたりした場合にだけイベントが起動します。その場合、$dlobj にライブラリの名前が格納されます。また、$dllist も利用できます。
lib-path が / で始まる場合は、パス名全体が比較されます。それ以外の場合は、パス名のベースだけが比較されます。
lib-path を指定しない場合、イベントは任意の dl 動作があるときに必ず起動します。$dlobj は空になりますが、$dllist は有効です。
fault イベント指定の構文:
fault fault
fault イベントは、指定された障害が検出されたときに発生します。障害は、アーキテクチャー依存です。dbx に認識される一連の障害を次のリストに示し、proc(4) マニュアルページで定義しています。
不正命令
特権付き命令
ブレークポイントトラップ
トレーストラップ (ステップ実行)
メモリーアクセス (境界合わせなど)
メモリー境界 (無効なアドレス)
整数オーバーフロー
整数ゼロ除算
浮動小数点例外
修復不可能なスタックフォルト
回復可能なページフォルト
ウォッチポイントトラップ
CPU パフォーマンスカウンタオーバーフロー
これらの障害は、/usr/include/sys/fault.h から抜粋されています。fault には上に挙げたいずれかを大文字または小文字、FLT- 接頭辞を付けるか付けないかで指定するか、または実際の数値コードを指定できます。
lwp_exit イベント指定の構文:
lwp_exit
lwp_exit イベントは、lwp が終了したときに発生します。$lwp には、イベントハンドラの継続時間中に終了した LWP (軽量プロセス) の ID が含まれます。
sig イベント指定の構文:
sig signal
sig signal イベントは、デバッグ中のプログラムにシグナルが初めて送られたときに、発生します。signal は、10 進数、または大文字、小文字のシグナル名のいずれかです。接頭辞はオプションです。このイベントは、catch コマンドおよび ignore コマンドからは完全に独立しています。ただし、catch コマンドは次のように実装することができます。
function simple_catch {
when sig $1 {
stop;
echo Stopped due to $sigstr $sig
whereami
}
}
または、サブコードでシグナルを指定することができます。sig イベント指定のこのオプションの構文:
sig signal sub-code
指定の sub-code を持つ指定の信号が child に初めて送られたとき、sig signalsub-code イベントが発生します。シグナルと同様に、sub-code は 10 進数として、大文字または小文字で指定することができます。接頭辞はオプションです。
sysin イベント指定の構文:
sysin code|name
指定されたシステムコールが起動された直後で、プロセスがカーネルモードに入ったとき。
dbx でサポートされるシステムコールの概念は、/usr/include/sys/syscall.h に列挙されるように、カーネルへのトラップによって提供されるものです。
この概念は、ABI のシステムコールの概念とは違います。ABI のシステムコールの一部は部分的にユーザーモードで実装され、非 ABI のカーネルトラップを使用します。ただし、一般的なシステムコールのほとんど (シグナル関係は除く) は syscall.h と ABI で共通です。
/usr/include/sys/syscall.h 内のカーネルシステムコールトラップのリストは、Oracle Solaris OS のプライベートインタフェースの一部であり、リリースによって異なります。dbx が受け付けるトラップ名 (コード) およびトラップ番号のリストは、dbx がサポートするバージョンの Oracle Solaris OS によってサポートされているすべてを含みます。dbx によってサポートされている名前が特定のリリースの Solaris OS のそれらと正確に一致することはありえないため、syscall.h 内の一部の名前は使用できない場合があります。すべてのトラップ番号 (コード) は dbx で受け入れられ、予測どおりに動作しますが、既知のシステムコールトラップに対応しない場合は、警告が発行されます。
sysout イベント指定の構文:
sysout code|name
指定されたシステムコールが終了し、プロセスがユーザーモードに戻る直前。
引数がないときは、すべてのシステムコールがトレースされます。ここで、modify イベントや RTC (実行時検査) などの特定の dbx は、子プロセスにその目的でシステムコールを引き起こすことがあることに注意してください。トレースした場合にそのシステムコールの内容が示されることがあります。
このセクションでは、実行進行状況に関するイベントのイベント指定について説明します。
exit イベント指定の構文:
exit exitcode
next イベントは、ステップインしない関数を除いて、step イベントと似ています。
returns イベントは、現在アクセスされている関数の戻りポイントにあるブレークポイントです。表示されている関数を使用するのは、いくつかの up を行なったあとに returns イベント指定を使用できるようにするためです。通常の returns イベントは常に一時イベント (–temp) で、動作中のプロセスが存在する場合にだけ作成できます。
returns イベント指定の構文:
returns function
returns function イベントは、特定の関数がその呼び出し場所に戻るたびに実行されます。これは一時イベントではありません。戻り値は示されませんが、SPARC プラットフォームでは $o0、Intel プラットフォームでは $eax を使用して、必須戻り値を調べることができます。
SPARC ベースのシステム – $o0
x86 ベースのシステム – $eax
x64 ベースのシステム – $rax、$rdx
このイベントは、次のコードとほとんど同じ働きをします。
when in func { stop returns; }
step イベントは、ソース行の最初の命令が実行されたときに発生します。たとえば、次のコマンドで簡単なトレースを取得できます。
when step { echo $lineno: $line; }; cont
step イベントを有効にするということは、次に cont コマンドが使用されるときに自動的にステップ実行できるように dbx に命令することと同じです。
throw イベントの構文:
throw [type | –unhandled | –unexpected]
throw イベントは、アプリケーションによって、処理されないか、予期しない例外がスローされるたびに発生します。
throw イベントで例外のタイプが指定されている場合、そのタイプの例外だけが throw イベントを発生させます。
–unhandled オプションが指定されている場合、例外を示す特殊な例外タイプがスローされますが、それに対してハンドラが存在しません。
–unexpected オプションが指定されている場合、例外を示す特殊な例外タイプはそれをスローした関数の例外指定を満たしていません。
次のセクションでは、追跡されたスレッドのイベント指定について説明します。
omp_barrier イベント指定は、追跡されたスレッドがバリアに入るか、出るタイミングです。type (explicit または implicit になる) と、state (enter、exit、または all_entered になる) を指定できます。デフォルトは explicit all_entered です。
omp_taskwait イベント指定は、追跡されたスレッドが taskwait に入るか、出るタイミングです。state を指定でき、これは enter または exit になります。デフォルトは exit です。
omp_ordered イベント指定は、追跡されたスレッドが Ordered 領域に入るか、出るタイミングです。state を指定でき、これは begin、enter、または exit になります。デフォルトは enter です。
omp_critical イベント指定は、追跡されたスレッドがクリティカル領域に入るか、出るタイミングです。
omp_atomic イベント指定は、追跡されたスレッドが不可分領域に入るか、出るタイミングです。state を指定でき、これは begin または exit になります。デフォルトは begin です。
omp_flush イベント指定は、追跡されたスレッドが明示的なフラッシュ領域に入るか、出るタイミングです。
omp_task イベント指定は、追跡されたスレッドがタスク領域に入るか、出るタイミングです。state を指定でき、これは create、start、または finish になります。デフォルトは start です。
omp_master イベント指定は、追跡されたスレッドがマスター領域に入るか、出るタイミングです。
omp_single イベント指定は、追跡されたスレッドが Single 領域に入るタイミングです。
このセクションでは、その他のタイプのイベントのイベント指定について説明します。
attach イベントは、dbx がプロセスに正常に接続したタイミングです。
detach イベントは dbx がデバッグ中のプログラムから正常に切り離されたタイミングです。
lastrites イベントは、デバッグ中のプロセスが終了する直前のタイミングです。これは次の理由によって発生する可能性があります。
_exit(2) システムコールが、明示的な呼び出し経由か、または main() の戻り時に呼び出された。
終了シグナルが送信されようとするとき。
dbx コマンド kill によってプロセスが強制終了されつつあるとき。
プロセスの最終段階は、必ずではありませんが通常はこのイベントが発生したときに利用可能になり、プロセスの状態を確認することができます。このイベントのあとにプログラムの実行を再開すると、プロセスは終了します。
proc_gone イベントは dbx がデバッグ対象のプロセスに関連付けられなくなったときに発生します。事前定義済み変数 $reason は、signal、exit、kill、または detach になります。
prog_new イベントは、follow exec の結果として新しいプログラムがロードされたときに発生します。
stop イベントは、特に stop ハンドラへの応答として、ユーザーがプロンプトを受け取るなど、プロセスが停止するたびに発生します。次に例を示します。
display x
when stop {print x;}
sync イベントは、デバッグ中のプロセスが exec() で実行された直後に発生します。a.out で指定されたメモリーはすべて有効で存在しますが、あらかじめ読み込まれるべき共有ライブラリはまだ読み込まれていません。たとえば printf は dbx に認識されていますが、まだメモリーにはマップされていません。
stop コマンドにこのイベントを指定しても期待した結果は得られません。when コマンドに指定してください。
syncrtld イベントは、sync、またはデバッグ中のプロセスがまだ共有ライブラリを処理していない場合は attach のあとに発生します。これは、動的リンカーの起動コードが実行され、プリロード済みのすべての共有ライブラリのシンボルテーブルがロードされたあと、ただし、.init セクション内のコードが実行される前に実行します。
stop コマンドにこのイベントを指定しても期待した結果は得られません。when コマンドに指定してください。
thr_create イベントは、スレッドまたは指定したスレッド ID を持つスレッドが作成されたときに発生します。たとえば、次の stop コマンドでスレッド ID t@1 はスレッド作成を示しますが、スレッド ID t@5 は作成済みスレッドを示しています。
stop thr_create t@5 -thread t@1
thr_exit イベントは、スレッドが終了したときに発生します。指定したスレッドの終了を取り込むには、次のように stop コマンドで -thread オプションを使用します。
stop thr_exit -thread t@5
timer イベントの構文:
timer seconds
timer イベントは、デバッグ中のプログラムが seconds 秒間実行されたときに発生します。このイベントで使用されるタイマーは、collector コマンドで共有されます。解像度はミリ秒であるため、秒の浮動小数点値 (0.001 など) が使用可能です。