日本語 man コマンド類 (ja-man-1.1j_5) と日本語 man ドキュメント (ja-man-doc-5.4 (5.4-RELEASE 用) など) をインストールすると、以下のような man コマンド閲覧、キーワード検索が コンソールからできるようになります。
4.11-RELEASE-K, 5.4-RELEASE-K, 5.5-RELEASE-K, 6.0-RELEASE-K から 6.4-RELEASE-K, 7.0-RELEASE-K から 7.4-RELEASE-K, 8.0-RELEASE-K から 8.4-RELEASE-K, 9.0-RELEASE-K から 9.3-RELEASE-K, 10.0-RELEASE-K から 10.3-RELEASE-K, 11.0-RELEASE-K から 11.4-RELEASE-K, 12.0-RELEASE-K, 12.1-RELEASE-K は、 プライベート版 (小金丸が編集してまとめたもの) ですが、 より多くの翻訳したファイルが含まれています。 (5.4-RELEASE-K から 6.4-RELEASE-K, 7.0-RELEASE-K から 7.4-RELEASE-K, 8.0-RELEASE-K から 8.4-RELEASE-K, 9.0-RELEASE-K から 9.3-RELEASE-K, 10.0-RELEASE-K から 10.3-RELEASE-K, 11.0-RELEASE-K から 11.4-RELEASE-K, 12.0-RELEASE-K から 12.4-RELEASE-K, 13.0-RELEASE-K から 13.3-RELEASE-K, 14.0-RELEASE-K から 14.1-RELEASE-K は、全翻訳済み)
13.3-STABLE-K, 15.0-CURRENT-K は現在、作成中で日々更新されています。
Table of Contents
SDT(9) FreeBSD カーネル開発者マニュアル SDT(9)
名称
SDT -- 静的に定義されたトレースのプローブを追加するための DTrace フレーム
ワーク
書式
#include <sys/param.h>
#include <sys/queue.h>
#include <sys/sdt.h>
SDT_PROVIDER_DECLARE(prov);
SDT_PROVIDER_DEFINE(prov);
SDT_PROBE_DECLARE(prov, mod, func, name);
SDT_PROBE_DEFINE(prov, mod, func, name);
SDT_PROBE_DEFINE0(prov, mod, func, name);
SDT_PROBE_DEFINE1(prov, mod, func, name, arg0);
SDT_PROBE_DEFINE2(prov, mod, func, name, arg0, arg1);
SDT_PROBE_DEFINE3(prov, mod, func, name, arg0, arg1, arg2);
SDT_PROBE_DEFINE4(prov, mod, func, name, arg0, arg1, arg2, arg3);
SDT_PROBE_DEFINE5(prov, mod, func, name, arg0, arg1, arg2, arg3, arg4);
SDT_PROBE_DEFINE6(prov, mod, func, name, arg0, arg1, arg2, arg3, arg4,
arg5);
SDT_PROBE_DEFINE7(prov, mod, func, name, arg0, arg1, arg2, arg3, arg4,
arg5, arg6);
SDT_PROBE_DEFINE0_XLATE(prov, mod, func, name);
SDT_PROBE_DEFINE1_XLATE(prov, mod, func, name, arg0, xarg0);
SDT_PROBE_DEFINE2_XLATE(prov, mod, func, name, arg0, xarg0, arg1, xarg1);
SDT_PROBE_DEFINE3_XLATE(prov, mod, func, name, arg0, xarg0, arg1, xarg1,
arg2, xarg2);
SDT_PROBE_DEFINE4_XLATE(prov, mod, func, name, arg0, xarg0, arg1, xarg1,
arg2, xarg2, arg3, xarg3);
SDT_PROBE_DEFINE5_XLATE(prov, mod, func, name, arg0, xarg0, arg1, xarg1,
arg2, xarg2, arg3, xarg3, arg4, xarg4);
SDT_PROBE_DEFINE6_XLATE(prov, mod, func, name, arg0, xarg0, arg1, xarg1,
arg2, xarg2, arg3, xarg3, arg4, xarg4, arg5, xarg5);
SDT_PROBE_DEFINE7_XLATE(prov, mod, func, name, arg0, xarg0, arg1, xarg1,
arg2, xarg2, arg3, xarg3, arg4, xarg4, arg5, xarg5, arg6, xarg6);
SDT_PROBE0(prov, mod, func, name);
SDT_PROBE1(prov, mod, func, name, arg0);
SDT_PROBE2(prov, mod, func, name, arg0, arg1);
SDT_PROBE3(prov, mod, func, name, arg0, arg1, arg2);
SDT_PROBE4(prov, mod, func, name, arg0, arg1, arg2, arg3);
SDT_PROBE5(prov, mod, func, name, arg0, arg1, arg2, arg3, arg4);
SDT_PROBE6(prov, mod, func, name, arg0, arg1, arg2, arg3, arg4, arg5);
SDT_PROBE7(prov, mod, func, name, arg0, arg1, arg2, arg3, arg4, arg5,
arg6);
解説
SDT マクロによって、プログラマは、カーネルコードの静的なトレースポイント
を定義することができます。これらのトレースポイントは、コードを dtrace(1)
を使用して機器を備えることができる、DTrace プローブを作成するために、SDT
フレームワークによって使用されます。デフォルトで、SDT トレースポイント
は、無効にされ、周囲のコードに効果がありません。与えられたトレースポイン
トに対応する DTrace プローブが有効にされるとき、トレースポイントを実行す
るスレッドは、ハンドラを呼び出し、プローブを起動します。さらに、トレース
ポイントは、引数を取ることができ、有効にされたプローブを起動するとき、
データを DTrace フレームワークへ渡すことを可能にします。
複数のトレースポイントは、プログラマが特定のコードの実行パスにプローブを
結び付けることではなく、論理システムイベントに類似する DTrace プローブを
作成することを可能にし、単一の DTrace プローブに類似しています。例えば、
ネットワークスタックへの IP パケットの到着に対応する DTrace プローブは、2
つの SDT トレースポイントを使用して定義されます: IPv4 パケットのための一
つと IPv6 パケットのための一つです。
DTrace プローブを定義することに加えて、SDT マクロによって、プログラマは、
名前空間の論理的に関連するプローブすることを可能にして、新しい DTrace プ
ロバイダを定義することができます。例は、FreeBSD の sctp(4) の実装のために
SDT プローブを含んでいる、FreeBSD の sctp プロバイダです。
SDT_PROVIDER_DECLARE() と SDT_PROVIDER_DEFINE() マクロは、SDT フレーム
ワークがある prov と名前が付けられた DTrace プロバイダを宣言し、定義する
ためにそれぞれ使用されます。プロバイダは、一度だけ定義される必要がありま
す。しかしながら、プロバイダは、そのプロバイダに属する、あらゆる SDT プ
ローブを定義する前に宣言されなければなりません。
同様に、SDT_PROBE_DECLARE() と SDT_PROBE_DEFINE*() マクロは、SDT フレーム
ワークを使用して DTrace プローブを宣言して、定義するために使用されます。
一旦、プローブが定義されたならば、そのプローブのためのトレースポイント
は、カーネルコードに追加されます。DTrace プローブ識別子は、プロバイダ、モ
ジュール、関数と名前から成り、それらすべては、SDT プローブ定義で指定され
ます。プローブは、モジュール名を指定するべきでないことに注意してください:
プローブのモジュール名は、カーネルモジュールがアンロードされるとき、それ
が破壊されるべきかどうか判断するために使用されます。「バグ」セクションを
参照してください。プローブは、複数のカーネルモジュールに渡って定義されて
はならないことに特に注意してください。
`-' 文字 (ダッシュ) がプローブ名で必要とされるなら、技術的な理由のために
様々な SDT_*() マクロに渡されたプローブ name パラメータで `__' (2 つの下
線) として表わされるべきです (ダッシュは、C の識別子として有効ではありま
せん)。
また、SDT_PROBE_DEFINE*() マクロによって、プログラマは、プローブに渡され
る引数のタイプを宣言することができます。これは、オプションです。
(SDT_PROBE_DEFINE() マクロの使用を通して) 引数タイプが省略されるなら、引
数を利用したいユーザは、手動で D スクリプトの正確なタイプに、それらを
cast しなければなりません。プローブ定義がそれらの引数タイプの宣言を含むこ
とは強く推奨されます。
SDT_PROBE_DEFINE*_XLATE() マクロは、引数タイプが対応する xarg 引数によっ
て指定されたタイプにダイナミックに変換されるプローブのために使用されま
す。これは、他のオペレーティングシステムからプローブ定義を移植するとき、
主として役に立ちます。dtrace(1) によって見られるように、これらのマクロを
使用して定義されたプローブの引数は、プローブ定義の xarg タイプと一致する
タイプがあります。しかしながら、トレースポイントで渡された引数は、プロー
ブ定義の本来の引数タイプと一致するタイプがあり、したがって、本来のタイプ
は、変換されたタイプに動的に変換されます。適切な変換プログラムが
/usr/lib/dtrace で定義されている限り、プローブを使用するスクリプトは、与
えられた SDT プローブ引数の基本的なタイプにそれら自体が関係している必要は
ありません。
SDT_PROBE*() マクロは、SDT トレースポイントを作成するために使用されます。
それらは、実行形式のコードに追加される必要があり、それらが呼び出される
コードを設置するために使用することができます。
プロバイダ
多くのカーネル DTrace プロバイダが、利用可能です。一般的に、これらのプロ
バイダは、安定しているインタフェースを定義し、次のように処理されるべきで
す: 既存の D スクリプトは、プローブが名前を代えられるか、または、その引数
が修正されるなら、壊されます。しかしながら、しばしば、サブシステムまたは
ドライバをデバッグするために特別の SDT プローブを定義するために役に立ちま
す。同様に、開発者は、それらの将来の安定性に責任を持たずに、SDT プローブ
のグループを提供することを望みます。そのようなプローブは、新しいプロバイ
ダを定義する代わりに `sdt' プロバイダに追加されるべきです。
使用例
現在のシステムで利用可能な DTrace プロバイダは、次でリストすることができ
ます。
dtrace -l | sed 1d | awk '{print $2}' | sort -u
与えられたプロバイダによって提供さるプローブの詳細なリストは、-P フラグを
使用してプロバイダを指定することによって取得することができます。例えば、
`sched' プロバイダのためのプローブと引数のタイプを見るために、次を実行し
ます。
dtrace -lv -P sched
次のプローブ定義は、カーネルがタイプ Destination Unreachable の ICMP パ
ケットを受信するとき、仮定としてトリガされる、呼び出された
`icmp:::receive-unreachable' を DTrace プローブを作成します。
SDT_PROVIDER_DECLARE(icmp);
SDT_PROBE_DEFINE1(icmp, , , receive__unreachable,
"struct icmp *");
特に、このプローブは、単一の引数を取ります: パケットのための ICMP ヘッダ
を含んでいる構造体へのポインタ。このプローブのモジュール名は、指定されな
いことに注意してください。
ネットワークスタックが IP パケットを受信するとき、起動する DTrace プロー
ブを考慮してください。そのようなプローブは、複数のトレースポイントによっ
て定義されます:
SDT_PROBE_DEFINE3(ip, , , receive, "struct ifnet *",
"struct ip *", "struct ip6_hdr *");
int
ip_input(struct mbuf *m)
{
struct ip *ip;
...
ip = mtod(m, struct ip *);
SDT_PROBE3(ip, , , receive, m->m_pkthdr.rcvif, ip, NULL);
...
}
int
ip6_input(struct mbuf *m)
{
struct ip6_hdr *ip6;
...
ip6 = mtod(m, struct ip6_hdr *);
SDT_PROBE3(ip, , , receive, m->m_pkthdr.rcvif, NULL, ip6);
...
}
特に、プローブは、カーネルが IPv4 パケットまたは IPv6 パケットのいずれか
を受信するとき、起動するべきです。
上記の ICMP プローブの議論を考慮してください。その 2 番目の引数が、RFC
792 で定義されている、ICMP パケットの ICMP ヘッダを表わすために FreeBSD
カーネルで定義されたタイプである、タイプ struct icmp であることを注意しま
す。Linux は、同じ目的のために、対応するタイプ struct icmphdr があります
が、そのフィールド名は、FreeBSD の struct icmp と異なります。同様に、
illumos は、再び異なるフィールド名で icmph_t タイプを定義しています。すべ
ての 3 つのオペレーティングシステムで定義される `icmp:::pkt-receive' プ
ローブでさえ、まだ、ICMP ヘッダ引数の与えられたフィールドを抽出するための
OS 特有のスクリプトを書かなければなりません。動的に変換されたタイプは、次
の問題を解決します: ICMP ヘッダを表わす OS 独立の c(7) 構造体を定義するこ
とができ、例えば、struct icmp_hdr_dt と 3 つの OS 特有のタイプの各々から
dtrace(1) ライブラリのパスのすべての struct icmp_hdr_dt まで、変換プログ
ラムを定義します、次に、上記の FreeBSD のプローブを、次で定義することがで
きます:
SDT_PROBE_DEFINE1_XLATE(ip, , , receive, "struct icmp *",
"struct icmp_hdr_dt *");
関連項目
dtrace(1), dtrace_io(4), dtrace_ip(4), dtrace_proc(4), dtrace_sched(4),
dtrace_tcp(4), dtrace_udp(4)
作者
DTrace と SDT SDT フレームワークは、John Birrell <jb@FreeBSD.org> によっ
て Solaris から FreeBSD に最初に移植されました。このマニュアルページは、
Mark Johnston <markj@FreeBSD.org> によって書かれました。
バグ
SDT マクロによって、プローブのモジュールと関数名をプローブ定義の一部とし
て指定することができます。DTrace フレームワークは、カーネルモジュールがア
ンロードされるとき、どのプローブが破壊されるべきであるかを決定するため
に、プローブのモジュール名を使用するので、プローブのモジュール名は、定義
されたモジュールの名前と一致するべきです。SDT は、プローブ定義で指定され
ないままであるなら、モジュール名を適切に設定します。「使用例」を参照して
ください。
(FreeBSD のポートの拡張によって) オリジナルの SDT 実装のゴールの 1 つは、
不活性の SDT プローブは、性能に影響をあたえるべきでないということです。こ
れは、不運にも事実と異なります。SDT トレースポイントは、それらが定義され
ているコードに少量の 0 でない待ち時間の量を追加します。プローブのより洗練
された実装は、この問題を軽減するための助けとなります。
FreeBSD 11.4 April 18, 2015 FreeBSD 11.4