doc/ja_JP.eucJP/man/man2/ptrace.2
Kazuo Horikawa d652d85bad Update to 4.2-20010112-STABLE base and revise Japanese wording.
Submitted by:jpman Project <man-jp@jp.FreeBSD.org>
2001-03-16 23:56:38 +00:00

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
で登場しました。