ktrace(2)

ktrace − プロセスのトレース

標準 C ライブラリ (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> インクルードファイル内で定義されていま す。

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

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

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

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

戻り値

関数 ktrace() は、処理が成功すると値 0 を返します。そうでない場合、値 -1 が返され、グローバル変数 errno が設定されてエラーを示します。

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

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

[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 ではじめて登場しました。

FreeBSD 10.0 June 4, 1993 FreeBSD 10.0