338 lines
7.9 KiB
Groff
338 lines
7.9 KiB
Groff
.\" %FreeBSD: src/lib/libc/sys/ptrace.2,v 1.10.2.1 1999/08/29 14:49:17 peter Exp %
|
|
.\" %NetBSD: ptrace.2,v 1.2 1995/02/27 12:35:37 cgd Exp %
|
|
.\"
|
|
.\" This file is in the public domain.
|
|
.Dd January 20, 1996
|
|
.Dt PTRACE 2
|
|
.Os FreeBSD
|
|
.Sh 名称
|
|
.Nm ptrace
|
|
.Nd プロセスのトレースとデバッグ
|
|
.Sh ライブラリ
|
|
.Lb libc
|
|
.Sh 書式
|
|
.Fd #include <sys/types.h>
|
|
.Fd #include <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
|
|
(トレース
|
|
されるプロセス)を制御できます。
|
|
ほとんどの場合、トレースされるプロセスは正常に実行されますが、
|
|
シグナルを受信すると
|
|
.Po
|
|
.Xr sigaction 2
|
|
を参照
|
|
.Pc 、
|
|
停止します。トレースのプロセスは、
|
|
.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
|
|
この要求は、トレースされているプロセスが使用する唯一の要求です。
|
|
この要求は、
|
|
プロセスがその親によってトレースされると予想されることを宣言します。
|
|
他の引数はすべて無視され
|
|
ます (親プロセスが子プロセスをトレースすると予想できない場合は、
|
|
それはおそらく結果によって
|
|
混乱されています。トレースされているプロセスが停止すると、このプロセスは、
|
|
.Eo \&
|
|
.Fn ptrace
|
|
.Ec \&
|
|
によってしか継続するようにできません)。プロセスがこの要求を使用し、
|
|
.Xr execve 2
|
|
またはそれに組み込まれているルーチン
|
|
.Po
|
|
たとえば、
|
|
.Xr execv 3
|
|
.Pc
|
|
を呼び出した場合、
|
|
そのプロセスは新しいイメージの最初の指示を実行する前に停止します。
|
|
また、実行中の実行可能モジュールについて
|
|
setuid または setgid ビットは無視されます。
|
|
.It Dv PT_READ_I , Dv PT_READ_D
|
|
これらの要求は、トレースされたプロセスのアドレス空間から 1 つの
|
|
.Li 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_READ_U
|
|
この要求は、トレースされるプロセスのユーザ構造体から 1 つの
|
|
.Li int
|
|
を読み取ります。
|
|
.Fa addr
|
|
引数は、
|
|
ユーザ構造体のベースに相対的に
|
|
int の位置を指定します。この引数は、通常、明示的にまたは
|
|
.Eo \&
|
|
.Fn ptrace
|
|
.Ec
|
|
のプロトタイプの存在のどちらかによって
|
|
.Li caddr_t
|
|
にキャストされる整数値です。
|
|
.Dv PT_READ_I
|
|
および
|
|
.Dv PT_READ_D
|
|
と異なり、
|
|
.Fa addr
|
|
は
|
|
.Li int
|
|
境界に整列されている必要があります。読取られた値は
|
|
.Eo \&
|
|
.Fn ptrace
|
|
.Ec
|
|
からの戻り値として返されます。
|
|
.It Dv PT_WRITE_U
|
|
この要求はトレースされるプロセスのユーザ構造体に 1 つの
|
|
.Li int
|
|
を書き込みます。
|
|
.Fa addr
|
|
は
|
|
.Dv PT_READ_U
|
|
についてとまったく同じようにオフセットを指定し、
|
|
.Fa data
|
|
は
|
|
.Dv PT_WRITE_I
|
|
および
|
|
.Dv PT_WRITE_D
|
|
とまったく同じように書き込まれる値を指定します。
|
|
.It Dv PT_CONTINUE
|
|
トレースされるプロセスは実行を継続します。
|
|
.Fa addr
|
|
は、実行が再開される場所 (プログラムカウンタには新しい値)、
|
|
または実行が停止されたところで再開されることを示す
|
|
.Li (caddr_t)1
|
|
を指定します。
|
|
.Fa data
|
|
は、実行を再開するときにトレースされるプロセスに配信されるシグナル番号、
|
|
またはシグナルが送信されない場合は 0 を提供します。
|
|
.It Dv PT_STEP
|
|
トレースされるプロセスは 1 命令ずつステップ実行されます。
|
|
.Fa addr
|
|
と
|
|
.Fa data
|
|
フィールドは使用されません。
|
|
.It Dv PT_KILL
|
|
トレースされるプロセスは、
|
|
.Dv PT_CONTINUE
|
|
が、配信されるシグナルとして与えられた
|
|
.Dv SIGKILL
|
|
とともに使用されたかのように終了します。
|
|
.It Dv PT_ATTACH
|
|
この要求は、さもなければ無関係のプロセスの制御を取得し、
|
|
それをトレース開始するように
|
|
します。トレースされるプロセスからの協力は必要としません。このケースでは、
|
|
.Fa pid
|
|
がトレースされるプロセスのプロセス ID を指定し、
|
|
他の 2 つの引数は無視されます。
|
|
この要求では、ターゲットプロセスにトレースする
|
|
プロセスと同じリアル UID があること、
|
|
それが setuid または setgid 実行可能モジュールを実行している必要が
|
|
あることが要求されます (トレースしているプロセスがルートとして実行されている
|
|
場合、これらの制約は該当しません)。
|
|
トレースしているプロセスは、新たにトレースされるプロセスが停止させ、
|
|
次に、これがずっとトレースされているかのように制御できます。
|
|
.It Dv PT_DETACH
|
|
この要求は PT_CONTINUE と類似していますが、実行を継続する別の場所を
|
|
指定できないこと、
|
|
およびそれが継続した後、トレースされたプロセスがトレースされなくなり、
|
|
通常どおり実行を継続することが異なります。
|
|
.El
|
|
.Pp
|
|
さらにマシンに固有の要求が存在することがあります。i386
|
|
では、これらは次のとおりです。
|
|
.Bl -tag -width 12n
|
|
.It Dv PT_GETREGS
|
|
この要求は、トレースされたプロセスのマシンレジスタを、
|
|
.Fa addr
|
|
が指す
|
|
.Dq Li "struct reg"
|
|
.Pf ( Aq Pa machine/reg.h
|
|
内に定義されています) 内に読み取ります。
|
|
.It Dv PT_SETREGS
|
|
この要求は
|
|
.Dv PT_GETREGS
|
|
の逆です。
|
|
.Fa addr
|
|
が指す
|
|
.Dq Li "struct reg"
|
|
.Pf ( Aq Pa machine/reg.h
|
|
内に定義されています)
|
|
からトレースされたプロセスのマシンレジスタをロードします。
|
|
.It Dv PT_GETFPREGS
|
|
この要求はトレースされるプロセスの浮動小数点レジスタを
|
|
.Fa addr
|
|
が指す
|
|
.Dq Li "struct fpreg"
|
|
.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
|
|
が指す
|
|
.Dq Li "struct dbreg"
|
|
.Pf ( Aq Pa machine/reg.h
|
|
内に定義されています)
|
|
に読みとります。
|
|
.It Dv PT_SETDBREGS
|
|
この要求は
|
|
.Dv PT_GETDBREGS
|
|
の反対です。
|
|
.Fa addr
|
|
の指す
|
|
.Dq Li "struct dbreg"
|
|
.Pf ( Aq Pa machine/reg.h
|
|
内に定義されています)
|
|
からトレースされたプロセスのデバッグレジスタにロードします。
|
|
.El
|
|
.Sh 戻り値
|
|
要求にはエラーでない値として
|
|
.Li -1
|
|
を
|
|
.Fn ptrace
|
|
に返させるものもあります。
|
|
曖昧さをなくすために、呼び出しの前に
|
|
.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_READ_U
|
|
または
|
|
.Dv PT_WRITE_U
|
|
への
|
|
.Fa addr
|
|
が
|
|
.\".Li int Ns \&-aligned.
|
|
.Li int
|
|
で整列していませんでした。
|
|
.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
|
|
で登場しました。
|