tail head cat sleep
QR code linking to this page

manページ  — KTRACE

名称

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_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() の操作に影響します。

戻り値

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() システムコールは BSD 4.4 ではじめて登場しました。

KTRACE (2) June 4, 1993

tail head cat sleep
QR code linking to this page


このマニュアルページサービスについてのご意見は Ben Bullock にお知らせください。 Privacy policy.