4 アクションおよびサブルーチン
traceやprintfなどのD関数コールを使用して、DTraceによって提供される2つの異なるサービス(アクションとサブルーチン)を呼び出します。アクションはデータをトレースするか、DTraceの外部の状態を変更しますが、サブルーチンは内部のDTrace状態にのみ影響します。
この章では、DTraceアクションとサブルーチンを定義し、その構文とセマンティクスについても説明します。
アクション関数
アクション関数により、DTraceプログラムで、DTrace外部システムとの相互作用が可能になります。最も一般的なアクションは、データのDTraceバッファへの記録です。その他のアクションとしては、現在のプロセスを停止するアクション、現在のプロセス上で特定のシグナルを発行するアクション、トレースをすべて停止するアクションなどがあります。このようなアクションのうち、明確な方法でシステムに変更を加えるものは破壊,アクションと呼ばれます。このようなアクションは、破壊アクションが明示的に有効化されている場合のみ使用されます。デフォルトでは、データ記録のアクションによって、データが主バッファに記録されます。主バッファおよびバッファ・ポリシーの詳細は、「バッファおよびバッファリング」を参照してください。
デフォルト・アクション
節には、任意の数のアクションと変数操作を含めることができます。節を空のままにすると、デフォルト・アクションがとられます。デフォルトのアクションでは、有効なプローブID (EPID)が主バッファ内にトレースされます。epidの詳細は、「組込み変数」を参照してください。EPIDから、dtraceコマンドによって、CPU、プローブID、プローブ関数およびプローブ名が出力されます。
デフォルトのアクションにより、dtraceコマンドの簡単な使用が促進されます。たとえば、次のコマンドを実行すると、vmlinuxモジュール内のすべてのプローブでデフォルト・アクションが可能になります。
# dtrace -m vmlinux
前述のコマンドでは、次のような出力が得られます。
# dtrace -m vmlinux dtrace: description 'vmlinux' matched 35 probes CPU ID FUNCTION:NAME 0 42 __schedule:sleep 0 34 dequeue_task:dequeue 0 40 __schedule:off-cpu 0 23 finish_task_switch:on-cpu 0 24 enqueue_task:enqueue 0 41 __schedule:preempt 0 40 __schedule:off-cpu 0 23 finish_task_switch:on-cpu 0 11 update_process_times:tick 0 42 __schedule:sleep 0 34 dequeue_task:dequeue 0 40 __schedule:off-cpu 0 23 finish_task_switch:on-cpu 0 24 enqueue_task:enqueue 0 41 __schedule:preempt 0 40 __schedule:off-cpu 0 23 finish_task_switch:on-cpu 0 11 update_process_times:tick 0 12 try_to_wake_up:wakeup 0 42 __schedule:sleep ...
データ記録アクション
データ記録アクションは、コアDTraceアクションです。これらのアクションのデフォルトの動作は、主バッファへのデータの記録ですが、投機バッファへのデータの記録も可能です。主バッファおよび投機バッファの詳細は、「バッファおよびバッファリング」および「投機トレース」を参照してください。
次の説明では指定バッファという語を使用して、データの記録先が主バッファか投機バッファ(アクションがspeculateの後ろに指定されている場合)であることを示しています。
freopen
void freopen(string format, ...)
freopenアクションでは、stdoutに関連付けられているファイルを、printf形式の引数で指定されたファイルに変更します。
""文字列が使用されている場合、出力は再度stdoutにリストアされます。
注意:
freopenアクションはデータ記録アクションであることに加えて、任意のファイルを上書きできるため、破壊アクションでもあります。
func
_symaddr func(uintptr_t address)
funcアクションは、指定されたカーネル空間アドレスに対応するシンボルを出力します。たとえば、func((uintptr_t) (&vmlinux`max_pfn))の場合、vmlinux`max_pfnが出力されます。funcアクションは、symの別名です。
mod
_symaddr mod(uintptr_t address)
modアクションは指定したカーネル空間アドレスに対応するモジュールの名前を出力します。たとえば、mod((uintptr_t) (&vmlinux`max_pfn))はvmlinuxを出力します。
printa
void printa(aggregation) void printa(string format, aggregation)
printaアクションでは、集積体を表示し、フォーマットを設定できます。詳細は、「集積体」を参照してください。formatが指定されていない場合、printaは、DTraceコンシューマへのディレクティブのみをトレースし、指定した集積体はデフォルト・フォーマットで処理され、表示されます。formatが指定されると、集積体のフォーマットが設定されます。printaフォーマット文字列の詳細は、「printaアクション」を参照してください。
printaが、DTraceコンシューマが処理する集積体であるdirectiveのみをトレースする場合、カーネル内の集積体は処理されません。したがって、printaディレクティブのトレースとディレクティブの実際の処理の間の時間は、集積体のレート、バッファリング・ポリシー(およびバッファリング・ポリシーがswitchingかどうか)、バッファの切替えのレートなど、バッファ処理に影響を与える要因によって異なります。詳細は、「集積体」および「バッファおよびバッファリング」を参照してください。
printf
void printf(string format, ...)
traceと同様に、printfアクションはD式をトレースしますが、printfでは、複雑なprintfスタイルのフォーマットが可能です。パラメータはformat文字列とその後の任意の数の引数で構成されます。デフォルトでは、引数は指定バッファにトレースされます。その後、次のように、指定されたフォーマット設定文字列に従って、これらの引数にdtraceコマンドの出力フォーマットが設定されます。
printf("execname is %s; priority is %d", execname, curlwpsinfo->pr_pri);詳細は、「printfアクション」を参照してください。
stack
stack stack(int nframes)
stack stack(void)
stackアクションは、カーネル・スタック・トレースを指定バッファに記録します。カーネル・スタックの深さはnframesで指定します。nframesを指定しない場合、stackframesオプションで指定された数のスタック・フレームが記録されます。dtraceコマンドは、ルート・フレームまで、またはnframes制限に達するまで(どちらか早い方)フレームを報告します。
# dtrace -n gettimeofday:entry'{stack()}'
dtrace: description 'gettimeofday:entry' matched 1 probe
CPU ID FUNCTION:NAME
0 196 gettimeofday:entry
vmlinux`pollwake
vmlinux`dtrace_stacktrace+0x30
vmlinux`__brk_limit+0x1e1832d7
vmlinux`__brk_limit+0x1e1913a1
vmlinux`pollwake
vmlinux`do_gettimeofday+0x1a
vmlinux`ktime_get_ts+0xad
vmlinux`systrace_syscall+0xde
vmlinux`audit_syscall_entry+0x1d7
vmlinux`system_call_fastpath+0x16
0 196 gettimeofday:entry
vmlinux`dtrace_stacktrace+0x30
vmlinux`__brk_limit+0x1e1832d7
vmlinux`__brk_limit+0x1e1913a1
vmlinux`security_file_permission+0x8b
vmlinux`systrace_syscall+0xde
vmlinux`audit_syscall_entry+0x1d7
vmlinux`system_call_fastpath+0x16
...
void以外の戻り値を持つstackアクションは、次のように、集積体のキーとして使用することもできます。
# dtrace -n execve:entry'{@[stack()] = count()}'
dtrace: description 'execve:entry' matched 1 probe
^C
vmlinux`dtrace_stacktrace+0x30
vmlinux`__brk_limit+0x1e1832d7
vmlinux`__brk_limit+0x1e1913a1
vmlinux`dtrace_execve+0xcd
vmlinux`audit_syscall_entry+0x1d7
vmlinux`dtrace_stub_execve+0x6c
2
vmlinux`dtrace_stacktrace+0x30
vmlinux`__brk_limit+0x1e1832d7
vmlinux`__brk_limit+0x1e1913a1
vmlinux`do_sigaction+0x13a
vmlinux`dtrace_execve+0xcd
vmlinux`audit_syscall_entry+0x1d7
vmlinux`dtrace_stub_execve+0x6c
13
...sym
_symaddr sym(uintptr_t address)
symアクションは、指定されたカーネル空間アドレスに対応するシンボルを出力します。たとえば、sym((uintptr_t) (&vmlinux`max_pfn))の場合、vmlinux`max_pfnが出力されます。symアクションは、funcの別名です。
trace
void trace(expression)
traceアクションは最も基本的なアクションです。このアクションは引数としてD式をとり、その結果を指定バッファにトレースします。traceアクションの例を次に示します。
trace(execname);
trace(curlwpsinfo->pr_pri);
trace(timestamp / 1000);
trace(‘lbolt);
trace("somehow managed to get here");
traceアクションがバッファで使用される場合、出力フォーマットはデータ型によって異なります。dtraceコマンドによって、データがASCII文字列に類似していると判断された場合、テキストとして出力され、NULL文字(0)で出力を終了します。dtraceによって、データがバイナリである可能性が高いと判断された場合、次のように16進形式で出力されます。
0 342 write:entry
0 1 2 3 4 5 6 7 8 9 a b c d e f 0123456789abcdef
0: c0 de 09 c2 4a e8 27 54 dc f8 9f f1 9a 20 4b d1 ....J.’T..... K.
10: 9c 7a 7a 85 1b 03 0a fb 3a 81 8a 1b 25 35 b3 9a .zz.....:...%5..
20: f1 7d e6 2b 66 6d 1c 11 f8 eb 40 7f 65 9a 25 f8 .}.+fm....@.e.%.
30: c8 68 87 b2 6f 48 a2 a5 f3 a2 1f 46 ab 3d f9 d2 .h..oH.....F.=..
40: 3d b8 4c c0 41 3c f7 3c cd 18 ad 0d 0d d3 1a 90 =.L.A<.<........
traceアクションでrawbytesオプションを指定すると、常にバイナリ・フォーマットを使用すると指定できます。
tracemem
void tracemem(address, size_t nbytes) void tracemem(address, size_t nbytes, size_t dbytes)
tracememアクションは、最初の引数addressとしてD式、2番目の引数nbytesとして定数をとります。tracememアクションは、addressで指定されたアドレスから、nbytesで指定された長さのメモリーを指定バッファにコピーします。2つの引数のみを指定した場合、dtraceはバッファのコンテンツ全体をダンプします。
2番目のフォーマットでは、tracememアクションは、動的に計算されるD式である追加の3番目の引数dbytesをとります。結果は、表示されるバイト数を制限するために使用されます。結果が0未満またはnbytesより大きい場合、結果は無視され、tracememは2つの引数の形式を使用してコールされた場合と同様に動作します。それ以外の場合、dtraceは、指定バッファのdbytesバイトのみをダンプします。
ustack
ノート:
削除された実行可能ファイルでのシンボル参照を実行する場合、プログラムをリンクするときに--export-dynamicオプションを指定する必要があります。このオプションにより、リンカーですべてのシンボルが動的シンボル表(実行時に動的オブジェクトから参照可能なシンボルのセット)に追加されます。gccを使用してオブジェクトをリンクする場合、正しいオプションをリンカーに渡すためにオプションを-Wl,--export-dynamicとして指定します。
また、共有ライブラリまたは削除されていない実行可能ファイルでシンボルを検索する場合、--export-dynamicオプションは必要ありません。
DTraceは、次のように、32ビットおよび64ビット・バイナリの両方でustackアクションの使用をサポートしています。
stack ustack(int nframes, int strsize) stack ustack(int nframes) stack ustack(void)
ustackアクションは、ユーザー・スタック・トレースを指定バッファに記録します。ユーザー・スタックの深さはnframesで指定します。nframesを指定しない場合、ustackframesオプションで指定された数のスタック・フレームが記録されます。ustackはプロープの起動時に呼出し元フレームのアドレスを決定できますが、スタック・フレームはustackアクションがDTraceコンシューマによってユーザー・レベルで処理されるまでシンボルに変換されません。strsizeにゼロ以外の値が指定された場合、ustackは指定された容量の文字列空間を割り当ててから、これを使用してカーネルから直接アドレスからシンボルへ変換します。このような直接のユーザー・シンボル変換は、DTraceでこの使用方法をサポートするスタックトレース・ヘルパーとともにのみ使用されます。そのようなフレームが変換できない場合、そのフレームは16進のアドレスとしてのみ表示されます。
次の例では、アドレスからシンボルへの変換なしでスタックをトレースしています。
# dtrace -n syscall::write:entry'/pid == $target/{ustack(); exit(0)}' -c "./mytestprog -v"
dtrace: description 'syscall::write:entry' matched 1 probe
mytestprog (Version 1.0)
CPU ID FUNCTION:NAME
2 6 write:entry
mytestprog`printver+0x2f
mytestprog`0x401338
mytestprog`main+0xc7
mytestprog`0x401338
libc.so.6`__libc_start_main+0xfd
mytestprog`main
mytestprog`0x400ad0
mytestprog`__libc_csu_init
mytestprog`0x400ad0
mytestprog`0x400af9
ustackシンボル変換はスタック・データが記録された後に発生します。したがって、シンボル変換が実行可能になる前に対応するユーザー・プロセスが終了し、スタック・フレーム変換が不可能になる場合があります。シンボル変換が実行される前にユーザー・プロセスが終了した場合、dtraceは警告メッセージに続いて16進のスタック・フレームを出力します。
破壊アクション
一部のDTraceアクションは、明確な方法でシステムの状態を変更するため、破壊と呼ばれます。破壊アクションは、明示的に有効にしないと使用できません。dtraceを使用する場合、-wオプションを使用して破壊アクションを有効にします。明示的に有効化せずに破壊アクションを実行しようとすると、dtraceは失敗し、次のようなメッセージが表示されます。
dtrace: failed to enable 'syscall': destructive actions not allowed
プロセス破壊アクションは、特定のプロセスに対してのみ影響します。一方、カーネル破壊アクションはシステム全体に影響します。したがって、このようなアクションは、システム上のすべてのプロセスに影響を及ぼすのみでなく、影響を受けるシステムのネットワーク・サービスによっては、その他のシステムにも暗黙的または明示的に影響を及ぼすため、慎重に使用する必要があります。
次の情報は、プロセス破壊アクションとカーネル破壊アクションの両方に関連します。
copyout (プロセス破壊)
void copyout(void *buf, uintptr_t addr, size_t nbytes)
copyoutアクションは、bufで指定したバッファから、現在のスレッドに関連付けられたプロセスのアドレス空間内で指定されたaddrのアドレスにnbytesをコピーします。ユーザー空間アドレスが、現在のアドレス空間で有効な、フォルト・インのページに対応していない場合、エラーが生成されます。
copyoutstr (プロセス破壊)
void copyoutstr(string str, uintptr_t addr, size_t maxlen)
copyoutstrアクションは、strで指定された文字列を、現在のスレッドに関連付けられたプロセスのアドレス空間内のaddrで指定されたアドレスにコピーします。ユーザー空間アドレスが、現在のアドレス空間で有効な、フォルト・インのページに対応していない場合、エラーが生成されます。文字列の長さはstrsizeオプションで設定された値に制限されています。「オプションおよびチューニング可能パラメータ」を参照してください。
raise (プロセス破壊)
void raise(int signal)
raiseアクションは、指定したシグナルを現在実行中のプロセスに送信します。このアクションは、シグナルをプロセスに送信するkillコマンドの使用と類似しています。raiseアクションでは、プロセスの実行中の特定のポイントでシグナルを送信できます。
stop (プロセス破壊)
void stop(void)
stopアクションは、有効なプローブを起動するプロセスが次にカーネルを出るとき、procアクションで停止したときと同じようにプロセスを強制終了します。stopアクションで、任意のDTraceプローブ・ポイントでプロセスを停止できます。このアクションを使用すると、単純なブレークポイントでは補足が難しい特定の状態のプログラムを捕捉し、そのプロセスにgdbなどの従来のデバッガをアタッチできます。また、gcoreユーティリティを使用すると、停止したプロセスの状態をコア・ファイルに保存し、後で分析に使用できます。
system (プロセス破壊)
void system(string program, ...)
systemアクションは、指定されたprogramを、シェルへ入力されたものとして実行します。program文字列には、printfまたはprintaのフォーマット変換を含めることができます。そのフォーマット変換に合った引数を指定する必要があります。有効なフォーマット変換の詳細は、「出力フォーマット」を参照してください。
次の例では、毎秒1回dateコマンドを実行します。
# dtrace -wqn tick-1sec'{system("date")}'
Tue Oct 16 10:21:34 BST 2012
Tue Oct 16 10:21:35 BST 2012
Tue Oct 16 10:21:36 BST 2012
^C
#
先ほどの例よりもアクションの使用方法が複雑になった例を、次に示します。printf変換をprogram文字列で使用し、パイプなどの従来のフィルタリング・ツールも使用しています。次のソース・コードを入力し、whosend.dという名前のファイルに保存します。
#pragma D option destructive
#pragma D option quiet
proc:::signal-send
/args[2] == SIGINT/
{
printf("SIGINT sent to %s by ", args[1]->pr_fname);
system("getent passwd %d | cut -d: -f5", uid);
}前述のスクリプトを実行すると、次のような出力が得られます。
# dtrace -s whosend.d SIGINT sent to top by root SIGINT sent to bash by root SIGINT sent to bash by A Nother ^C SIGINT sent to dtrace by root
指定されたコマンドは、プローブの起動のコンテキストでは実行されません。実行されるのは、systemアクションの詳細を含むバッファがユーザー・レベルで処理される場合です。この処理が行われる方法と時期は、「バッファおよびバッファリング」で説明するように、バッファリング・ポリシーによって異なります。デフォルトのバッファリング・ポリシーでは、バッファ処理レートはswitchrateオプションで指定されます。
次の例のように、明示的にswitchrateをチューニングして、デフォルトの1秒よりも長くした場合、システム内で遅延が発生します。time.dという名前のファイルに保存します。
#pragma D option quiet
#pragma D option destructive
#pragma D option switchrate=5sec
tick-1sec
/n++ < 5/
{
printf("walltime : %Y\n", walltimestamp);
printf("date : ");
system("date");
printf("\n");
}
tick-1sec
/n == 5/
{
exit(0);
}前述のスクリプトを実行すると、次のような出力が得られます。
# dtrace -s time.d walltime : 2012 Oct 16 10:26:07 date : Tue Oct 16 10:26:11 BST 2012 walltime : 2012 Oct 16 10:26:08 date : Tue Oct 16 10:26:11 BST 2012 walltime : 2012 Oct 16 10:26:09 date : Tue Oct 16 10:26:11 BST 2012 walltime : 2012 Oct 16 10:26:10 date : Tue Oct 16 10:26:11 BST 2012 walltime : 2012 Oct 16 10:26:11 date : Tue Oct 16 10:26:11 BST 2012
前述の出力では、walltimeの値は異なりますが、dateの値は同一です。この結果は、dateコマンドが、systemアクションが記録されたときではなく、バッファが処理されたときに実行されているためです。
chill (カーネル破壊)
void chill(int nanoseconds)
chillアクションによって、指定されたナノ秒数の間、DTraceがスピンします。このアクションは、主にタイミングに関連する問題の調査に役立ちます。たとえば、このアクションを使用して、競合しているウィンドウを開いたり、定期イベントを同期させたり、同期を解除することができます。DTraceプローブのコンテキストでは、割込みが無効になっているため、chillアクションを使用すると、割込み遅延、スケジュール遅延、およびディスパッチ遅延が発生します。このように、chillは想定外のシステムへの影響があるため、乱用は避けてください。システム・アクティビティは定期的な割込み処理に依存するため、DTraceは、CPU上で1秒間隔のうち500ミリ秒を超えたchillアクションの実行を拒否します。最大chill間隔を超過すると、DTraceは、不正な操作を表すエラーをレポートします。
# dtrace -w -n syscall::openat:entry'{chill(500000001)}'
dtrace: allowing destructive actions
dtrace: description 'syscall::openat:entry' matched 1 probe
dtrace: 57 errors
CPU ID FUNCTION:NAME
dtrace: error on enabled probe ID 1 (ID 14: syscall::openat:entry): \
illegal operation in action #1
chillへの複数のコールによる合計、または単一のプローブを使用する複数のDTraceコンシューマによる合計が、この時間制限を超えた場合も同様です。たとえば、次のコマンドを実行しても同じエラーが生成されます。
# dtrace -w -n syscall::openat:entry'{chill(250000000); chill(250000001);}'panic (カーネル破壊)
void panic(void)
panicアクションがトリガーされると、カーネル・パニックが発生します。このアクションは、必要に応じて強制的にシステムのクラッシュ・ダンプを実行するときに使用します。このアクションをリング・バッファリングと組み合せることで、問題を把握できます。詳細は、「バッファおよびバッファリング」を参照してください。panicアクションを使用すると、パニックの原因となったプローブを示すパニック・メッセージが表示されます。また、rsyslogdによっても再起動時にメッセージが表示されます。クラッシュ・ダンプのメッセージ・バッファには、プローブおよびpanicアクションの原因となったイベント・コントロール・ブロック(ECB)も含まれます。
特殊アクション
次に、データ記録アクションでも破壊アクションでもない特殊アクションを示します。
exit
void exit(int status)
exitアクションでは、トレースをただちに終了し、DTraceコンシューマに、トレースを終了し、最終処理を行い、指定されたstatus値でexit()をコールするように指示できます。exitはステータスをユーザー・レベルに戻すという点でデータ記録アクションとみなされます。ただし、その他のデータ記録アクションとは異なり、exitは投機的にトレースできません。exitアクションによって、DTraceコンシューマはバッファ・ポリシーに関係なく終了します。exitはデータ記録アクションのため、欠落することがあります。
exitをコールすると、他のCPU上ですでに実行中のDTraceアクションのみが最後まで実行されます。どのCPUでも、新たにアクションは実行されません。このルールの唯一の例外はENDプローブの処理であり、これはDTraceコンシューマがexitアクションを処理し、トレースを終了するように指示した後でコールされます。
サブルーチン関数
サブルーチン関数は通常、DTraceの内部状態にのみ影響を及ぼすという点で、アクションとは異なります。このため、破壊サブルーチンというようなものは存在しません。また、サブルーチンはデータをバッファにトレースしません。サブルーチンの多くは、アプリケーション・プログラミング・インタフェースに類似しています。詳細は、マニュアル・ページの項3を参照してください。
これらのサブルーチンの多くには一時バッファが必要で、一時バッファは節の間のみ保持されます。このようなバッファには、事前に割り当てられたスクラッチ・メモリーが使用されます。
alloca
void *alloca(size_t size)
alloca関数は、スクラッチ・メモリーからsizeバイトを割り当て、割り当てられたメモリーへのポインタを返します。必ず8バイトのバイト列を持つポインタが返されます。スクラッチ・メモリーは、節の開始から完了までの間しか有効ではありません。allocaで割り当てられたメモリーは、節の完了時に割当てが解除されます。使用できるスクラッチ・メモリーが不足している場合、メモリーの割当ては行われず、エラーが生成されます。
basename
string basename(char *str)
basename関数は、指定された文字列のコピーから構成される文字列を生成しますが、ディレクトリ・パスなど、/で終わる接頭辞は付きません。返される文字列には、スクラッチ・メモリーからメモリーが割り当てられます。そのためこれは節の間のみ有効です。使用できるスクラッチ・メモリーが不足している場合、basenameは実行されず、エラーが生成されます。
bcopy
void bcopy(void *src, void *dest, size_t size)
bcopy関数はsrcがポイントするメモリーから、destがポイントするメモリーへsizeバイトをコピーします。すべてのコピー元のメモリーはスクラッチ・メモリーの外部、すべてのコピー先のメモリーはスクラッチ・メモリーの内部にある必要があります。この条件と一致していない場合、コピーは行われず、エラーが生成されます。
cleanpath
string cleanpath(char *str)
cleanpath関数は、strで指定されたパスのコピーで構成される文字列を生成します。ただし、特定の重複要素は排除されます。特に、パス内の/./要素は削除され、/../要素は縮小されます。パス内の/../は、シンボリック・リンクを考慮せずに縮小されます。このため、cleanpathを使用すると、有効なパスが縮小され、短い無効なパスが返されることがあります。
たとえば、strが「/foo/../bar」であり、/fooが/net/foo/exportへのシンボリック・リンクの場合、barは/内ではなく、/net/foo内に存在するのに、cleanpathは文字列「/bar」を返します。この問題は、cleanpathが起動プローブのコンテキストでコールされますが、このコンテキストでは、任意の名前の完全なシンボリック・リンク解決が行われないために発生します。返される文字列には、スクラッチ・メモリーからメモリーが割り当てられます。そのためこれは節の間のみ有効です。使用できるスクラッチ・メモリーが不足している場合、cleanpathは実行されず、エラーが生成されます。
copyin
void *copyin(uintptr_t addr, size_t size)
copyin関数は、指定されたユーザー・アドレス(addr)からDTraceスクラッチ・バッファに、指定されたサイズ(バイト)をコピーし、このバッファのアドレスを返します。ユーザー・アドレスは、現在のスレッドに関連付けられたプロセスの空間に含まれるアドレスであるとみなされます。最終的なバッファ・ポインタは、必ず8バイトのバイト列を持つことになります。指定されたアドレスは、現在のプロセス内のフォルト・インのページに対応している必要があります。アドレスがフォルト・インのページに対応していない場合や、使用できるスクラッチ・メモリーが不足している場合は、NULLが返され、エラーが生成されます。
copyinstr
string copyinstr(uintptr_t addr) string copyinstr(uintptr_t addr, size_t maxlen)
copyinstr関数は、指定されたユーザー・アドレス(addr)からDTraceスクラッチ・バッファに、NULLで終了するC文字列をコピーし、このバッファのアドレスを返します。ユーザー・アドレスは、現在のスレッドに関連付けられたプロセスの空間に含まれるアドレスであるとみなされます。maxlenパラメータが指定されている場合、調査済の過去のaddrバイト数に制限が設定されます(結果の文字列は常にNULLで終了します)。結果の文字列の長さは、strsizeオプションで設定された値に制限されています。詳細は、「オプションおよびチューニング可能パラメータ」を参照してください。copyin関数の場合と同じく、指定されたアドレスは、現在のプロセス内のフォルト・インのページに対応している必要があります。アドレスがフォルト・インのページに対応していない場合や、使用できるスクラッチ・メモリーが不足している場合は、NULLが返され、エラーが生成されます。
copyinto
void copyinto(uintptr_t addr, size_t size, void *dest)
copyinto関数は、指定されたユーザー・アドレス(addr)から、destで指定されたDTraceスクラッチ・バッファに、指定されたサイズ(バイト)をコピーします。ユーザー・アドレスは、現在のスレッドに関連付けられたプロセスの空間に含まれるアドレスであるとみなされます。指定されたアドレスは、現在のプロセス内のフォルト・インのページに対応している必要があります。アドレスがフォルト・インのページに対応していない場合や、コピー先のメモリーの一部がスクラッチ・メモリー内にない場合、コピーは行われず、エラーが生成されます。
d_path
string d_path(struct path *ptr)
d_path関数は、ptrでポイントされるstruct pathの絶対パス名を含む文字列を生成します。返される文字列には、スクラッチ・メモリーからメモリーが割り当てられます。そのためこれは節の間のみ有効です。使用できるスクラッチ・メモリーが不足している場合、d_pathは実行されず、エラーが生成されます。
dirname
string dirname(char *str)
dirname関数は、strで指定されたパス名の最終レベルを除くすべてのレベルを構成する文字列を生成します。返される文字列には、スクラッチ・メモリーからメモリーが割り当てられます。そのためこれは節の間のみ有効です。使用できるスクラッチ・メモリーが不足している場合、dirnameは実行されず、エラーが生成されます。
index
int index(const char *s, const char *subs) int index(const char *s, const char *subs, int start)
index関数は、オプションの位置startから開始し、s文字列内の部分文字列(subs)が最初に出現した位置を特定します。startで指定した値が0未満の場合、これは暗黙的に0に設定されます。sが空の文字列の場合、indexは0を返します。sにsubsと一致するものがない場合、indexは1を返します。
inet_ntoa
string inet_ntoa(ipaddr_t *addr)
inet_ntoa関数は、IPv4アドレスへのaddrのポインタをとり、ドット区切りの10進数文字列として返します。返される文字列には、スクラッチ・メモリーからメモリーが割り当てられます。そのためこれは節の間のみ有効です。使用できるスクラッチ・メモリーが不足している場合、inet_ntoaは実行されず、エラーが生成されます。
inet_ntoa6
string inet_ntoa6(in6_addr_t *addr)
inet_ntoa6関数は、IPv6アドレスへのポインタaddrをとり、RFC 1884表記規則2の文字列として、小文字の16進数で返します。返される文字列には、スクラッチ・メモリーからメモリーが割り当てられます。そのためこれは節の間のみ有効です。使用できるスクラッチ・メモリーが不足している場合、inet_ntoa6は実行されず、エラーが生成されます。
inet_ntop
string inet_ntop(int af, void *addr)
inet_ntop関数はIPアドレスへのポインタaddrをとり、指定されたアドレス・ファミリに応じた文字列バージョンを返します。サポートされているアドレス・ファミリはAF_INETおよびAF_INET6であり、どちらもDプログラムで使用できるよう定義されています。返される文字列には、スクラッチ・メモリーからメモリーが割り当てられます。そのためこれは節の間のみ有効です。使用できるスクラッチ・メモリーが不足している場合、inet_ntopは実行されず、エラーが生成されます。
lltostr
string lltostr(int64_t longlong)
lltostr関数はlonglongを文字列に変換します。返される文字列には、スクラッチ・メモリーからメモリーが割り当てられます。そのためこれは節の間のみ有効です。使用できるスクラッチ・メモリーが不足している場合、lltostrは実行されず、エラーが生成されます。
mutex_owned
int mutex_owned(kmutex_t *mutex)
mutex_owned関数は、コール元のスレッドが指定されたカーネル相互排他ロックを所有している場合は、ゼロ以外の値を返し、そうでない場合は、ゼロを返します。
mutex_owner
kthread_t *mutex_owner(kmutex_t *mutex)
mutex_owner関数は、指定された適応型カーネル相互排他ロックの現在の所有者のスレッド・ポインタを返します。指定された適応型相互排他ロックの所有者が存在しない場合や、指定された相互排他ロックがスピン相互排他ロックである場合、mutex_ownerはNULLを返します。
mutex_type_adaptive
int mutex_type_adaptive(kmutex_t *mutex)
Oracle Linuxカーネルのすべての相互排他ロックは適応型であり、mutex_type_adaptive関数は常に1を返します。
mutex_type_spin
int mutex_type_spin(kmutex_t *mutex)
Oracle Linuxカーネルのすべての相互排他ロックは適応型であり、mutex_type_spin関数は常に0を返します。
progenyof
int progenyof(pid_t pid)
progenyof関数は、コール元のプロセス(一致したプローブを現在トリガーしているスレッドに関連付けられたプロセス)が指定されたプロセスID pidの子孫に該当する場合、ゼロ以外の値を返します。
rindex
int rindex(const char *s, const char *subs) int rindex(const char *s, const char *subs, int start)
rindex関数は、オプションの位置startから開始し、文字列s内の部分文字列subsが最後に出現した位置を特定します。startで指定した値が0未満の場合、これは暗黙的に0に設定されます。sが空の文字列の場合、rindexは0を返します。sのsubsに一致するものがない場合、rindexは-1を返します。
rw_iswriter
int rw_iswriter(krwlock_t *rwlock)
rw_iswriter関数は、指定された読取り/書込みロック(rwlock)が書込み側に保持されているか必要とされている場合、ゼロ以外の値を返します。ロックが読取り側のみで保持されていて、書込み側がブロックされていない場合、またはロックがまったく保持されていない場合、rw_iswriterはゼロを返します。
rw_read_held
int rw_read_held(krwlock_t *rwlock)
rw_read_held関数は、指定された読取り/書込みロック(rwlock)が読取り側によって保持されている場合、ゼロ以外の値を返します。ロックが書込み側のみで保持されている場合やまったく保持されていない場合、rw_read_heldはゼロを返します。
rw_write_held
int rw_write_held(krwlock_t *rwlock)
rw_write_held関数は、指定された読取り/書込みロック(rwlock)が書込み側によって保持されている場合、ゼロ以外の値を返します。ロックが読取り側のみで保持されている場合やまったく保持されていない場合、rw_write_heldはゼロを返します。
speculation
int speculation(void)
speculation関数は、speculateで使用する投機トレース・バッファを予約し、このバッファの識別子を返します。詳細は、「投機トレース」を参照してください。
strchr
string strchr(const char *s, char c)
strchr関数は、文字列sの文字cの最初の出現場所へのポインタを返します。一致するものがない場合、strstrは0を返します。この関数は、ワイド文字またはマルチバイト文字では機能しません。
strjoin
string strjoin(char *str1, char *str2)
strjoin関数は、str1とstr2の連結で構成される文字列を生成します。返される文字列には、スクラッチ・メモリーからメモリーが割り当てられます。そのためこれは節の間のみ有効です。使用できるスクラッチ・メモリーが不足している場合、strjoinは実行されず、エラーが生成されます。
strrchr
string strrchr(const char *s, char c)
strrchr関数は、文字列sの文字cの最後の出現場所へのポインタを返します。一致するものがない場合、strrstrは0を返します。この関数は、ワイド文字またはマルチバイト文字では機能しません。
strstr
string strstr(const char *s, const char *subs)
strstr関数は、文字列sの部分文字列subsの最初の出現場所へのポインタを返します。sが空の文字列の場合、strstrは空の文字列へのポインタを返します。一致するものがない場合、strstrは0を返します。
strtok
string strtok(const char *str, const char *delim)
strtok関数は、デリミタとしてdelimを使用して、文字列を一連のトークンに解析します。最初にstrtokをコールしたとき、str内で解析する文字列を指定します。次のトークンを取得するための後続のコールでは、それぞれNULLとしてstrを指定します。それぞれのコールには、異なるデリミタを指定できます。strをトラバースするためにstrtokによって使用される内部ポインタは、同じプローブの複数にわたる有効化においてのみ有効です。つまり、これは暗黙的な節ローカル変数と同様に動作します。strtok関数は、トークンがなくなるとNULLを返します。