リナックスコマンド

ptraceのヘルプ・マニュアル

日本語 英語

• help
• man

ptrace --help

man ptrace

PTRACE(2) Linux Programmer’s Manual PTRACE(2) 名前 ptrace - プロセスのトレース 書式 #include long ptrace(enum __ptrace_request request, pid_t pid, void *addr, void *data); 説明 ptrace() システムコールは、親プロセスが、別のプロセスの実行の監視/制御 を行ったり、コアイメージ (core image) やレジスタの調査/変更を行ったりす る 手段を提供する。 ptrace() は、主にブレークポイントによるデバッグやシ ステムコールのトレースを実装するのに用いられる。 トレースを開始するには、まず親プロセスで fork(2) を呼び出す。生成された 子 プロセスで PTRACE_TRACEME を行い、続いて (典型的には) exec(3) を行な う。別の方法としては、親プロセスが既存のプロセスに対して PTRACE_ATTACH を使用し、トレースを開始する。 ト レースの実行中、子プロセスはシグナルが配送されるたびに、たとえそのシ グナルが無視すべきものであっても停止する (SIGKILL は例外で、通常どお り の 効果をもたらす)。親プロセスには次の wait(2) で通知され、停止している 間に子プロセスを調べたり修正したりすることができる。そして親プロセス は 子 プロセスの実行を再開させるが、配送されたシグナルを無視することもでき る (あるいは代わりに別のシグナルを配送することもできる) 。 親プロセスがトレースを終了する際には、 PTRACE_KILL を使用して子プロセス を終了させることもできるし、 PTRACE_DETACH を用いて通常のトレースなしの モードにして、実行を継続させることもできる。 request の値がこのシステムコールの動作を決定する: PTRACE_TRACEME このプロセスが親プロセスによってトレースされることを表す。このプ ロセスに (SIGKILL 以外の) シグナルが配送されると、プロセスは停止 し、親プロセスに wait(2) を通じて通知される。また、これ以降は こ のプロセスが execve(2) を呼び出す度に SIGTRAP が送信されるように なる。これによって、親プロセスは新しいプログラムが実行を開始する 前に制御することができる。親プロセスが自プロセスをトレースするつ もりがない場合には、おそらくこのプロセスは本要求を行うべきではな いだろう。 (pid, addr, data は無視される。) 上 記の要求は子プロセスだけが行なうものである。残りは親プロセスだけが行 なうものである。以下の要求では、pid で操作の対象となる子プロセスを指 定 する。 PTRACE_KILL を除き、要求を行なうためには子プロセスは停止していな ければならない。 PTRACE_PEEKTEXT, PTRACE_PEEKDATA 子プロセスのメモリの addr の位置から 1 ワードを読み出す。読み 出 し たワードは ptrace() の返り値として返される。 Linux ではテキス ト (text) とデータ (data) で同じアドレス空間を使用するため、この 2 つの要求は現在のところ同じものである。 (引き数 data は無視され る。) PTRACE_PEEKUSER 子プロセスの USER 領域のオフセット addr の位置から 1 ワードを 読 み込む。USER 領域にはそのプロセスのレジスタ (registers) などの情 報が保持されている ( を参照)。読み込んだ ワ ー ド は ptrace() コールの結果として返される。たいていはオフセットはワー ド境界になければならないが、アーキテクチャによってはその必要はな い。「注意」の節を参照。 (data は無視される。 ) PTRACE_POKETEXT, PTRACE_POKEDATA ワード data を子プロセスのメモリの addr の位置へコピーする。上と 同様に、現在のところ二つの要求は同じものである。 PTRACE_POKEUSER ワード data を子プロセスの USER 領域のオフセット addr の位置にコ ピーする。上と同様に、通常、オフセットはワード境界になければなら ない。カーネルの完全性 (integrity) を維持するため、変更内容に よ っては USER 領域の変更は禁止されている。 PTRACE_GETREGS, PTRACE_GETFPREGS それぞれ、子プロセスの汎用レジスタ、浮動小数点レジスタを親プロセ スの data の位置にコピーする。この data の 書 式 に 関 し て は を参照すること。(addr は無視される。) PTRACE_GETSIGINFO (Linux 2.3.99-pre6 以降) 停 止の原因となったシグナルに関する情報を取得する。 siginfo_t 構 造体 (sigaction(2) 参照) を子プロセスから親プロセスの data の 位 置にコピーする。 (addr は無視される。) PTRACE_SETREGS, PTRACE_SETFPREGS それぞれ、子プロセスの汎用レジスタ、浮動小数点レジスタに親プロセ スの date の位置からコピーする。 PTRACE_POKEUSER と同様に、汎 用 レ ジスタによっては変更が禁止されている場合がある。 (addr は無視 される。) PTRACE_SETSIGINFO (Linux 2.3.99-pre6 以降) シグナル情報を設定する。 siginfo_t 構造体を親プロセスの デ ー タ data の位置から子プロセスにコピーする。この処理を行うことができ るのは、子プロセスに通常は配送されるはずでトレーサに捕捉されたシ グナルについてだけである。これらの通常のシグナルと ptrace() 自身 が発生するシグナルを見分けるのは難しいかもしれない。 (addr は 無 視される。) PTRACE_SETOPTIONS (Linux 2.4.6 以降; バグの章にある警告も参照) 親プロセスの data に基づいて ptrace のオプションを設定する (addr は無視される)。 data はオプションのビットマスクとして解釈され 、 オプションには以下のフラグを指定できる: PTRACE_O_TRACESYSGOOD (Linux 2.4.6 以降) シ ステムコールのトラップが配送されたときに、シグナル番号 のビット 7 を設定する (すなわち、(SIGTRAP | 0x80) を配 送 する)。これにより、トレーサが通常のトラップとシステムコー ルによるトラップを区別しやすくなる。 (PTRACE_O_TRACESYS- GOOD はどのアーキテクチャでも動作しない可能性がある。) PTRACE_O_TRACEFORK (Linux 2.5.46 以降) 次 の fork(2) 呼 び 出 し 時 に SIGTRAP | PTRACE_EVENT_FORK << 8 で子プロセスの動作を停止させ、新た に fork さ れ た プ ロセスのトレースを自動的に開始し、 SIGSTOP でそのプロセスの実行を開始する。新しいプロセス の PID は PTRACE_GETEVENTMSG で取得できる。 PTRACE_O_TRACEVFORK (Linux 2.5.46 以降) 次 の vfork(2) 呼 び 出 し 時 に SIGTRAP | PTRACE_EVENT_VFORK << 8 で子プロセスの動作を停止させ、 新 た に vfork されたプロセスのトレースを自動的に開始し、 SIGSTOP でそのプロセスの実行を開始する。新しいプロセス の PID は PTRACE_GETEVENTMSG で取得できる。 PTRACE_O_TRACECLONE (Linux 2.5.46 以降) 次 の clone(2) 呼 び 出 し 時 に SIGTRAP | PTRACE_EVENT_CLONE << 8 で子プロセスの動作を停止させ、 新 たに clone で作成されたプロセスのトレースを自動的に開始し 、 SIGSTOP でプロセスの実行を開始する。新しいプロセ ス の PID は PTRACE_GETEVENTMSG で取得できる。このオプションで 全ての clone(2) コールを捕まえられるわけではない。子プ ロ セスが CLONE_VFORK フラグ付きで clone(2) を呼び出した場合 、 PTRACE_O_TRACEVFORK が設定され て い れ ば 代 わ り に PTRACE_EVENT_VFORK が配送される。また、子プロセスが終了シ グナルを SIGCHLD に設定して clone(2) を呼び出した場合は、 PTRACE_O_TRACEFORK が設定されていれば PTRACE_EVENT_FORK が配送される。 PTRACE_O_TRACEEXEC (Linux 2.5.46 以降) 次 の execve(2) 呼 び 出 し 時 に SIGTRAP | PTRACE_EVENT_EXEC << 8 で子プロセスの動作を停止させる。 PTRACE_O_TRACEVFORKDONE (Linux 2.5.60 以降) 次 の vfork(2) 呼 び 出 し 時 に SIGTRAP | PTRACE_EVENT_VFORK_DONE << 8 で子プロセスの動作を停止させ る。 PTRACE_O_TRACEEXIT (Linux 2.5.60 以降) 終 了 (exit) 時に SIGTRAP | PTRACE_EVENT_EXIT << 8 で子プ ロセスの動作を停止させる。子プロセスの終了ステー タ ス は PTRACE_GETEVENTMSG で取得できる。この停止はレジスタがまだ 参照可能であるプロセス終了処理の初期に行われ、トレーサ は ど こで終了が発生したかを知ることができる。通常の終了通知 (exit notification) はプロセスの終了処理が完了した後に 行 わ れる。コンテキストを参照することはできるにも関わらず、 トレーサはこの時点から終了を止めることはできない。 PTRACE_GETEVENTMSG (Linux 2.5.46 以降) 発生したばかりの ptrace イベントに関するメッセージ を (unsigned long 型で) 取得する。取得したメッセージは親プロセスの data の位 置に格納される。得られる内容は、 PTRACE_EVENT_EXIT の場合は子 プ ロ セ ス の 終 了 ス テ ー タ ス で あ り 、 PTRACE_EVENT_FORK, PTRACE_EVENT_VFORK, PTRACE_EVENT_CLONE の場合は新しいプロセス の PID で あ る 。 Linux 2.6.18 以降では、新しいプロセスの PID は PTRACE_EVENT_VFORK_DONE で入手できる。 (addr は無視される。) PTRACE_CONT 停止した子プロセスの実行を再開させる。 data が ゼ ロ で な く 、 SIGSTOP でもなければ、子プロセスに配送されるシグナルと解釈される 。ゼロや SIGSTOP の場合はシグナルは配送されない。これを使うと 、 例えば、親プロセスは子プロセスに送られたシグナルを実際に配送する かどうかを制御することができる。(addr は無視される。) PTRACE_SYSCALL, PTRACE_SINGLESTEP PTRACE_CONT と同様に停止した子プロセスを再開す る 。 た だ し 、 PTRACE_SYSCALL の場合は子プロセスが次にシステムコールに入るかシ ステムコールから抜けるかする時に、 PTRACE_SINGLESTEP の場合は 1 命 令 (instruction) 実行した後に停止させる (通常どおり、子プロセ スはシグナルを受け取った場合にも停止する)。親プロセスから見る と 、 子プロセスは SIGTRAP を受信して停止したように見える。そのため 、例えば PTRACE_SYSCALL を使うと、1回目の停止で引き数を 調 べ て PTRACE_SYSCALL を実行し、 2回目の停止でシステムコールの返り値を 調べる、というようなことができる。引き数 data は PTRACE_CONT の 場合と同じ様に解釈される。 (addr は無視される。) PTRACE_SYSEMU, PTRACE_SYSEMU_SINGLESTEP (Linux 2.6.14 以降) PTRACE_SYSEMU は、実行を再開し、次のシステムコールに入る時に停止 させる。システムコールは実行されない。 PTRACE_SYSEMU_SINGLESTEP も 同様だが、システムコールでない場合には 1 命令 (singlestep) だ け実行した時点でも停止させる。このコールは User Mode Linux の よ うに子プロセスのシステムコールを全てエミュレートしようとするプロ グラムで使用される。引き数 data は PTRACE_CONT の場合と同じ様 に 解 釈される。 (addr は無視される。全てのアーキテクチャでサポート されているわけではない。) PTRACE_KILL 子プロセスに SIGKILL を送り終了させる。(addr と data は無視さ れ る。) PTRACE_ATTACH pid で指定されたプロセスに接続 (attach) し、それを呼び出し元のプ ロセスの子プロセスとしてトレースできるようにする。子プロセ ス は PTRACE_TRACEME したかのように振舞う。呼び出し元のプロセスはその ほとんどの目的において、その子プロセスの実際の親になる (例えば、 子 プロセスのイベントの通知を受けとったり、 ps(1) で親として表示 されたりする)。しかし、子プロセスで getppid(2) を実行した場合 に は元の親プロセスの PID が返される。子プロセスには SIGSTOP が送ら れるが、この呼び出しが完了するまでに必ずしも停止するとは限らない 。 子 プ ロセスの停止を待つには wait(2) を使用すること。(addr と data は無視される。) PTRACE_DETACH PTRACE_CONT と同様に停止した子プロセスを再開する。ただしまずその プ ロセスからの分離 (detach) を行い、 PTRACE_ATTACH での親の切り 換えによる効果と PTRACE_TRACEME の効果を取り消す。意図したもので は ないだろうが、 Linux では、トレースされている子プロセスはどの ような方法でトレースを開始されたとしても 、 こ の 方 法 で 分 離 (detach) することができる。 (addr は無視される。) 返り値 成 功すると、 PTRACE_PEEK* の場合は要求したデータを返し、それ以外の場合 は 0 を返す。エラーの場合は -1 を返し、 errno が適切に設 定 さ れ る 。 PTRACE_PEEK* が成功して返す値も -1 になることがあるため、そのような要 求の場合には、呼び出し元は errno を調べ、エラーか発生したのかどうかを判 断しなければならない。 エラー EBUSY (i386 のみ) デバッグレジスタの確保または解放でエラーが発生した。 EFAULT 親プロセスまたは子プロセスのメモリの不正な領域に読み書きしようと した。おそらくその領域がマッピングされていないか、その領域へのア クセスが許されていないかである。不運なことに、Linux ではこのよう な エラーの場合、多かれ少なかれ恣意的に EIO を返したり EFAULT を 返したりすることがある。 EINVAL 不正なオプションを設定しようとした。 EIO request が不正である。または、親プロセスまたは子プロセスのメモリ の不正な領域に読み書きしようとした。または、ワード境界違反があっ た。または、実行再開の要求で不正なシグナルを指定した。 EPERM 指定したプロセスをトレースすることができない。これは親プロセスが 必 要な権限 (必要なケーパビリティは CAP_SYS_PTRACE) を持っていな いことが原因の場合がある。分かりやすい理由を挙げるなら、ルートで な い プロセスはシグナルを送れないプロセスはトレースできないし、 set-user-ID/set-group-ID プログラムを実行しているプロセスはト レ ー ス できない。または、プロセスはすでにトレース中である、または init(8) プロセス (PID が 1) である。 ESRCH 指定したプロセスが存在しない。または、指定したプロセスは呼び出し たプロセスが現在トレース中の子プロセスではない。または、指定した プロセスが停止していない (停止していることが必要な要求の場合)。 準拠 SVr4, 4.3BSD. 注意 ptrace() の引き数は上のようなプロトタイプに基づいて解釈されるが、 glibc では、現在のところ ptrace() は request 引き数だけが固定の可変長引き数関 数として宣言されている。これは必要なければ残りの引き数は省略可能であ る こ とを意味するが、それは gcc(1) の明文化されていない動作を利用している ことになる。 init(8) すなわち PID が 1 のプロセスはトレースすることができない。 メモリや USER 領域の内容や配置は OS ごと、アーキテクチャごとに非常に 依 存する。オフセットが指定された場合、返されるデータは struct user の定義 と完全に一致しないこともありえる。 「ワード (word) 」の大きさは OS によって決まる。 (例えば、32 ビッ ト の Linux では 32 ビットである、など。) ト レースすることによってトレースされるプロセスの動作に些細な違いが起こ ることがある。例えば、プロセスが PTRACE_ATTACH によって接続された場合に は、そのプロセスが停止した時でも本来の親は wait(2) を使って通知を受ける ことができず、新しい親が効率よくこの通知を真似る方法もない。 親プロセスが PTRACE_EVENT_* がセットされたイベントを受信した場合、子 プ ロ セスは通常通りのシグナル配送が行われる状態にない。つまり、親プロセス が、シグナルにより ptrace(PTRACE_CONT) を行ったり、 ptrace(PTRACE_KILL) を 行ったりできないということである。こららのメッセージの受信後は、子プ ロセスを終了 (kill) するのに、シグナル SIGKILL を指定して kill(2) を 行 う方法を代わりに使用できる。 このマニュアルは現在の Linux における ptrace() コールの動作について記述 している。他の Unix ではその動作は著しく異なる。いかなる場合も ptrace() を使うと OS やアーキテクチャに非常に依存したものになる。 SunOS のマニュアル・ページには ptrace() は「独特で不可解」と記述されて おり、まさしくそうである。 Solaris 2 では proc ベースのデバッグのインタ ー フェースとして ptrace() の上位互換関数が実装され、より強力で一貫性の あるものとなっている。 バグ カーネル 2.6 のヘッダがインストールされたホストでは、 PTRACE_SETOPTIONS はカーネル 2.4 のヘッダとは異なる値で宣言される。このため、カーネル 2.6 のヘッダでコンパイルされたアプリケーションはカーネル 2.4 では正しく動作 し な い 。 こ の 問 題 は 、 PTRACE_SETOPTIONS が定義されていた際は、 PTRACE_SETOPTIONS を PTRACE_OLDSETOPTIONS に定義し直すことで対処でき る 。 関連項目 gdb(1), strace(1), execve(2), fork(2), signal(2), wait(2), exec(3), capabilities(7) Linux 2009-03-30 PTRACE(2)

