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> インクルードファイル内で定義されています。

戻り値

エラー
ktrace() は次の場合に失敗します。

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

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

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

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

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

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

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

関連項目
kdump(1), ktrace(1)

歴史
ktrace() 関数は 4.4BSD ではじめて登場しました。