.\" Copyright (c) 1993
.\"	The Regents of the University of California.  All rights reserved.
.\"
.\" Redistribution and use in source and binary forms, with or without
.\" modification, are permitted provided that the following conditions
.\" are met:
.\" 1. Redistributions of source code must retain the above copyright
.\"    notice, this list of conditions and the following disclaimer.
.\" 2. Redistributions in binary form must reproduce the above copyright
.\"    notice, this list of conditions and the following disclaimer in the
.\"    documentation and/or other materials provided with the distribution.
.\" 3. All advertising materials mentioning features or use of this software
.\"    must display the following acknowledgement:
.\"	This product includes software developed by the University of
.\"	California, Berkeley and its contributors.
.\" 4. Neither the name of the University nor the names of its contributors
.\"    may be used to endorse or promote products derived from this software
.\"    without specific prior written permission.
.\"
.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
.\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
.\" SUCH DAMAGE.
.\"
.\"     @(#)ktrace.2	8.1 (Berkeley) 6/4/93
.\" %FreeBSD: src/lib/libc/sys/ktrace.2,v 1.24 2003/12/14 14:54:53 jkoshy Exp %
.\"
.\" $FreeBSD$
.Dd June 4, 1993
.Dt KTRACE 2
.Os
.Sh 名称
.Nm ktrace
.Nd プロセスのトレース
.Sh ライブラリ
.Lb libc
.Sh 書式
.In sys/param.h
.In sys/time.h
.In sys/uio.h
.In sys/ktrace.h
.Ft int
.Fn ktrace "const char *tracefile" "int ops" "int trpoints" "int pid"
.Sh 解説
.Fn ktrace
システムコールは、1 つまたは複数のプロセスのトレースを有効または無効にします。
ユーザは自分のプロセスだけをトレースできます。
スーパユーザだけが、setuid プログラムまたは
setgid プログラムをトレースできます。
.Pp
.Fa tracefile
引数は、トレースに使用するファイルのパス名を指定します。
ファイルは存在していなければならず、
呼び出し側プロセスによって書込み可能な通常ファイルである必要があります。
トレースレコードはすべてファイルの末尾に追加されるので、
直前のトレースデータを切り捨てるためにはファイルの長さを 0 にする必要が
あります。
トレース点が無効な場合 (後述の KTROP_CLEAR を参照)、
.Fa tracefile
は NULL にできます。
.Pp
.Fa ops
引数は要求された ktrace 操作を指定します。
定義されている操作は次のとおりです:
.Bl -column KTRFLAG_DESCENDXXX -offset indent
.It "KTROP_SET	"
.Fa trpoints
で指定されたトレース点を有効にします。
.It "KTROP_CLEAR	"
.Fa trpoints
で指定されたトレース点を無効にします。
.It "KTROP_CLEARFILE	すべてのトレースを停止します。"
.It "KTRFLAG_DESCEND	トレースの変更が、指定のプロセスとその現在の"
すべての子プロセスに適用されます。
.El
.Pp
.Fa trpoints
引数は関心のあるトレース点を指定します。
定義されているトレース点は次のとおりです:
.Bl -column KTRFAC_SYSCALLXXX -offset indent
.It "KTRFAC_SYSCALL	システムコールをトレースします。"
.It "KTRFAC_SYSRET	システムコールからの戻り値をトレースします。"
.It "KTRFAC_NAMEI	パス名の探索操作をトレースします。"
.It "KTRFAC_GENIO	すべての入出力をトレースします"
(このオプションが大量の出力を生成する可能性があることに注意してください)。
.It "KTRFAC_PSIG	ポストされたシグナルをトレースします。"
.It "KTRFAC_CSW	コンテキストスイッチをトレースします。"
.It "KTRFAC_INHERIT	これ以降の子にトレースを継承します。"
.El
.Pp
各トレースイベントは、汎用のヘッダの後に
トレース点に固有の構成要素が続く形式のレコードを出力します。
汎用のヘッダは次のとおりです:
.Bd -literal
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;
};
.Ed
.Pp
.Va ktr_len
フィールドはこのヘッダに続く
.Va ktr_type
データの長さを示します。
.Va ktr_pid
フィールドと
.Va ktr_comm
フィールドは、レコードを生成したプロセスとコマンドを示します。
.Va ktr_time
フィールドは、
レコードが生成された時刻を (マイクロ秒単位で) 示します。
.Va ktr_buf
は、内部カーネルポインタであって有用ではありません。
.Pp
汎用ヘッダには
.Va ktr_len
バイトの長さの
.Va ktr_type
レコードが続きます。
タイプに固有のレコードは
.In sys/ktrace.h
インクルードファイル内で定義されています。
.Sh SYSCTL チューナブル
次の
.Xr sysctl 8
チューナブルが
.Fn ktrace
の動作に影響します:
.Bl -tag -width indent
.It Va kern.ktrace.geniosize
トレースされた I/O 要求がトレースファイルに記録するデータ量を制限します。
.It Va kern.ktrace.request_pool
一度に記録するトレースイベント数を制限します。
.El
.Pp
プロセスをデバッグできるかを制御する sysctl チューナブル
.Xr ( p_candebug 9
によって決められている) もまた
.Fn ktrace
の操作に影響します。
.Sh 戻り値
.Rv -std ktrace
.Sh エラー
.Fn ktrace
システムコールは次の場合に失敗します:
.Bl -tag -width Er
.It Bq Er ENOTDIR
パスの構成要素中にディレクトリ以外のものが含まれています。
.It Bq Er ENAMETOOLONG
パス名の構成要素が 255 文字を越えているか、
またはパス名全体が 1023 文字を越えています。
.It Bq Er ENOENT
指定のトレースファイルが存在しません。
.It Bq Er EACCES
前置パス名の構成要素について検索許可が拒否されています。
.It Bq Er ELOOP
パス名を変換するときに検出されたシンボリックリンクが多すぎます。
.It Bq Er EIO
ファイルシステムに読み書きしている間に入出力エラーが発生しました。
.It Bq Er ENOSYS
カーネルが
.Nm
サポートとともにコンパイルされていません。
.El
.Pp
一時的な資源不足のために、
スレッドが 1 個以上のトレースイベントを記録できないことがあり得ます。
この状態はカーネルによって記憶され、次に成功するトレース要求において
.Va ktr_type
フィールドの
.Li KTR_DROP
フラグがセットされます。
.Sh 関連項目
.Xr kdump 1 ,
.Xr ktrace 1 ,
.Xr utrace 2 ,
.Xr sysctl 8 ,
.Xr p_candebug 9
.Sh 歴史
.Fn ktrace
システムコールは
.Bx 4.4
ではじめて登場しました。