KTRACE(2)

名称
ktrace - プロセスのトレース

ライブラリ
libc

書式
<sys/param.h> <sys/time.h> <sys/uio.h> <sys/ktrace.h> int ktrace(const char *tracefile, int ops, int trpoints, int pid)

解説
ktrace() システムコールは、1 つまたは複数のプロセスのトレースを有効または無効にします。 ユーザは自分のプロセスだけをトレースできます。 スーパユーザだけが、setuid プログラムまたは setgid プログラムをトレースできます。

tracefile 引数は、トレースに使用するファイルのパス名を指定します。 ファイルは存在していなければならず、 呼び出し側プロセスによって書込み可能な通常ファイルである必要があります。 トレースレコードはすべてファイルの末尾に追加されるので、 直前のトレースデータを切り捨てるためにはファイルの長さを 0 にする必要が あります。 トレース点が無効な場合 (後述の KTROP_CLEAR を参照)、 tracefile は NULL にできます。

ops 引数は要求された ktrace 操作を指定します。 定義されている操作は次のとおりです:
KTROP_SET |
trpoints で指定されたトレース点を有効にします。
KTROP_CLEAR |
trpoints で指定されたトレース点を無効にします。
KTROP_CLEARFILE | すべてのトレースを停止します。
KTRFLAG_DESCEND | トレースの変更が、指定のプロセスとその現在の
すべての子プロセスに適用されます。

trpoints 引数は関心のあるトレース点を指定します。 定義されているトレース点は次のとおりです:
KTRFAC_SYSCALL | システムコールをトレースします。
KTRFAC_SYSRET | システムコールからの戻り値をトレースします。
KTRFAC_NAMEI | パス名の探索操作をトレースします。
KTRFAC_GENIO | すべての入出力をトレースします
(このオプションが大量の出力を生成する可能性があることに注意してください)。
KTRFAC_PSIG | ポストされたシグナルをトレースします。
KTRFAC_CSW | コンテキストスイッチをトレースします。
KTRFAC_INHERIT | これ以降の子にトレースを継承します。

各トレースイベントは、汎用のヘッダの後に トレース点に固有の構成要素が続く形式のレコードを出力します。 汎用のヘッダは次のとおりです:

    struct ktr_header {
    	int	ktr_len;		/* バッファの長さ */
    	short	ktr_type;		/* トレースレコードのタイプ */
    	pid_t	ktr_pid;		/* プロセス ID */
    	char	ktr_comm[MAXCOMLEN+1];	/* コマンド名 */
    	struct	timeval ktr_time;	/* タイムスタンプ */
    	caddr_t	ktr_buf;
    };

ktr_len フィールドはこのヘッダに続く ktr_type データの長さを示します。 ktr_pid フィールドと ktr_comm フィールドは、レコードを生成したプロセスとコマンドを示します。 ktr_time フィールドは、 レコードが生成された時刻を (マイクロ秒単位で) 示します。 ktr_buf は、内部カーネルポインタであって有用ではありません。

汎用ヘッダには ktr_len バイトの長さの ktr_type レコードが続きます。 タイプに固有のレコードは <sys/ktrace.h> インクルードファイル内で定義されています。

SYSCTL チューナブル
次の sysctl(8) チューナブルが ktrace() の動作に影響します:

kern.ktrace.geniosize
    トレースされた I/O 要求がトレースファイルに記録するデータ量を制限します。

kern.ktrace.request_pool
    一度に記録するトレースイベント数を制限します。

プロセスをデバッグできるかを制御する sysctl チューナブル ((p_candebug) 9 によって決められている) もまた ktrace() の操作に影響します。

戻り値

エラー
ktrace() システムコールは次の場合に失敗します:

[ENOTDIR]
    パスの構成要素中にディレクトリ以外のものが含まれています。

[ENAMETOOLONG]
    パス名の構成要素が 255 文字を越えているか、 またはパス名全体が 1023 文字を越えています。

[ENOENT]
    指定のトレースファイルが存在しません。

[EACCES]
    前置パス名の構成要素について検索許可が拒否されています。

[ELOOP]
    パス名を変換するときに検出されたシンボリックリンクが多すぎます。

[EIO]
    ファイルシステムに読み書きしている間に入出力エラーが発生しました。

[ENOSYS]
    カーネルが ktrace サポートとともにコンパイルされていません。

一時的な資源不足のために、 スレッドが 1 個以上のトレースイベントを記録できないことがあり得ます。 この状態はカーネルによって記憶され、次に成功するトレース要求において ktr_type フィールドの KTR_DROP フラグがセットされます。

関連項目
kdump(1), ktrace(1), utrace(2), sysctl(8), p_candebug(9)

歴史
ktrace() システムコールは 4.4BSD ではじめて登場しました。