.\" %FreeBSD: src/lib/libc/sys/ptrace.2,v 1.12.2.12 2001/12/14 18:34:01 ru Exp %
.\"	%NetBSD: ptrace.2,v 1.2 1995/02/27 12:35:37 cgd Exp $
.\"
.\" This file is in the public domain.
.\" $FreeBSD$
.Dd January 20, 1996
.Dt PTRACE 2
.Os
.Sh 名称
.Nm ptrace
.Nd プロセスのトレースとデバッグ
.Sh ライブラリ
.Lb libc
.Sh 書式
.In sys/types.h
.In sys/ptrace.h
.Ft int
.Fn ptrace "int request" "pid_t pid" "caddr_t addr" "int data"
.Sh 解説
.Fn ptrace
はトレースとデバッグの機能を提供します。これによって 1 つのプロセス
.\".Em tracing
(トレース
するプロセス) が
他のプロセス
.\".Em traced
(トレース
されるプロセス) を制御できます。
ほとんどの場合、トレースされるプロセスは正常に実行されます。
ただし、トレースされるプロセスはシグナル
.Xr ( sigaction 2
を参照)
を受信すると停止します。トレースするプロセスは、
.Xr wait 2
または
.Dv SIGCHLD
シグナルによってこれを検知し、停止されたプロセスの状態を調査して、
それを終了させるか、または適切な形で実行を継続させます。
.Fn ptrace
は、これらすべてを制御するメカニズムです。
.Pp
.Fa request
引数は、どの操作を実行するかを指定します。
残りの引数の意味は操作によって異なります。
後述する 1 つの特殊なケースを除いて、
.Fn ptrace
呼び出しはすべてトレースするプロセスによって行われ、
.Fa pid
引数はトレースされるプロセスのプロセス ID を指定します。
.Fa request
は次のものにできます。
.Bl -tag -width 12n
.It Dv PT_TRACE_ME
この要求は、トレースされるプロセスが使用する唯一の要求です。
この要求は、
プロセスがその親によってトレースされることを宣言します。
他の引数はすべて無視され
ます (親プロセスが子プロセスをトレースしない場合は、
かなり混乱した結果になります。
トレースされるプロセスが停止すると、このプロセスは、
.Fn ptrace
によってしか実行を継続できません)。プロセスがこの要求を使用し、
.Xr execve 2
またはそれに組み込まれているルーチン
(たとえば、
.Xr execv 3 )
を呼び出した場合、
そのプロセスは新しいイメージの最初の命令を実行する前に停止します。
また、実行される実行可能モジュールの
setuid または setgid ビットは無視されます。
.It Dv PT_READ_I , Dv PT_READ_D
これらの要求は、トレースされるプロセスのアドレス空間から 1 つの
.Vt int
データを読み取ります。従来、
.Fn ptrace
は命令とデータについて区別されたアドレス空間のある
マシンを許容していました。これが 2 つの要求がある理由です。概念的には、
.Dv PT_READ_I
が命令空間から読み取り、
.Dv PT_READ_D
がデータ空間から読み取ります。現在の
.Fx
システムでは、これらの 2 つの要求は完全に同一です。
.Fa addr
引数が、読み取りが行われる (トレースされるプロセスの仮想アドレス空間内の)
アドレスを指定します。
このアドレスはどのような境界調整制約も満たす必要はありません。
読み取られた値は
.Eo \&
.Fn ptrace
.Ec
からの戻り値として
返されます。
.It Dv PT_WRITE_I , Dv PT_WRITE_D
これらの要求は
.Dv PT_READ_I
および
.Dv PT_READ_D
と同様ですが、読み取るのではなく
書き込むところが異なります。
.Fa data
引数で書き込まれる値を指定します。
.It Dv PT_CONTINUE
トレースされるプロセスは実行を継続します。
.Fa addr
は、実行が再開される場所 (プログラムカウンタの新しい値)、
または実行が停止されたところで再開されることを示す
.Po Vt caddr_t Pc Ns 1
を指定します。
.Fa data
には、トレースされるプロセスが実行を再開するときに受信するシグナル番号、
またはシグナルを送信しない場合には 0 を指定します。
.It Dv PT_STEP
トレースされるプロセスは 1 命令ずつステップ実行されます。
.Fa addr
には
.Po Vt caddr_t Pc Ns 1
を渡す必要があります。
.Fa data
フィールドは使用されません。
.It Dv PT_KILL
トレースされるプロセスは、あたかも
.Dv SIGKILL
を配信シグナルとして
.Dv PT_CONTINUE
が使用されたかのように、終了します。
.It Dv PT_ATTACH
この要求は、他の無関係なプロセスの制御を取得し、
そのトレースを開始します。
トレースされるプロセスからの協力は必要としません。このケースでは、
.Fa pid
にトレースされるプロセスのプロセス ID を指定し、
他の 2 つの引数は無視されます。
この要求では、ターゲットプロセスがトレースする
プロセスと同じ実 UID を持つこと、
それが setuid または setgid された実行可能モジュールでないこと
が要求されます (トレースするプロセスが root として実行されている
場合、これらの制約は適用されません)。
トレースするプロセスは、新たにトレースされるプロセスを停止させ、
あたかも最初からずっとトレースしていたかのように制御できます。
.It Dv PT_DETACH
この要求は PT_CONTINUE と類似していますが、実行を継続する別の場所を
指定できないこと、
および要求が成功した後、トレースされていたプロセスはもはや
トレースされず、通常どおり実行を継続することが異なります。
.El
.Pp
さらにマシンに固有の要求が存在することがあります。i386
では、これらは次のとおりです。
.Bl -tag -width 12n
.It Dv PT_GETREGS
この要求は、トレースされるプロセスのマシンレジスタを、
.Fa addr
が指す
.Do
.Vt "struct reg"
.Dc
.Pf ( Aq Pa machine/reg.h
内に定義されています) 内に読み取ります。
.It Dv PT_SETREGS
この要求は
.Dv PT_GETREGS
の逆です。
.Fa addr
が指す
.Do
.Vt "struct reg"
.Dc
.Pf ( Aq Pa machine/reg.h
内に定義されています)
からトレースされるプロセスのマシンレジスタをロードします。
.It Dv PT_GETFPREGS
この要求はトレースされるプロセスの浮動小数点レジスタを
.Fa addr
が指す
.Do
.Vt "struct fpreg"
.Dc
.Pf ( Aq Pa machine/reg.h
に定義されています) に読み取ります。
.It Dv PT_SETFPREGS
この要求は
.Dv PT_GETFPREGS
の反対です。
.Fa addr
が指す
.Dq Li "struct fpreg"
.Pf ( Aq Pa machine/reg.h
内に定義されています)
からトレースされるプロセスの浮動小数点レジスタをロードします。
.It Dv PT_GETDBREGS
この要求はトレースされるプロセスのデバッグレジスタを
.Fa addr
が指す
.Do
.Vt "struct dbreg"
.Dc
.Pf ( Aq Pa machine/reg.h
内に定義されています)
に読み取ります。
.It Dv PT_SETDBREGS
この要求は
.Dv PT_GETDBREGS
の反対です。
.Fa addr
の指す
.Do
.Vt "struct dbreg"
.Dc
.Pf ( Aq Pa machine/reg.h
内に定義されています)
からトレースされるプロセスのデバッグレジスタにロードします。
.El
.Sh 戻り値
いくつかの要求で
.Fn ptrace
はエラー以外の場合にも
.Li -1
を返します。
曖昧さをなくすためには、呼び出しの前に
.Va errno
を 0 に設定し、後でチェックします。
.Sh エラー
.Fn ptrace
関数は次の場合に処理に失敗します。
.Bl -tag -width Er
.It Bq Er ESRCH
.Bl -bullet -compact
.It
指定されたプロセス ID を持つプロセスが存在しません。
.El
.It Bq Er EINVAL
.Bl -bullet -compact
.It
プロセスが自分自身に対して
.Dv PT_ATTACH
を使おうとしました。
.It
.Fa request
が正しい要求の 1 つではありませんでした。
.It
.Dv PT_CONTINUE
へのシグナル番号
.Fa ( data )
が 0 でないか、または正しいシグナル番号ではありませんでした。
.It
.Dv PT_GETREGS ,
.Dv PT_SETREGS ,
.Dv PT_GETFPREGS ,
.Dv PT_SETFPREGS ,
.Dv PT_GETDBREGS
または
.Dv PT_SETDBREGS
が、有効なレジスタセットを設定せずに使用されました
(これが真になるのは、通常、システムプロセスについてのみです)。
.El
.It Bq Er EBUSY
.Bl -bullet -compact
.It
.Dv PT_ATTACH
が既にトレース中のプロセスについて使用されました。
.It
要求をしているプロセス以外のプロセスによって、トレースされるプロセスを
操作しようとする要求が試みられました。
.It
要求
.Dv ( PT_ATTACH
以外の) が停止されていないプロセスを指定しました。
.El
.It Bq Er EPERM
.Bl -bullet -compact
.It
要求
.Dv ( PT_ATTACH
以外の) が、まったくトレースされていないプロセスを操作しようとしました。
.It
前述の
.Dv PT_ATTACH
で説明した条件を満たさないプロセスについて
.Dv PT_ATTACH
を使おうとしました。
.El
.El
.Sh 関連項目
.Xr execve 2 ,
.Xr sigaction 2 ,
.Xr wait 2 ,
.Xr execv 3 ,
.Xr i386_clr_watch 3 ,
.Xr i386_set_watch 3
.Sh 歴史
.Fn ptrace
関数は
.At v7
で登場しました。