プログラミングユーティリティ

`prex` コマンドの構成要素

プローブポイントをソースコードに挿入するときに、さまざまな属性や (必要に応じて) 値を各プローブポイントに割り当てることができます。たとえば、任意の名前を "name" 属性の値に割り当てることができます。

定義済みの属性とその値の意味を表 1-3 に示します。prex コマンドを使用して、プローブポイントの属性または値に一致する複数のプローブポイントをグループとして選択できます。また、選択したプローブポイントのトレースやデバッグを行うこともできます。

prex コマンドとそのアクションは、表 1-5 を参照してください。

例 1-1 では、TNF_PROBE マクロによって work_start という名前のプローブポイントが定義されています。このプローブポイントには、state と message という 2 つの引数があります。work_start という名前のプローブが検出されるたびに、変数 state と message のタイムスタンプと値がトレースファイルに記録されます。

例 1-1 `prex` の属性と値

 #include <tnf/probe.h>
 
 int
 work(int state, char *message)
 {
    TNF_PROBE_2(work_start, "work_module work"
               "sunw%debug in function work",
               tnf_long, int_input, state,
               tnf_string, string_input, message);
   ...
   ...
 }

TNF_PROBE マクロとこのコード例についての詳細は、「TNF_PROBE マクロの使い方」を参照してください。

属性

属性は、コード内のプローブポイントを識別するための特性です。定義済みの属性を表 1-3 に示します。ユーザーは、TNF_PROBE を使用して別の属性を追加定義することができます。「TNF_PROBE マクロの使い方」を参照してください。

表 1-3 定義済みの属性


属性	特性	値
`enable`	プローブポイントは、そのプローブポイントが有効な場合にだけ、設定されているアクションを実行します。たとえば、トレースを行うように設定しても、プローブポイントが有効になっている場合にしかトレースは行われません。	OFF (デフォルト)
`file`	プローブポイントが含まれているファイルの名前。	`work.c`
`funcs`	このプローブに接続されたプローブ関数のリストを表示します。現在使用できるのはデバッグ関数だけです。	<値なし> (デフォルト)
`keys`	プローブポイントが属するグループ。プローブポイントのいずれかのキーが有効になると、そのプローブポイントは有効になります。	work_module work
`line`	プローブポイントが現われるコード内の行番号	10
`name`	プローブポイントの名前	work_start
`object`	プローブポイントが含まれている共有オブジェクトまたは実行可能プログラムの名前。特定のモジュール中のプローブをすべて選択する場合に便利な属性です。	work
`slots`	プローブポイントの引数 (arg_name_n については、「`TNF_PROBE_1` 〜 `TNF_PROBE_5`」を参照) の名前。	int_input string_input
`trace`	プローブポイントのトレースがオンの場合、プログラムのプローブポイントを実行するたびに、データが 1 行ずつトレースファイルに書き込まれます。	ON (デフォルト)

プローブの照合構文

プローブの属性と値に基づいてプローブを選択します。 selector_list に選択条件を指定します。それぞれの属性または値は、以下のいずれかで表現できます。

識別子−英字、数字、_ ¥ . % (下線、バックスラッシュ、ピリオド、パーセント記号) を使用した文字列。識別子の最初の文字を数字にすることはできません。
引用符付き文字列−単一引用符で囲んだ文字列。この文字列は文字どおりに解釈される直定数とみなされます。照合する文字列が予約語の場合に便利な表現です。予約語の一覧については、表 1-4 を参照してください。
正規表現−スラッシュ (/) で囲んだ文字列。ed(1) の規則に従って照合用に拡張されています。正規表現においてパス名などを表すためにスラッシュを使用する場合は、/¥/tmp¥/filename のように、バックスラッシュでそのスラッシュをエスケープしてください。

selector_list は、1 つ以上の selector= という形式の選択条件で構成されています。最初の selector= が指定されていない場合は、keys= がデフォルトになります。たとえば、enable コマンドは以下の書式で指定します。

enable selector_list

たとえば、以下のように指定します。

enable name=/first/ file='sampleZ.c'

このコマンドは、値 first が含まれている name 属性 (正規表現による一致) をもつプローブポイント、または値が sampleZ.c である file 属性を持つプローブポイントをすべて有効にします。なお、トレースは、論理積ではなく論理和であることに注意してください。

選択条件 selector_list の簡略名として、$set_name のように変数を設定することができます。以下の例では、myprobes がその set_name に当たります。

create $myprobes name=/first/ file='sampleZ.c'
enable $myprobes

これは、前述の例と同じ処理を行います。set_name は、識別子の命名規則に従っています。デフォルト設定の $all は、プログラムのプローブをすべて選択します。

予約語

予約語を表 1-4 に示します。これらの予約語を使用して属性または値を選択する場合は、その予約語を単一引用符で囲んでください。

表 1-4 予約語