PTRACE(2) Linux Programmer’s Manual PTRACE(2) NAME ptrace - process trace SYNOPSIS #include long ptrace(enum __ptrace_request request, pid_t pid, void *addr, void *data); DESCRIPTION The ptrace() system call provides a means by which a parent process may observe and control the execution of another process, and examine and change its core image and registers. It is primarily used to implement breakpoint debugging and system call tracing. The parent can initiate a trace by calling fork(2) and having the resulting child do a PTRACE_TRACEME, followed (typically) by an exec(3). Alternatively, the parent may commence trace of an existing process using PTRACE_ATTACH. While being traced, the child will stop each time a signal is deliv- ered, even if the signal is being ignored. (The exception is SIGKILL, which has its usual effect.) The parent will be notified at its next wait(2) and may inspect and modify the child process while it is stopped. The parent then causes the child to continue, optionally ignoring the delivered signal (or even delivering a different signal instead). When the parent is finished tracing, it can terminate the child with PTRACE_KILL or cause it to continue executing in a normal, untraced mode via PTRACE_DETACH. The value of request determines the action to be performed: PTRACE_TRACEME Indicates that this process is to be traced by its parent. Any signal (except SIGKILL) delivered to this process will cause it to stop and its parent to be notified via wait(2). Also, all subsequent calls to execve(2) by this process will cause a SIG- TRAP to be sent to it, giving the parent a chance to gain con- trol before the new program begins execution. A process proba- bly shouldn’t make this request if its parent isn’t expecting to trace it. (pid, addr, and data are ignored.) The above request is used only by the child process; the rest are used only by the parent. In the following requests, pid specifies the child process to be acted on. For requests other than PTRACE_KILL, the child process must be stopped. PTRACE_PEEKTEXT, PTRACE_PEEKDATA Reads a word at the location addr in the child’s memory, return- ing the word as the result of the ptrace() call. Linux does not have separate text and data address spaces, so the two requests are currently equivalent. (The argument data is ignored.) PTRACE_PEEKUSER Reads a word at offset addr in the child’s USER area, which holds the registers and other information about the process (see ). The word is returned as the result of the ptrace() call. Typically the offset must be word-aligned, though this might vary by architecture. See NOTES. (data is ignored.) PTRACE_POKETEXT, PTRACE_POKEDATA Copies the word data to location addr in the child’s memory. As above, the two requests are currently equivalent. PTRACE_POKEUSER Copies the word data to offset addr in the child’s USER area. As above, the offset must typically be word-aligned. In order to maintain the integrity of the kernel, some modifications to the USER area are disallowed. PTRACE_GETREGS, PTRACE_GETFPREGS Copies the child’s general purpose or floating-point registers, respectively, to location data in the parent. See for information on the format of this data. (addr is ignored.) PTRACE_GETSIGINFO (since Linux 2.3.99-pre6) Retrieve information about the signal that caused the stop. Copies a siginfo_t structure (see sigaction(2)) from the child to location data in the parent. (addr is ignored.) PTRACE_SETREGS, PTRACE_SETFPREGS Copies the child’s general purpose or floating-point registers, respectively, from location data in the parent. As for PTRACE_POKEUSER, some general purpose register modifications may be disallowed. (addr is ignored.) PTRACE_SETSIGINFO (since Linux 2.3.99-pre6) Set signal information. Copies a siginfo_t structure from loca- tion data in the parent to the child. This will only affect signals that would normally be delivered to the child and were caught by the tracer. It may be difficult to tell these normal signals from synthetic signals generated by ptrace() itself. (addr is ignored.) PTRACE_SETOPTIONS (since Linux 2.4.6; see BUGS for caveats) Sets ptrace options from data in the parent. (addr is ignored.) data is interpreted as a bit mask of options, which are speci- fied by the following flags: PTRACE_O_TRACESYSGOOD (since Linux 2.4.6) When delivering syscall traps, set bit 7 in the signal number (i.e., deliver (SIGTRAP | 0x80) This makes it easy for the tracer to tell the difference between normal traps and those caused by a syscall. (PTRACE_O_TRACESYS- GOOD may not work on all architectures.) PTRACE_O_TRACEFORK (since Linux 2.5.46) Stop the child at the next fork(2) call with SIGTRAP | PTRACE_EVENT_FORK << 8 and automatically start tracing the newly forked process, which will start with a SIGSTOP. The PID for the new process can be retrieved with PTRACE_GETEVENTMSG. PTRACE_O_TRACEVFORK (since Linux 2.5.46) Stop the child at the next vfork(2) call with SIGTRAP | PTRACE_EVENT_VFORK << 8 and automatically start tracing the newly vforked process, which will start with a SIGSTOP. The PID for the new process can be retrieved with PTRACE_GETEVENTMSG. PTRACE_O_TRACECLONE (since Linux 2.5.46) Stop the child at the next clone(2) call with SIGTRAP | PTRACE_EVENT_CLONE << 8 and automatically start tracing the newly cloned process, which will start with a SIGSTOP. The PID for the new process can be retrieved with PTRACE_GETEVENTMSG. This option may not catch clone(2) calls in all cases. If the child calls clone(2) with the CLONE_VFORK flag, PTRACE_EVENT_VFORK will be delivered instead if PTRACE_O_TRACEVFORK is set; other- wise if the child calls clone(2) with the exit signal set to SIGCHLD, PTRACE_EVENT_FORK will be delivered if PTRACE_O_TRACEFORK is set. PTRACE_O_TRACEEXEC (since Linux 2.5.46) Stop the child at the next execve(2) call with SIGTRAP | PTRACE_EVENT_EXEC << 8. PTRACE_O_TRACEVFORKDONE (since Linux 2.5.60) Stop the child at the completion of the next vfork(2) call with SIGTRAP | PTRACE_EVENT_VFORK_DONE << 8. PTRACE_O_TRACEEXIT (since Linux 2.5.60) Stop the child at exit with SIGTRAP | PTRACE_EVENT_EXIT << 8. The child’s exit status can be retrieved with PTRACE_GETEVENTMSG. This stop will be done early during process exit when registers are still available, allowing the tracer to see where the exit occurred, whereas the normal exit notification is done after the process is finished exiting. Even though con- text is available, the tracer cannot prevent the exit from happening at this point. PTRACE_GETEVENTMSG (since Linux 2.5.46) Retrieve a message (as an unsigned long) about the ptrace event that just happened, placing it in the location data in the par- ent. For PTRACE_EVENT_EXIT this is the child’s exit status. For PTRACE_EVENT_FORK, PTRACE_EVENT_VFORK and PTRACE_EVENT_CLONE this is the PID of the new process. Since Linux 2.6.18, the PID of the new process is also available for PTRACE_EVENT_VFORK_DONE. (addr is ignored.) PTRACE_CONT Restarts the stopped child process. If data is non-zero and not SIGSTOP, it is interpreted as a signal to be delivered to the child; otherwise, no signal is delivered. Thus, for example, the parent can control whether a signal sent to the child is delivered or not. (addr is ignored.) PTRACE_SYSCALL, PTRACE_SINGLESTEP Restarts the stopped child as for PTRACE_CONT, but arranges for the child to be stopped at the next entry to or exit from a sys- tem call, or after execution of a single instruction, respec- tively. (The child will also, as usual, be stopped upon receipt of a signal.) From the parent’s perspective, the child will appear to have been stopped by receipt of a SIGTRAP. So, for PTRACE_SYSCALL, for example, the idea is to inspect the argu- ments to the system call at the first stop, then do another PTRACE_SYSCALL and inspect the return value of the system call at the second stop. The data argument is treated as for PTRACE_CONT. (addr is ignored.) PTRACE_SYSEMU, PTRACE_SYSEMU_SINGLESTEP (since Linux 2.6.14) For PTRACE_SYSEMU, continue and stop on entry to the next syscall, which will not be executed. For PTRACE_SYSEMU_SIN- GLESTEP, do the same but also singlestep if not a syscall. This call is used by programs like User Mode Linux that want to emu- late all the child’s system calls. The data argument is treated as for PTRACE_CONT. (addr is ignored; not supported on all architectures.) PTRACE_KILL Sends the child a SIGKILL to terminate it. (addr and data are ignored.) PTRACE_ATTACH Attaches to the process specified in pid, making it a traced "child" of the calling process; the behavior of the child is as if it had done a PTRACE_TRACEME. The calling process actually becomes the parent of the child process for most purposes (e.g., it will receive notification of child events and appears in ps(1) output as the child’s parent), but a getppid(2) by the child will still return the PID of the original parent. The child is sent a SIGSTOP, but will not necessarily have stopped by the completion of this call; use wait(2) to wait for the child to stop. (addr and data are ignored.) PTRACE_DETACH Restarts the stopped child as for PTRACE_CONT, but first detaches from the process, undoing the reparenting effect of PTRACE_ATTACH, and the effects of PTRACE_TRACEME. Although per- haps not intended, under Linux a traced child can be detached in this way regardless of which method was used to initiate trac- ing. (addr is ignored.) RETURN VALUE On success, PTRACE_PEEK* requests return the requested data, while other requests return zero. On error, all requests return -1, and errno is set appropriately. Since the value returned by a successful PTRACE_PEEK* request may be -1, the caller must check errno after such requests to determine whether or not an error occurred. ERRORS EBUSY (i386 only) There was an error with allocating or freeing a debug register. EFAULT There was an attempt to read from or write to an invalid area in the parent’s or child’s memory, probably because the area wasn’t mapped or accessible. Unfortunately, under Linux, different variations of this fault will return EIO or EFAULT more or less arbitrarily. EINVAL An attempt was made to set an invalid option. EIO request is invalid, or an attempt was made to read from or write to an invalid area in the parent’s or child’s memory, or there was a word-alignment violation, or an invalid signal was speci- fied during a restart request. EPERM The specified process cannot be traced. This could be because the parent has insufficient privileges (the required capability is CAP_SYS_PTRACE); non-root processes cannot trace processes that they cannot send signals to or those running set-user- ID/set-group-ID programs, for obvious reasons. Alternatively, the process may already be being traced, or be init(8) (PID 1). ESRCH The specified process does not exist, or is not currently being traced by the caller, or is not stopped (for requests that require that). CONFORMING TO SVr4, 4.3BSD. NOTES Although arguments to ptrace() are interpreted according to the proto- type given, glibc currently declares ptrace() as a variadic function with only the request argument fixed. This means that unneeded trail- ing arguments may be omitted, though doing so makes use of undocumented gcc(1) behavior. init(8), the process with PID 1, may not be traced. The layout of the contents of memory and the USER area are quite OS- and architecture-specific. The offset supplied, and the data returned, might not entirely match with the definition of struct user. The size of a "word" is determined by the OS variant (e.g., for 32-bit Linux it is 32 bits, etc.). Tracing causes a few subtle differences in the semantics of traced pro- cesses. For example, if a process is attached to with PTRACE_ATTACH, its original parent can no longer receive notification via wait(2) when it stops, and there is no way for the new parent to effectively simu- late this notification. When the parent receives an event with PTRACE_EVENT_* set, the child is not in the normal signal delivery path. This means the parent cannot do ptrace(PTRACE_CONT) with a signal or ptrace(PTRACE_KILL). kill(2) with a SIGKILL signal can be used instead to kill the child process after receiving one of these messages. This page documents the way the ptrace() call works currently in Linux. Its behavior differs noticeably on other flavors of Unix. In any case, use of ptrace() is highly OS- and architecture-specific. The SunOS man page describes ptrace() as "unique and arcane", which it is. The proc-based debugging interface present in Solaris 2 implements a superset of ptrace() functionality in a more powerful and uniform way. BUGS On hosts with 2.6 kernel headers, PTRACE_SETOPTIONS is declared with a different value than the one for 2.4. This leads to applications com- piled with such headers failing when run on 2.4 kernels. This can be worked around by redefining PTRACE_SETOPTIONS to PTRACE_OLDSETOPTIONS, if that is defined. SEE ALSO gdb(1), strace(1), execve(2), fork(2), signal(2), wait(2), exec(3), capabilities(7) COLOPHON This page is part of release 3.22 of the Linux man-pages project. A description of the project, and information about reporting bugs, can be found at http://www.kernel.org/doc/man-pages/. Linux 2009-03-30 PTRACE(2)