名称

ktrace — プロセスのトレース

ライブラリ

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_USER	アプリケーション特有のイベントをトレースします.
KTRFAC_STRUCT	特定のデータ構造をトレースします.
KTRFAC_SYSCTL	sysctl をトレースします.
KTRFAC_PROCCTOR	プロセス構築をトレースします.
KTRFAC_PROCDTOR	プロセス破壊をトレースします.
KTRFAC_CAPFAIL	ケーパビリティ機能をトレースします.
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;  /* タイムスタンプ */ 
 intptr_t ktr_tid;  /* ktr_buffer でした */ 
};

ktr_len フィールドは、このヘッダに続く ktr_type データの長さを示します。 ktr_pid フィールドと ktr_comm フィールドは、レコードを生成したプロセスとコマンドを示します。 ktr_time フィールドは、レコードが生成された時刻を (マイクロ秒単位で) 示します。 ktr_tid フィールドは、スレッド ID を保持しています。

汎用ヘッダには、 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() の操作に影響します。

戻り値

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 フラグがセットされます。

関連項目

kdump(1), ktrace(1), utrace(2), sysctl(8), p_candebug(9)

歴史

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