`add`	`alloc`	`buffer`
`clear`	`connect`	`continue`
`create`	`dealloc`	`delete`
`disable`	`enable`	`fcns`
`filter`	`help`	`history`
`kill`	`ktrace`	`list`
`off`	`on`	`pfilter`
`probes`	`quit`	`resume`
`sets`	`source`	`suspend`
`trace`	`untrace`	`values`

たとえば、以下のコマンドは、trace 属性の値が ON のプローブをすべて有効にします。trace と on はどちらも予約語なので、単一引用符で囲む必要があります。

enable 'trace'='on'

表 1-5 prex のコマンド


コマンド	アクション
`clear $set_name` `clear` `selector_list`	接続されているプローブ関数を切り離します。
`clear $set_name` `clear` `selector_list`	接続されているプローブ関数を切り離します。
`connect &debug $set_name` `connect &debug` `selector_list`	デバック関数をプローブポイントに接続します。このコマンドを実行しても、プローブポイントは有効になりません。デバッグ関数は、トレースファイルにではなく `stderr` に出力を送ります。

`continue`	`prex` を接続したまま、プログラムの実行を再開します。
`create` `$set_name` `selector_list`	`selector_list` と一致するプローブポイントのグループを作成します。同時に、`selector_list` のエイリアス $`set_name` を作成します。
`enable $set_name` `enable` `selector_list` `disable $set_name` `disable` `selector_list`	プローブポイントに設定されているアクションをそのプローブポイントに実行させるかどうかを制御します。デフォルトでは、プローブポイントは無効になっています。つまり、`prex` はトレースをオンにしません。プローブポイントのトレースを停止する最も効率的な方法 (プローブポイントにおける実行時間の面から考えた場合) は、`disable` コマンドを使用する方法です。 `enable` と `disable` コマンドは、主スイッチで、トレースを実行するかどうかを決定する最も優先度が高い要素です。プローブポイントが無効の場合は、そのプローブポイントが `debug()` 関数に接続されていて `trace` 属性がオンであっても、`stderr` やトレースファイルに情報は送られません。



`help`	使用可能な `prex` コマンドをすべて表示します。
`list` `attribute`s `probes` `selector_list` `list` `attribute`s `probes$` `set_name`	指定されたプローブポイントが有効/無効のどちらであるか、そのプローブポイントのトレースがオン/オフのどちらであるか、および接続されているプローブ関数を表示します。「属性」で説明したように、属性が選択条件になります。たとえば、以下のコマンドは、一致したプローブポイントの `name` 属性と `file` 属性の値だけを表示します。 `list name file probes $all` 以下のコマンドは、デフォルトの属性とその値 (`name`、`enable`、`trace`、`file`、`line`、`funcs`) をすべて表示します。 `list probes $all`

`list fcns`	定義済みの関数 (現在は、`&debug` だけが定義されています) を表示します。
`list history`	制御コマンドの履歴を表示します。`dlopen()` によって新しい共有オブジェクトがプログラムに取り込まれるたびに `connect`、`clear`、`trace`、`untrace`、`enable`、`disable` で使用したコマンドの履歴が記録されます。「`dlopen()`、`dlclose()`、履歴」を参照してください。
`list sets`	定義されたセットを表示します。
`list values` `attributes`	`attributes` に指定された属性に関連付けられた固有値を表示します。たとえば `list values keys` を実行すると、プログラム内の固有キーがすべて表示されます。
`source` `filename`	`prex` コマンドのファイルを読み込みます。`ファイル名`は引用符で囲んでください。
`trace $set_name` >`trace` `selector_list` `untrace $set_name` `untrace` `selector_list`	プローブポイントのトレース動作を制御します。`trace` と `untrace` を使用して、プローブポイントを実行したときにそのプローブポイントにトレース記録を生成させるかどうかを切り替えます。`trace` と `untrace` のどちらを実行しても、プローブポイントは有効になりません。デフォルトでは、トレースはオンになります。 `untrace` コマンドは、デバッグ出力だけを得たいときに利用できます。このコマンドを使用する際には、トレースをオフ、デバッグをオンにして、プローブを有効にする必要があります。 `debug` は `stderr` に書き込みを行いますが、`trace` は `mmap` された (メモリーが割り当てられた) ファイルに書き込みを行います。そのため、トレースの方がデバッグ関数よりもプログラムに与える負荷が少なくなります。



`quit`	`prex` を終了します。`prex` を使用してプログラムがロードされている場合は、そのプログラムを強制終了します。`prex` にプログラムが接続されている場合は、そのプログラムが再実行されます。
`quit kill`	`prex` を終了して、プログラムを強制終了します。
`quit resume`	`prex` を終了して、プログラムを再実行します。
`quit suspend`	プログラムを中断したまま、`prex` を終了します。

prex コマンドの構成要素

例 1-1 prex の属性と値

属性

プローブの照合構文

予約語

`prex` コマンドの構成要素

例 1-1 `prex` の属性と値