日本語 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.3-RELEASE-K, 13.0-RELEASE-K から 13.2-RELEASE-K は、全翻訳済み)
13.3-STABLE-K, 15.0-CURRENT-K は現在、作成中で日々更新されています。
Table of Contents
DTRACE(1) FreeBSD 一般コマンドマニュアル DTRACE(1)
名称
dtrace -- 動的トレース (追跡) コンパイラとトレース (追跡) ユーティリティ
書式
dtrace [-32 | -64] [-aACeFGhHlqSvVwZ] [-b bufsz] [-c cmd]
[-D name [=value]] [-I path] [-L path] [-o output] [-s script]
[-U name] [-x arg [=value]] [-X a | c | s | t] [-p pid]
[-P provider [[predicate] action]]
[-m [provider:] module [[predicate] action]]
[-f [[provider:] module:] function [[predicate] action]]
[-n [[[provider:] module:] function:] name [[predicate] action]]
[-i probe-id [[predicate] action]]
解説
DTrace は、Solaris から移植された総合的な動的トレース (追跡) フレームワー
クです。DTrace は、管理者、開発者とサービスマンがオペレーティングシステム
とユーザプログラムの振る舞いに関する任意の質問に簡潔に答えることを可能と
する強力なインフラストラクチャを提供しています。
dtrace コマンドは、次のものを含む DTrace 機能によって提供される必要不可欠
なサービスへの一般的なインタフェースを供給しています:
• 現在、DTrace によって公表されたプローブとプロバイダのセットをリ
ストするオプション
• プローブ記述指定子 (プロバイダ、モジュール、関数、名前) のいず
れかを使用して直接的なプローブを有効にするオプション
• D コンパイラを実行して、コマンド行に直接書かれた 1 つ以上の D
プログラムファイルまたはプログラムをコンパイルするオプション
• 匿名のトレース (追跡) プログラムを生成するオプション
• プログラムの安定性のレポートを生成するオプション
• 振る舞いをトレースし、バッファリングする DTrace を変更して、追
加の D コンパイラ機能を有効にするオプション
利用者は、インタプリタファイルを作成するために shebang (#!) 宣言で、それ
を使用することによって D スクリプトを作成するために dtrace を使用すること
ができます。また、利用者は、D プログラムをコンパイルして、実際に -e オプ
ションを使用してトレースを有効にしないでそれらの特性を決定することを試み
るために dtrace を使用することができます。
オプション
-P, -m, -f, -n と -i オプションによって受け付けられた引数は、スラッシュ
(/) で囲まれたオプションの D 言語 predicate と大括弧 ({}) で囲まれた、オ
プションの D 言語の action 文リストを含むことができます。コマンド行で指定
された D プログラムコードは、シェルによってメタ文字の解釈を避けるために適
切にクォート (引用) されなければなりません。
次のオプションが、サポートされます:
-32 | -64
D コンパイラは、オペレーティングシステムのカーネルの従来のデータ
モデルを使用してプログラムを作成します。-32 オプションが指定され
るなら、dtrace によって、D コンパイラは、32 ビットのデータモデル
を使用して強制的に D プログラムをコンパイルします。-64 オプション
が指定されるなら、dtrace によって、D コンパイラは、64 ビットの
データモデルを使用して強制的に D プログラムをコンパイルします。こ
れらのオプションは、通常 dtrace がデフォルトとして従来のデータモ
デルを選択するように、必要ではありません。データモデルは、整数タ
イプと他の言語の特性のサイズに影響します。32 ビットと 64 ビットの
カーネルの両方で、いずれかのデータモデルのためにコンパイルされた
D プログラムを実行することができます。また、-32 と -64 オプション
は、-G オプションによって作成された elf(5) ファイル形式 (ELF32 ま
たは ELF64) を決定します。
-a 匿名でトレースされた状態を要求して、トレースされたデータを表示し
ます。利用者は、新しいデータを待ち続けているのではなく、匿名のト
レース状態を消費する直後に、dtrace が終了するように強制する -a オ
プションと -e オプションを組み合わせることができます。
-A 匿名のトレースのためにディレクティブ (指示) を生成し、それらを
/boot/dtrace.dof に書き込みます。このオプションは、匿名のトレース
のために指定されたプローブを有効とするために 1 組の dtrace 設定
ファイルディレクティブを構成して、次に終了します。デフォルトで、
dtrace は、ファイル /boot/dtrace.dof にディレクティブを格納するこ
とを試みます。代替の出力ファイルを指定するために -o オプションを
使用して、この振る舞いを変更することができます。
-b bufsz
プリンシパルのトレースバッファサイズ bufsz を設定します。トレース
バッファサイズは、サイズ接尾辞 k、m、g または t のいずれかを含む
ことができます。バッファ空間を割り付けることができないなら、
dtrace は、バッファサイズを減少することを試み、bufresize 特性の設
定に依存して終了します。
-c cmd 指定されたコマンド cmd を実行し、完了すれば、終了します。2 つ以上
の -c オプションがコマンド行に存在しているなら、dtrace は、すべて
のコマンドが終了したとき、それを終了するような、各子プロセスのた
めの終了ステータスを報告して、終了します。最初のコマンドのプロセ
ス ID は、コマンド行で指定されるあらゆる D プログラム、または
$target マクロ変数を通して -s オプションを使用して利用可能とされ
ます。
-C それらをコンパイルする前に、D プログラムで C プリプロセッサ
cpp(1) を実行します。利用者は、-D, -U, -I と -H オプションを使用
して C プリプロセッサにオプションを渡すことができます。-X オプ
ションを使用するなら、利用者は、C 標準の適合の程度を選択すること
ができます。C プリプロセッサを呼び出すとき、D コンパイラによって
定義されたトークンのセットの記述については、-X を参照してくださ
い。
-D name [=value]
(-C オプションを使用して有効にされた) cpp(1) を呼び出すときに、
name を定義します。利用者が追加の value を指定するなら、name は、
対応する値に代入されます。このオプションは、それぞれの cpp(1) の
呼び出しに -D オプションを渡します。
-e あらゆる要求をコンパイルし、匿名のトレース状態 (-a オプション) を
消費した後に終了しますが、あらゆるプローブを有効にする前です。利
用者は、匿名のトレースデータを印刷して終了するために -a オプショ
ンと、このオプションを組み合わせることができます。また、利用者
は、このオプションと D コンパイラオプションを組み合わせることもで
きます。この組み合わせは、プログラムが実際にそれらを実行しないで
コンパイルし、対応する計装を有効にすることを検証します。
-f [[provider:] module:] function [[predicate] action]
トレースまたはリスト (-l オプション) する関数名を指定します。対応
する引数は、プローブ記述形式 provider:module:function,
module:function または function のいずれかを含むことができます。
不特定のプローブ記述フィールドは、空白のままにされ、それらの
フィールドの値にかかわらずあらゆるプローブに一致します。function
以外の修飾子が記述で指定されないなら、対応する function があるす
べてのプローブは、一致されます。オプションの D プローブ節で -f 引
数を末尾に付けることができます。利用者は、一度に、コマンド行で 2
つの以上の -f オプションを指定することができます。
-F 関数エントリを識別することによって、トレースの出力を結合して、返
ります。関数エントリのプローブレポートは、字下げされ、それらの出
力は、`->' が前に付けられます。関数リターンのプローブレポートは、
字下げされず、それらの出力は、`<-' が前に付けられます。システム
コールのエントリプローブレポートは、字下げされ、それらの出力は、
`=>' が前に付けられます。システムコールのリターンプローブレポート
は、字下げされず、それらの出力は、`<=' が前に付けられます。
-G 組み込まれた DTrace プログラムを含んでいる ELF ファイルを生成しま
す。プログラムで指定された DTrace プローブは、別のプログラムにリ
ンクできるリロケータブル ELF オブジェクトの内部に保存されます。-o
オプションが存在しているなら、ELF ファイルは、このオペランドのた
めの引数として指定されたパス名を使用して保存されます。-o オプショ
ンが存在していなくて、名前が filename.d であるファイルに DTrace
プログラムが、含まれているなら、ELF ファイルは、名前 filename.o
を使用して保存されます。そうでなければ、ELF ファイルは、名前
d.out を使用して保存されます。
-h 指定されたプロバイダ定義でプローブに対応するマクロを含むヘッダ
ファイルを生成します。このオプションは、-G オプションをつけて後で
使用するために他のソースファイルによって含まれているヘッダファイ
ルを生成するために使用されるべきです。-o オプションが存在している
なら、ヘッダファイルは、そのオプションのための引数として指定され
たパス名を使用して保存されます。-o オプションが存在していなくて、
名前が filename.d であるファイルに DTrace プログラムが、含まれて
いるなら、ヘッダファイルは、名前 filename.h を使用して保存されま
す。
-H (-C オプションを使用して有効にされた) cpp(1) を呼び出すときに、含
まれているファイルのパス名を印刷 (表示) します。このオプション
は、-H オプションを、それぞれの cpp(1) 呼び出しに渡し、各行あたり
1 つ、標準エラーに、パス名のリストを表示します。
-i probe-id [[predicate] action]
トレースまたはリスト (l オプション) するためにプローブ識別子
(probe-id) を指定します。利用者は、`dtrace -l` によって表示される
ように 10 進整数を使用してプローブ ID を指定することができます。
オプションの D プローブ節で -i 引数を末尾に付けることができます。
利用者は、一度に、2 つ以上の -i のオプションを指定することができ
ます。
-I path
(-C オプションを使用して有効にされる) cpp(1) を呼び出すとき、
#include ファイルのために検索パスに指定されたディレクトリ path を
追加します。このオプションは、それぞれの cpp(1) 呼び出しに -I を
渡します。指定された path は、デフォルトのディレクトリのリストの
前方の検索パスに挿入されます。
-l それらを有効にする代わりにプローブをリストします。-l オプションが
指定されるなら、dtrace は、-P, -m, -f, -n, -i と -s オプションを
使用して与えられた記述に一致するプローブのレポートを作成します。
これらのオプションのいずれも指定されないなら、このオプションは、
すべてのプローブをリストします。
-L path
DTrace ライブラリのために検索パスに指定されたディレクトリ path を
追加します。DTrace ライブラリは、D プログラムを書くとき、使用でき
る共通の定義を含むために使用されます。指定された path は、デフォ
ルトのライブラリ検索パスの後に追加されます。
-m [provider:] module [[predicate] action]
トレースまたはリスト (-l オプション) するモジュール名を指定しま
す。対応する引数は、プローブ記述形式 provider:module または
module のいずれかを含むことができます。不特定のプローブ記述フィー
ルドは、空白のままにされ、それらのフィールドの値にかかわらずあら
ゆるプローブに一致します。module 以外の修飾子が記述で指定されない
なら、対応する module があるすべてのプローブが一致されます。オプ
ションの D プローブ節で -m 引数を末尾に付けることができます。一度
に、コマンド行で 2 つ以上の -m オプションを指定することができま
す。
-n [[[provider:] module:] function:] name [[predicate] action]
トレースまたはリスト (-l オプション) するプローブ名を指定します。
対応する引数は、プローブ記述形式 provider:module:function:name,
module:function:name, function:name または name のいずれかを含む
ことができます。不特定のプローブ記述フィードは、空白のままにさ
れ、それらのフィールドの値にかかわらずあらゆるプローブに一致しま
す。name 以外の修飾子が記述で指定されないなら、対応する name があ
るすべてのプローブが一致されます。オプションの D プローブ節で -n
引数を末尾に付けることができます。一度に、コマンド行で 2 つ以上の
-n オプションを指定することができます。
-o output
-A, -G と -l オプション、またはトレースデータ自体のための output
ファイルを指定します。-A オプションが存在し、-o が存在していない
なら、デフォルトの出力ファイルは、/boot/dtrace.dof です。-G オプ
ションが存在し、-s オプションの引数が、形式 filename.d で、-o が
存在していないなら、デフォルトの出力ファイルは、filename.o です。
そうでなければ、デフォルトの出力ファイルは、d.out です。
-p pid 指定されたプロセス ID pid を grab (とらえる) し、シンボルテーブル
をキャッシュし、完了すれば終了します。コマンド行に 2 つ以上の -p
オプションが存在しているなら、dtrace は、終了した各プロセスの終了
ステータスを報告して、すべてのコマンドが終了したとき、終了しま
す。最初のプロセス ID は、コマンド行で指定されるあらゆる D プログ
ラム、または $target マクロ変数を通して -s オプションを使用して利
用可能とされます。
-P provider [[predicate] action]
トレースまたはリスト (-l オプション) するプロバイダ名を指定しま
す。残っているプローブ記述フィールドのモジュール、関数と名前は、
空白のままにされ、それらのフィールドの値にかかわらずあらゆるプ
ローブに一致します。オプションの D プローブ節で -P 引数を末尾に付
けることができます。利用者は、一度に、コマンド行で 2 つの以上の
-P オプションを指定することができます。
-q quiet (静かな) モードに設定します。dtrace は、指定されたオプショ
ンと D プログラムによって一致されたプローブの数のようなメッセージ
を削除して、カラムヘッダ、CPU ID、プローブ ID を印刷せず、または
改行文字を出力に挿入します。`dtrace()' と `printf()' のような D
プログラム文によってトレースされ、書式化されるデータのみが、標準
出力に表示されます。
-s script
指定された D プログラムのソースファイルをコンパイルします。-e オ
プションが存在しているなら、プログラムは、コンパイルされますが、
計装 (instrumentation) は、有効にされません。-l オプションが存在
しているなら、プログラムは、コンパイルされ、それと一致するプロー
ブのセットは、リストされますが、計装は、有効にされません。-e, -l,
-G または -A のいずれも存在していないなら、D プログラムによって指
定された計装は、有効にされ、トレースは、始まります。
-S D コンパイラの中間コードを表示します。D コンパイラは、それぞれの
D プログラムのために生成された中間コードのレポートを標準エラーに
出力します。
-U name
(-C オプションを使用して有効にされる) cpp(1) を呼び出すとき、指定
された name を未定義とします。このオプションは、それぞれの cpp(1)
呼び出しに -U オプションを渡します。
-v verbose (冗長) モードを設定します。-v オプションが指定されるな
ら、dtrace は、指定された D プログラムのために最小のインタフェー
スの安定性と依存レベルを表示したプログラム安定性レポートを作成し
ます。
-V dtrace によってサポートされた最も高い D プログラミングのインタ
フェースバージョンを報告します。バージョン情報は、標準出力に印刷
(出力) され、dtrace コマンドは、終了します。
-w -s, -P, -m, -f, -n または -i オプションを使用して指定された D プ
ログラムの破壊的な動作を許可にします。-w オプションが指定されない
なら、dtrace は、破壊的な動作を含む D プログラムのコンパイルまた
は有効にすることを許可しません。
-x arg [=value]
DTrace ランタイムオプションまたは D コンパイラオプションを有効に
するか、または変更します。ブール値オプションは、それらの名前を指
定することによって、有効にされます。値があるオプションは、等号
(=) でオプション名と値を分けることによって設定されます。
-X a | c | s | t
(-C オプションを使用して有効にされる) cpp(1) を呼び出すとき、選択
されるべきである ISO C 規格への準拠の度合いを指定します。-X オプ
ション引数は、引数文字の値に依存する __STDC__ マクロの値と存在に
影響します。
-X オプションは、次の引数をサポートします:
a デフォルトです。ISO C によって要求されたセマンティック
(意味論) の変更がある、ISO C と K&R 互換性の拡張。これ
は、-X が指定されないなら、デフォルトのモードです。cpp(1)
が、-Xa オプションに関連して呼び出されるとき、事前に定義
されたマクロ __STDC__ は、0 の値があります。
c 適合しています。K&R C 互換性の拡張がない、厳密な適合 ISO
C。cpp(1) が -Xc オプションに関連して呼び出されるとき、事
前に定義されたマクロ __STDC__ は、1 の値があります。
s K&R C のみ。cpp(1) が -Xs オプションに関連して呼び出され
るとき、マクロ __STDC__ は、定義されません。
t 遷移。ISO C によって要求されたセマンティック (意味論) の
変更がない、ISO C と K&R 互換性の拡張。cpp(1) が -Xt オプ
ションに関連して呼び出されるとき、事前に定義されたマクロ
__STDC__ は、0 の値があります。
-X オプションが D コンパイラがどのように C プリプロセッサを呼び出
すかに影響するだけであるように、-Xa と -Xt オプションは、D の視点
と同等であり、両方とも、C 構築環境から設定の再使用を軽減するため
にだけに提供されます。
-X モードにかかわらず、次の追加 C プリプロセッサ定義は、すべての
モードで常に指定されて有効です:
• __sun
• __unix
• __SVR4
• __sparc (SPARC システムだけで)
• __sparcv9 (64 ビットのプログラムがコンパイルされるとき,
SPARC システムだけで)
• __i386 (32 ビットのプログラムがコンパイルされるとき,
x86 システムだけで)
• __amd64 (64 ビットのプログラムがコンパイルされるとき,
x86 システムだけで)
• __`uname -s`_`uname -r` (例えば, `FreeBSD_9.2-RELEASE')
• __SUNW_D=1
• __SUNW_D_VERSION=0xMMmmmuuu
ここで、MM は、16 進数のメジャーリリース値で、mmm は、
16 進数のマイナリリース値で、そして、uuu は、16 進数の
マイクロリリース値です。
-Z 0 のブローブに一致するプローブ記述を許可します。-Z オプションが指
定されないなら、dtrace は、エラーを報告し、D プログラムファイル
(-s オプション) で指定された任意のプローブ記述、またはコマンド行
(-P, -m, -f, -n または -i オプション) で、あらゆる知られているプ
ローブに一致しない記述を含んでいるなら、終了します。
オペランド
利用者は、1 組のマクロ変数 ($1, $2 その他) を定義するために dtrace コマン
ド行で、0 以上の追加引数を指定することができます。-s オプションを使用して
指定された D プログラムまたはコマンド行で追加引数を使用することができま
す。
関連ファイル
/boot/dtrace.dof 匿名のトレース指示のためのファイル。
終了ステータス
次の終了ステータスが返されます:
0 成功して終了。
D プログラム要求について、0 の終了ステータスは、プログラムが成功
してコンパイルされた、プローブが成功して有効にされたか、または匿
名の状態が、成功して検索されたことを示します。dtrace は、たとえ指
定されたトレース要求がエラーまたは低下 (drop) に遭遇したとして
も、0 を返します。
1 エラーが起こりました。
D プログラム要求について、1 の終了ステータスは、プログラムのコン
パイルが失敗したか、または指定された要求を、満たすことができな
かったことを示します。
2 不正なコマンド行オプションまたは引数が指定されました。
関連項目
cpp(1), dtruss(1), elf(5), SDT(9)
Solaris Dynamic Tracing Guide.
FreeBSD 11.2 April 18, 2015 FreeBSD 11.2