manページ  — KTRACE

ktrace – プロセスのトレース

ライブラリ 書式 解説 SYSCTL チューナブル 戻り値 エラー 関連項目 歴史

Standard C Library (libc, -lc)

#include <sys/param.h>

#include <sys/time.h>

#include <sys/uio.h>

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

The ktrace function returns the value 0 if successful; otherwise the value -1 is returned and the global variable errno is set to indicate the error.

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

[ENOTDIR]
	パスの構成要素中にディレクトリ以外のものが含まれています。
[ENAMETOOLONG]
	パス名の構成要素が 255 文字を越えているか、 またはパス名全体が 1023 文字を越えています。
[ENOENT]
	指定のトレースファイルが存在しません。
[EACCES]
	前置パス名の構成要素について検索許可が拒否されています。
[ELOOP]
	パス名を変換するときに検出されたシンボリックリンクが多すぎます。
[EIO]	ファイルシステムに読み書きしている間に入出力エラーが発生しました。
[ENOSYS]
	カーネルが ktrace サポートとともにコンパイルされていません。

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

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