プローブポイントをソースコードに挿入するときに、さまざまな属性や (必要に応じて) 値を各プローブポイントに割り当てることができます。たとえば、任意の名前を "name" 属性の値に割り当てることができます。
定義済みの属性とその値の意味を表 1-3 に示します。prex コマンドを使用して、プローブポイントの属性または値に一致する複数のプローブポイントをグループとして選択できます。また、選択したプローブポイントのトレースやデバッグを行うこともできます。
prex コマンドとそのアクションは、表 1-5 を参照してください。
例 1-1 では、TNF_PROBE
マクロによって work_start という名前のプローブポイントが定義されています。このプローブポイントには、state と message という 2 つの引数があります。work_start という名前のプローブが検出されるたびに、変数 state と message のタイムスタンプと値がトレースファイルに記録されます。
#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 マクロの使い方」を参照してください。
属性 |
特性 |
値 |
---|---|---|
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 |
接続されているプローブ関数を切り離します。 |
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 attributes probes selector_list list attributes 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 を終了します。 |