Android Hook学习之ptrace函数的使用

Synopsis

#include <sys/ptrace.h>

long ptrace(enum __ptrace_request request, pid_t pid, void *addr, void*data);

Description

The ptrace() system call provides a means bywhich one process (the "tracer") may observe and control theexecution of another process (the "tracee"), and examine and changethe tracee'smemory andregisters. It is primarily used toimplement breakpoint debugging and system call tracing.

A tracee first needs to be attachedto the tracer. Attachment and subsequent commands are per thread: in amultithreaded process, every thread can be individually attached to a(potentially different) tracer, or left not attached and thus not debugged.Therefore, "tracee" always means "(one) thread", never "a (possibly multithreaded) process". Ptrace commands  are alwayssent to a specific tracee using a call of the form

ptrace(PTRACE_foo, pid, ...)

where pid is the thread ID of the corresponding Linux thread.

(Note that in this page, a "multithreaded process" means athread group consisting of threads created using the clone(2)CLONE_THREAD flag.)

A process can initiate a trace by calling fork(2) andhaving the resulting child do a PTRACE_TRACEME, followed(typically) by an execve(2). Alternatively, oneprocess may commence tracing another process using PTRACE_ATTACH orPTRACE_SEIZE.

While being traced, the tracee will stop each time a signal is delivered,even if the signal is being ignored. (An exception isSIGKILL, which hasits usual effect.) The tracer will be notified at its next call to waitpid(2) (orone of the related "wait" system calls); that call will returna status value containing information that indicates the causeof the stop in the tracee. While the tracee is stopped, the tracer can usevarious ptrace requests to inspect and modify the tracee. The tracer thencauses the tracee to continue, optionally ignoring the delivered signal (oreven delivering a different signal instead).

If the PTRACE_O_TRACEEXEC option is not in effect, allsuccessful calls to execve(2) by the tracedprocess will cause it to be sent a SIGTRAP signal, giving theparent a chance to gain control before the new program begins execution.

When the tracer is finished tracing, it can cause the tracee to continueexecuting in a normal, untraced mode viaPTRACE_DETACH.

The value of request determinesthe action to be performed:

PTRACE_TRACEME

Indicate that thisprocess is to be traced by its parent. A process probably shouldn't make thisrequest if its parent isn't expecting to trace it. (pid, addr,and data are ignored.)

The PTRACE_TRACEME request is used only by the tracee;the remaining requests are used only by the tracer. In the followingrequests, pid specifies the thread ID of the tracee to be actedon. For requests other than PTRACE_ATTACH,PTRACE_SEIZE, PTRACE_INTERRUPT and PTRACE_KILL,the tracee must be stopped.

PTRACE_PEEKTEXT, PTRACE_PEEKDATA

Read a word at theaddress addr in the tracee's memory, returning the word as theresult of the ptrace() call. Linux does not have separate text anddata address spaces, so these two requests are currently equivalent. (data isignored.)

 

PTRACE_PEEKUSER

Read a word atoffset addr in the tracee's USER area, which holds theregisters and other information about the process (see <sys/user.h>).The word is returned as the result of the ptrace() call. Typically,the offset must be word-aligned, though this might vary by architecture. SeeNOTES. (data is ignored.)

 

PTRACE_POKETEXT, PTRACE_POKEDATA

Copy the word data tothe address addr in the tracee's memory. As for PTRACE_PEEKTEXT andPTRACE_PEEKDATA,these two requests are currently equivalent.

 

PTRACE_POKEUSER

Copy the word data tooffset addr in the tracee's USER area. As for PTRACE_PEEKUSER,the offset must typically be word-aligned. In order to maintain the integrityof the kernel, some modifications to the USER area are disallowed.

 

PTRACE_GETREGS, PTRACE_GETFPREGS

Copy the tracee'sgeneral-purpose or floating-point registers, respectively, to the address data inthe tracer. See<sys/user.h> for information on theformat of this data. (addr is ignored.) Note that SPARC systemshave the meaning ofdata and addr reversed; thatis, data is ignored and the registers are copied to theaddress addr. PTRACE_GETREGSand PTRACE_GETFPREGS arenot present on all architectures.

 

PTRACE_GETREGSET (since Linux 2.6.34)

Read the tracee'sregisters. addr specifies, in an architecture-dependent way,the type of registers to be read.NT_PRSTATUS (with numerical value1) usually results in reading of general-purpose registers. If the CPU has, forexample, floating-point and/or vector registers, they can be retrieved bysetting addr to the corresponding NT_fooconstant. data pointsto a struct iovec, which describes the destination buffer'slocation and length. On return, the kernel modifies iov.len toindicate the actual number of bytes returned.

 

PTRACE_GETSIGINFO (since Linux 2.3.99-pre6)

Retrieve informationabout the signal that caused the stop. Copy a siginfo_t structure(see sigaction(2)) from the traceeto the address data in the tracer. (addr isignored.)

 

PTRACE_SETREGS, PTRACE_SETFPREGS

Modify the tracee'sgeneral-purpose or floating-point registers, respectively, from theaddress data in the tracer. As forPTRACE_POKEUSER, somegeneral-purpose register modifications may be disallowed. (addr isignored.) Note that SPARC systems have the meaning of data and addr reversed;that is, data is ignored and the registers are copied from theaddress addr. PTRACE_SETREGS and PTRACE_SETFPREGS arenot present on all architectures.

 

PTRACE_SETREGSET (since Linux 2.6.34)

Modify the tracee'sregisters. The meaning of addr and data isanalogous to PTRACE_GETREGSET.

 

PTRACE_SETSIGINFO (since Linux 2.3.99-pre6)

Set signalinformation: copy a siginfo_t structure from the address data inthe tracer to the tracee. This will affect only signals that would normally bedelivered to the tracee and were caught by the tracer. It may be difficult totell these normal signals from synthetic signals generated by ptrace()itself. (addr is ignored.)

 

PTRACE_SETOPTIONS (since Linux 2.4.6; see BUGS forcaveats)

Set ptrace optionsfrom data. (addr is ignored.) data isinterpreted as a bit mask of options。

 

PTRACE_O_EXITKILL (since Linux 3.8)

If a tracer sets thisflag, a SIGKILL signal will be sent to every tracee if the tracerexits. This option is useful for ptrace jailers that want to ensure thattracees can never escape the tracer's control.

 

PTRACE_O_TRACECLONE (since Linux 2.5.46)

Stop the tracee atthe next clone(2) and automaticallystart tracing the newly cloned process, which will start with aSIGSTOP.A waitpid(2)

by the tracer will return a status value such that

status>>8 == (SIGTRAP | (PTRACE_EVENT_CLONE<<8))

The PID of the newprocess can be retrieved with PTRACE_GETEVENTMSG.

This option may not catch

clone(2) calls in all cases. If the tracee calls clone(2) withthe CLONE_VFORK flag, PTRACE_EVENT_VFORK willbe delivered instead if PTRACE_O_TRACEVFORK is set; otherwiseif the tracee calls clone(2) with the exitsignal set toSIGCHLD, PTRACE_EVENT_FORK will bedelivered if PTRACE_O_TRACEFORK is set.

 

PTRACE_O_TRACEEXEC (since Linux 2.5.46)

Stop the tracee atthe next execve(2). A waitpid(2) bythe tracer will return a status

value such that

status>>8 == (SIGTRAP | (PTRACE_EVENT_EXEC<<8))

If the execing threadis not a thread group leader, the thread ID is reset to thread group leader'sID before this stop. Since Linux 3.0, the former thread ID can be retrievedwith PTRACE_GETEVENTMSG.

 

PTRACE_O_TRACEEXIT (since Linux 2.5.60)

Stop the tracee atexit. A waitpid(2) by the tracerwill return

a status value such that

status>>8 == (SIGTRAP | (PTRACE_EVENT_EXIT<<8))

The tracee's exit statuscan be retrieved with PTRACE_GETEVENTMSG.

The tracee is stopped early during process exit,

when registers arestill available, allowing the tracer to see where the exit occurred, whereasthe normal exit notification is done after the process is finished exiting.Even though context is available, the tracer cannot prevent the exit fromhappening at this point.

 

PTRACE_O_TRACEFORK (since Linux 2.5.46)

Stop the tracee atthe next fork(2) and automaticallystart tracing the newly forked process, which will start with aSIGSTOP.A waitpid(2) by the tracerwill return

a status value such that

status>>8 == (SIGTRAP | (PTRACE_EVENT_FORK<<8))

The PID of the newprocess can be retrieved with PTRACE_GETEVENTMSG.

 

PTRACE_O_TRACESYSGOOD (since Linux 2.4.6)

When deliveringsystem call traps, set bit 7 in the signal number (i.e., deliver SIGTRAP|0x80).This makes it easy for the tracer to distinguish normal traps from those causedby a system call. (PTRACE_O_TRACESYSGOOD may not work on allarchitectures.)

 

PTRACE_O_TRACEVFORK (since Linux 2.5.46)

Stop the tracee atthe next vfork(2) and automaticallystart tracing the newly vforked process, which will start with aSIGSTOP.A waitpid(2) by

the tracer will return a status value such that

status>>8 == (SIGTRAP | (PTRACE_EVENT_VFORK<<8))

The PID of the newprocess can be retrieved with PTRACE_GETEVENTMSG.

 

PTRACE_O_TRACEVFORKDONE (since Linux 2.5.60)

Stop the tracee atthe completion of the next vfork(2). A waitpid(2) bythe tracer will return a status value such that

status>>8 == (SIGTRAP | (PTRACE_EVENT_VFORK_DONE<<8))

The PID of the newprocess can (since Linux 2.6.18) be retrieved with PTRACE_GETEVENTMSG.

 

PTRACE_GETEVENTMSG (since Linux 2.5.46)

Retrieve a message(as an unsigned long) about the ptrace event that just happened,placing it at the address data in the tracer. For PTRACE_EVENT_EXIT,this is the tracee's exit status. For PTRACE_EVENT_FORK,PTRACE_EVENT_VFORK, PTRACE_EVENT_VFORK_DONE,and PTRACE_EVENT_CLONE, this is the PID of the new process. (addr isignored.)

 

PTRACE_CONT

Restart the stoppedtracee process. If data is nonzero, it is interpreted as thenumber of a signal to be delivered to the tracee; otherwise, no signal isdelivered. Thus, for example, the tracer can control whether a signal sent tothe tracee is delivered or not. (addr is ignored.)

 

PTRACE_SYSCALL, PTRACE_SINGLESTEP

Restart the stoppedtracee as for PTRACE_CONT, but arrange for the tracee to be stoppedat the next entry to or exit from a system call, or after execution of a singleinstruction, respectively. (The tracee will also, as usual, be stopped uponreceipt of a signal.) From the tracer's perspective, the tracee will appear tohave been stopped by receipt of a SIGTRAP. So, for PTRACE_SYSCALL,for example, the idea is to inspect the arguments to the system call at thefirst stop, then do another PTRACE_SYSCALL and inspect thereturn value of the system call at the second stop. The data argumentis treated as for PTRACE_CONT. (addr is ignored.)

 

PTRACE_SYSEMU, PTRACE_SYSEMU_SINGLESTEP (sinceLinux 2.6.14)

For PTRACE_SYSEMU,continue and stop on entry to the next system call, which will not be executed.ForPTRACE_SYSEMU_SINGLESTEP, do the same but also singlestep if not asystem call. This call is used by programs like User Mode Linux that want toemulate all the tracee's system calls. The data argument istreated as forPTRACE_CONT. The addr argument isignored. These requests are currently supported only on x86.

 

PTRACE_LISTEN (since Linux 3.4)

Restart the stoppedtracee, but prevent it from executing. The resulting state of the tracee issimilar to a process which has been stopped by a SIGSTOP (orother stopping signal). See the "group-stop" subsection foradditional information.PTRACE_LISTEN only works on tracees attachedby PTRACE_SEIZE.

 

PTRACE_KILL

Send the traceea SIGKILL to terminate it. (addr and data areignored.)

This operation is deprecated; do not use it!

Instead, send a SIGKILL directlyusing kill(2) or tgkill(2).The problem with PTRACE_KILL is that it requires the tracee tobe in signal-delivery-stop, otherwise it may not work (i.e., may completesuccessfully but won't kill the tracee). By contrast, sending a SIGKILL directlyhas no such limitation.

 

PTRACE_INTERRUPT (since Linux 3.4)

Stop a tracee. If thetracee is running, it will stop with PTRACE_EVENT_STOP. If thetracee is already stopped by a signal, or receives a signal in parallelwith PTRACE_INTERRUPT, it may report a group-stop or asignal-delivery-stop instead of PTRACE_EVENT_STOP. PTRACE_INTERRUPT onlyworks on tracees attached by PTRACE_SEIZE.

 

PTRACE_ATTACH

Attach to the processspecified in pid, making it a tracee of the calling process. The traceeis sent a SIGSTOP, but will not necessarily have stopped by thecompletion of this call; use waitpid(2) towait for the tracee to stop. See the "Attaching and detaching"subsection for additional information. (addr and data areignored.)

 

PTRACE_SEIZE (since Linux 3.4)

Attach to the processspecified in pid, making it a tracee of the calling process.Unlike PTRACE_ATTACH,PTRACE_SEIZE does not stop theprocess. Only a PTRACE_SEIZEd process can accept PTRACE_INTERRUPT andPTRACE_LISTEN commands. addr mustbe zero. data contains a bit mask of ptrace options toactivate immediately.

 

PTRACE_DETACH

Restart the stoppedtracee as for PTRACE_CONT, but first detach from it. Under Linux, atracee can be detached in this way regardless of which method was used toinitiate tracing. (addr is ignored.)

Death under ptrace

When a (possibly multithreaded) process receives akilling signal (one whose disposition is set to SIG_DFL andwhose default action is to kill the process), all threads exit. Tracees reporttheir death to their tracer(s). Notification of this event isdelivered via waitpid(2).

Note that the killing signal will first cause signal-delivery-stop (on onetracee only), and only after it is injected by the tracer (or after it wasdispatched to a thread which isn't traced), will death from the signal happenon all tracees within a multithreaded process. (The term"signal-delivery-stop" is explained below.)

SIGKILL does not generate signal-delivery-stopand therefore the tracer can't suppress it. SIGKILL kills evenwithin system calls (syscall-exit-stop is not generated prior to death by SIGKILL).The net effect is that SIGKILL always kills the process (allits threads), even if some threads of the process are ptraced.

When the tracee calls _exit(2), it reports its death to itstracer. Other threads are not affected.

When any thread executes exit_group(2),every tracee in its thread group reports its death to its tracer.

If the PTRACE_O_TRACEEXIT option is on, PTRACE_EVENT_EXIT willhappen before actual death. This applies to exits via exit(2), exit_group(2),and signal deaths (except SIGKILL), and when threads are torn downon execve(2) in amultithreaded process.

The tracer cannot assume that the ptrace-stopped tracee exists. There aremany scenarios when the tracee may die while stopped (such as SIGKILL).Therefore, the tracer must be prepared to handle an ESRCH erroron any ptrace operation. Unfortunately, the same error is returned if thetracee exists but is not ptrace-stopped (for commands which require a stoppedtracee), or if it is not traced by the process which issued the ptrace call.The tracer needs to keep track of the stopped/running state of the tracee, andinterpret ESRCH as "tracee died unexpectedly" onlyif it knows that the tracee has been observed to enter ptrace-stop. Note thatthere is no guarantee that waitpid(WNOHANG) will reliablyreport the tracee's death status if a ptrace operation returned ESRCH. waitpid(WNOHANG) mayreturn 0 instead. In other words, the tracee may be "not yet fullydead", but already refusing ptrace requests.

The tracer can't assume that the tracee always ends itslife by reporting WIFEXITED(status) or WIFSIGNALED(status);there are cases where this does not occur. For example, if a thread other thanthread group leader does an execve(2),it disappears; its PID will never be seen again, and any subsequent ptracestops will be reported under the thread group leader's PID.

Stopped states

A tracee can be in two states: running or stopped.

There are many kinds of states when the tracee is stopped, and in ptracediscussions they are often conflated. Therefore, it is important to use preciseterms.

In this manual page, any stopped state in which the tracee is ready toaccept ptrace commands from the tracer is called ptrace-stop.Ptrace-stops can be further subdivided into signal-delivery-stop, group-stop, syscall-stop,and so on. These stopped states are described in detail below.

When the running tracee enters ptrace-stop, it notifies its tracerusing waitpid(2) (or one of theother "wait" system calls). Most of this manual page assumes that thetracer waits with:

pid = waitpid(pid_or_minus_1, &status, __WALL);

Ptrace-stopped tracees are reported as returns with pid greaterthan 0 and WIFSTOPPED(status) true.

The __WALL flag does not include the WSTOPPED and WEXITED flags,but implies their functionality.

Setting the WCONTINUED flag when calling waitpid(2) isnot recommended: the "continued" state is per-process and consumingit can confuse the real parent of the tracee.

Use of the WNOHANG flag may cause waitpid(2) toreturn 0 ("no wait results available yet") even if the tracer knowsthere should be a notification. Example:

errno = 0;

ptrace(PTRACE_CONT, pid, 0L, 0L);

if (errno == ESRCH) {

    /* tracee is dead */

    r = waitpid(tracee, &status,__WALL | WNOHANG);

    /* r can still be 0 here! */

}

The following kinds of ptrace-stops exist:signal-delivery-stops, group-stops, PTRACE_EVENT stops,syscall-stops. They all are reported by waitpid(2) with WIFSTOPPED(status) true.They may be differentiated by examining the value status>>8,and if there is ambiguity in that value, by querying PTRACE_GETSIGINFO.(Note: the WSTOPSIG(status) macro can't be used to performthis examination, because it returns the value (status>>8) &0xff.)

Signal-delivery-stop

When a (possibly multithreaded) process receives anysignal except SIGKILL, the kernel selects an arbitrary thread whichhandles the signal. (If the signal is generated with tgkill(2),the target thread can be explicitly selected by the caller.) If the selectedthread is traced, it enters signal-delivery-stop. At this point, the signal isnot yet delivered to the process, and can be suppressed by the tracer. If thetracer doesn't suppress the signal, it passes the signal to the tracee in thenext ptrace restart request. This second step of signal delivery iscalled signal injection in this manual page. Note that if thesignal is blocked, signal-delivery-stop doesn't happen until the signal isunblocked, with the usual exception that SIGSTOP can't beblocked.

Signal-delivery-stop is observed by the tracer as waitpid(2) returningwith WIFSTOPPED(status) true, with the signal returnedby WSTOPSIG(status). If the signal is SIGTRAP, this maybe a different kind of ptrace-stop; see the "Syscall-stops" and"execve" sections below for details. If WSTOPSIG(status) returnsa stopping signal, this may be a group-stop; see below.

Signal injection and suppression

After signal-delivery-stop is observed by the tracer, thetracer should restart the tracee with the call

ptrace(PTRACE_restart, pid, 0, sig)

where PTRACE_restart is one of the restarting ptracerequests. If sig is 0, then a signal is not delivered.Otherwise, the signalsig is delivered. This operation iscalled signal injection in this manual page, to distinguish itfrom signal-delivery-stop.

The sig value may be different from the WSTOPSIG(status) value:the tracer can cause a different signal to be injected.

Note that a suppressed signal still causes system calls to returnprematurely. In this case system calls will be restarted: the tracer will observethe tracee to reexecute the interrupted system call (or restart_syscall(2) systemcall for a few syscalls which use a different mechanism for restarting) if thetracer uses PTRACE_SYSCALL. Even system calls (such as poll(2))which are not restartable after signal are restarted after signal issuppressed; however, kernel bugs exist which cause some syscalls to failwith EINTR even though no observable signal is injected to thetracee.

Restarting ptrace commands issued in ptrace-stops other thansignal-delivery-stop are not guaranteed to inject a signal, even ifsig isnonzero. No error is reported; a nonzero sig may simply beignored. Ptrace users should not try to "create a new signal" thisway: use tgkill(2) instead.

The fact that signal injection requests may be ignored when restarting thetracee after ptrace stops that are not signal-delivery-stops is a cause ofconfusion among ptrace users. One typical scenario is that the tracer observesgroup-stop, mistakes it for signal-delivery-stop, restarts the tracee with

ptrace(PTRACE_restart, pid, 0, stopsig)

with the intention of injecting stopsig, but stopsig getsignored and the tracee continues to run.

The SIGCONT signal has a side effect of waking up (allthreads of) a group-stopped process. This side effect happens beforesignal-delivery-stop. The tracer can't suppress this side effect (it can onlysuppress signal injection, which only causes theSIGCONT handler tonot be executed in the tracee, if such a handler is installed). In fact, wakingup from group-stop may be followed by signal-delivery-stop for signal(s) other than SIGCONT,if they were pending when SIGCONT was delivered. In otherwords, SIGCONT may be not the first signal observed by thetracee after it was sent.

Stopping signals cause (all threads of) a process to enter group-stop.This side effect happens after signal injection, and therefore can besuppressed by the tracer.

In Linux 2.4 and earlier, the SIGSTOP signal can't beinjected.

PTRACE_GETSIGINFO can be used to retrieve a siginfo_t structurewhich corresponds to the delivered signal.PTRACE_SETSIGINFO may beused to modify it. If PTRACE_SETSIGINFO has been used toalter siginfo_t, the si_signofield and the sig parameterin the restarting command must match, otherwise the result is undefined.

Group-stop

When a (possibly multithreaded) process receives astopping signal, all threads stop. If some threads are traced, they enter agroup-stop. Note that the stopping signal will first cause signal-delivery-stop(on one tracee only), and only after it is injected by the tracer (or after itwas dispatched to a thread which isn't traced), will group-stop be initiatedon all tracees within the multithreaded process. As usual,every tracee reports its group-stop separately to the corresponding tracer.

Group-stop is observed by the tracer as waitpid(2) returningwith WIFSTOPPED(status) true, with the stopping signalavailable via WSTOPSIG(status). The same result is returned by someother classes of ptrace-stops, therefore the recommended practice is to performthe call

ptrace(PTRACE_GETSIGINFO, pid, 0, &siginfo)

The call can be avoided if the signal is not SIGSTOP, SIGTSTP, SIGTTIN,or SIGTTOU; only these four signals are stopping signals. If thetracer sees something else, it can't be a group-stop. Otherwise, the tracerneeds to call PTRACE_GETSIGINFO. If PTRACE_GETSIGINFO failswith EINVAL, then it is definitely a group-stop. (Other failurecodes are possible, such asESRCH ("no such process") ifa SIGKILL killed the tracee.)

As of Linux 2.6.38, after the tracer sees the tracee ptrace-stop and untilit restarts or kills it, the tracee will not run, and will not sendnotifications (except SIGKILL death) to the tracer, even ifthe tracer enters into another waitpid(2) call.

The kernel behavior described in the previous paragraph causes a problemwith transparent handling of stopping signals. If the tracer restarts thetracee after group-stop, the stopping signal is effectively ignored--the traceedoesn't remain stopped, it runs. If the tracer doesn't restart the traceebefore entering into the next waitpid(2),future SIGCONT signals will not be reported to the tracer;this would cause the SIGCONT signals to have no effect on thetracee.

Since Linux 3.4, there is a method to overcome this problem: insteadof PTRACE_CONT, a PTRACE_LISTEN command can beused to restart a tracee in a way where it does not execute, but waits for anew event which it can report via waitpid(2) (suchas when it is restarted by a SIGCONT).

PTRACE_EVENT stops

If the tracer sets PTRACE_O_TRACE_* options,the tracee will enter ptrace-stops called PTRACE_EVENT stops.

PTRACE_EVENT stops are observed by the traceras waitpid(2) returningwith WIFSTOPPED(status), andWSTOPSIG(status) returns SIGTRAP.An additional bit is set in the higher byte of the status word: the value status>>8 willbe

(SIGTRAP | PTRACE_EVENT_foo << 8).

The following events exist:

PTRACE_EVENT_VFORK

Stop before returnfrom vfork(2) or clone(2) withthe CLONE_VFORK flag. When the tracee is continued after thisstop, it will wait for child to exit/exec before continuing its execution (inother words, the usual behavior on vfork(2)).

PTRACE_EVENT_FORK

Stop before returnfrom fork(2) or clone(2) withthe exit signal set to SIGCHLD.

PTRACE_EVENT_CLONE

Stop before returnfrom clone(2).

PTRACE_EVENT_VFORK_DONE

Stop before returnfrom vfork(2) or clone(2) withthe CLONE_VFORK flag, but after the child unblocked thistracee by exiting or execing.

For all four stops described above, the stop occurs in the parent (i.e.,the tracee), not in the newly created thread.PTRACE_GETEVENTMSG canbe used to retrieve the new thread's ID.

PTRACE_EVENT_EXEC

Stop before returnfrom execve(2). Since Linux3.0, PTRACE_GETEVENTMSG returns the former thread ID.

PTRACE_EVENT_EXIT

Stop before exit(including death from exit_group(2)), signal death,or exit caused by execve(2) in amultithreaded process. PTRACE_GETEVENTMSG returns the exitstatus. Registers can be examined (unlike when "real" exit happens).The tracee is still alive; it needs to be PTRACE_CONTed or PTRACE_DETACHedto finish exiting.

PTRACE_EVENT_STOP

Stop induced by PTRACE_INTERRUPT command.

PTRACE_GETSIGINFO on PTRACE_EVENT stopsreturns SIGTRAP in si_signo, with si_code setto (event<<8) | SIGTRAP.

Syscall-stops

If the tracee was restarted by PTRACE_SYSCALL,the tracee enters syscall-enter-stop just prior to entering any system call. Ifthe tracer restarts the tracee with PTRACE_SYSCALL, the traceeenters syscall-exit-stop when the system call is finished, or if it isinterrupted by a signal. (That is, signal-delivery-stop never happens betweensyscall-enter-stop and syscall-exit-stop; it happens after syscall-exit-stop.)

Other possibilities are that the tracee may stop in a PTRACE_EVENT stop,exit (if it entered _exit(2) or exit_group(2)),be killed by SIGKILL, or die silently (if it is a thread groupleader, the execve(2) happened inanother thread, and that thread is not traced by the same tracer; this situationis discussed later).

Syscall-enter-stop and syscall-exit-stop are observed by the traceras waitpid(2) returningwith WIFSTOPPED(status) true, andWSTOPSIG(status) giving SIGTRAP.If the PTRACE_O_TRACESYSGOOD option was set by the tracer,thenWSTOPSIG(status) will give the value (SIGTRAP | 0x80).

Syscall-stops can be distinguished from signal-delivery-stop with SIGTRAP byquerying PTRACE_GETSIGINFO for the following cases:

si_code <= 0

SIGTRAP was delivered as a result of a user-space action, for example, asystem call (tgkill(2), kill(2), sigqueue(3),etc.), expiration of a POSIX timer, change of state on a POSIX message queue,or completion of an asynchronous I/O request.

si_code == SI_KERNEL (0x80)

SIGTRAP was sent by the kernel.

si_code == SIGTRAP or si_code ==(SIGTRAP|0x80)

This is asyscall-stop.

However, syscall-stops happen very often (twice per system call), andperforming PTRACE_GETSIGINFO for every syscall-stop may besomewhat expensive.

Some architectures allow the cases to be distinguished by examiningregisters. For example, on x86, rax == -ENOSYS insyscall-enter-stop. Since SIGTRAP (like any other signal)always happens after syscall-exit-stop, and at thispoint rax almost never contains -ENOSYS, the SIGTRAP lookslike "syscall-stop which is not syscall-enter-stop"; in other words,it looks like a "stray syscall-exit-stop" and can be detected thisway. But such detection is fragile and is best avoided.

Using the PTRACE_O_TRACESYSGOOD option is the recommendedmethod to distinguish syscall-stops from other kinds of ptrace-stops, since itis reliable and does not incur a performance penalty.

Syscall-enter-stop and syscall-exit-stop are indistinguishable from eachother by the tracer. The tracer needs to keep track of the sequence ofptrace-stops in order to not misinterpret syscall-enter-stop as syscall-exit-stopor vice versa. The rule is that syscall-enter-stop is always followed bysyscall-exit-stop, PTRACE_EVENT stop or the tracee's death; noother kinds of ptrace-stop can occur in between.

If after syscall-enter-stop, the tracer uses a restarting command otherthan PTRACE_SYSCALL, syscall-exit-stop is not generated.

PTRACE_GETSIGINFO on syscall-stops returns SIGTRAP in si_signo,with si_code set to SIGTRAP or (SIGTRAP|0x80).

PTRACE_SINGLESTEP, PTRACE_SYSEMU, PTRACE_SYSEMU_SINGLESTEP stops

[Details of these kinds of stops are yet to bedocumented.]

Informational and restarting ptrace commands

Most ptrace commands (all except PTRACE_ATTACH, PTRACE_SEIZE, PTRACE_TRACEME, PTRACE_INTERRUPT,and PTRACE_KILL) require the tracee to be in a ptrace-stop,otherwise they fail with ESRCH.

When the tracee is in ptrace-stop, the tracer can read and write data tothe tracee using informational commands. These commands leave the tracee inptrace-stopped state:

ptrace(PTRACE_PEEKTEXT/PEEKDATA/PEEKUSER, pid, addr, 0);

ptrace(PTRACE_POKETEXT/POKEDATA/POKEUSER, pid, addr, long_val);

ptrace(PTRACE_GETREGS/GETFPREGS, pid, 0, &struct);

ptrace(PTRACE_SETREGS/SETFPREGS, pid, 0, &struct);

ptrace(PTRACE_GETREGSET, pid, NT_foo, &iov);

ptrace(PTRACE_SETREGSET, pid, NT_foo, &iov);

ptrace(PTRACE_GETSIGINFO, pid, 0, &siginfo);

ptrace(PTRACE_SETSIGINFO, pid, 0, &siginfo);

ptrace(PTRACE_GETEVENTMSG, pid, 0, &long_var);

ptrace(PTRACE_SETOPTIONS, pid, 0, PTRACE_O_flags);

 

Note that some errors are not reported. For example,setting signal information (siginfo) may have no effect in someptrace-stops, yet the call may succeed (return 0 and not set errno);querying PTRACE_GETEVENTMSG may succeed and return some randomvalue if current ptrace-stop is not documented as returning a meaningful eventmessage.

The call

ptrace(PTRACE_SETOPTIONS, pid, 0, PTRACE_O_flags);

affects one tracee. The tracee's current flags are replaced. Flags areinherited by new tracees created and "auto-attached" via active PTRACE_O_TRACEFORK, PTRACE_O_TRACEVFORK,or PTRACE_O_TRACECLONE options.

Another group of commands makes the ptrace-stopped tracee run. They havethe form:

ptrace(cmd, pid, 0, sig);

where cmd is PTRACE_CONT, PTRACE_LISTEN, PTRACE_DETACH, PTRACE_SYSCALL, PTRACE_SINGLESTEP,PTRACE_SYSEMU,or PTRACE_SYSEMU_SINGLESTEP. If the tracee is insignal-delivery-stop, sig is the signal to be injected (if itis nonzero). Otherwise, sig may be ignored. (When restarting atracee from a ptrace-stop other than signal-delivery-stop, recommended practiceis to always pass 0 in sig.)

Attaching and detaching

A thread can be attached to the tracer using

the call

ptrace(PTRACE_ATTACH, pid, 0, 0);

or

ptrace(PTRACE_SEIZE, pid, 0, PTRACE_O_flags);

PTRACE_ATTACH sends SIGSTOP to thisthread. If the tracer wants this SIGSTOP to have no effect, itneeds to suppress it. Note that if other signals are concurrently sent to thisthread during attach, the tracer may see the tracee enter signal-delivery-stopwith other signal(s) first! The usual practice is to reinject thesesignals until SIGSTOP is seen, then suppress SIGSTOPinjection.The design bug here is that a ptrace attach and a concurrently delivered SIGSTOP mayrace and the concurrentSIGSTOP may be lost.

Since attaching sends SIGSTOP and the tracer usuallysuppresses it, this may cause a stray EINTR return from thecurrently executing system call in the tracee, as described in the "Signalinjection and suppression" section.

Since Linux 3.4, PTRACE_SEIZE can be used insteadof PTRACE_ATTACH. PTRACE_SEIZE does not stop theattached process. If you need to stop it after attach (or at any other time)without sending it any signals, use PTRACE_INTERRUPT command.

The request

ptrace(PTRACE_TRACEME, 0, 0, 0);

turns the calling thread into a tracee. The thread continues to run(doesn't enter ptrace-stop). A common practice is to follow thePTRACE_TRACEME with

raise(SIGSTOP);

and allow the parent (which is our tracer now) to observe oursignal-delivery-stop.

If the PTRACE_O_TRACEFORK, PTRACE_O_TRACEVFORK,or PTRACE_O_TRACECLONE options are in effect, then childrencreated by, respectively, vfork(2) or clone(2) withthe CLONE_VFORK flag, fork(2) or clone(2) withthe exit signal set to SIGCHLD, and other kinds of clone(2),are automatically attached to the same tracer which traced their parent. SIGSTOP isdelivered to the children, causing them to enter signal-delivery-stop afterthey exit the system call which created them.

Detaching of the tracee is performed by:

ptrace(PTRACE_DETACH, pid, 0, sig);

PTRACE_DETACH is a restarting operation; therefore itrequires the tracee to be in ptrace-stop. If the tracee is insignal-delivery-stop, a signal can be injected. Otherwise, the sig parametermay be silently ignored.

If the tracee is running when the tracer wants to detach it, the usualsolution is to send SIGSTOP (using tgkill(2),to make sure it goes to the correct thread), wait for the tracee to stop insignal-delivery-stop for SIGSTOP and then detach it(suppressingSIGSTOP injection). A design bug is that this can racewith concurrent SIGSTOPs. Another complication is that the traceemay enter other ptrace-stops and needs to be restarted and waited for again,until SIGSTOP is seen. Yet another complication is to be surethat the tracee is not already ptrace-stopped, because no signal deliveryhappens while it is--not even SIGSTOP.

If the tracer dies, all tracees are automatically detached and restarted,unless they were in group-stop. Handling of restart from group-stop iscurrently buggy, but the "as planned" behavior is to leave traceestopped and waiting for SIGCONT. If the tracee is restarted fromsignal-delivery-stop, the pending signal is injected.

execve(2) under ptrace

When one thread in a multithreaded process calls execve(2),the kernel destroys all other threads in the process, and resets the thread IDof the execing thread to the thread group ID (process ID). (Or, to put thingsanother way, when a multithreaded process does an execve(2),at completion of the call, it appears as though the execve(2) occurredin the thread group leader, regardless of which thread did the execve(2).)This resetting of the thread ID looks very confusing to tracers:

*

All other threadsstop in PTRACE_EVENT_EXIT stop, if the PTRACE_O_TRACEEXIT optionwas turned on. Then all other threads except the thread group leader reportdeath as if they exited via _exit(2) with exit code 0.

*

The execing traceechanges its thread ID while it is in the execve(2).(Remember, under ptrace, the "pid" returned fromwaitpid(2),or fed into ptrace calls, is the tracee's thread ID.) That is, the tracee'sthread ID is reset to be the same as its process ID, which is the same as thethread group leader's thread ID.

*

Then a PTRACE_EVENT_EXEC stophappens, if the PTRACE_O_TRACEEXEC option was turned on.

*

If the thread groupleader has reported its PTRACE_EVENT_EXIT stop by this time,it appears to the tracer that the dead thread leader "reappears fromnowhere". (Note: the thread group leader does not report death via WIFEXITED(status)untilthere is at least one other live thread. This eliminates the possibility thatthe tracer will see it dying and then reappearing.) If the thread group leaderwas still alive, for the tracer this may look as if thread group leader returnsfrom a different system call than it entered, or even "returned from asystem call even though it was not in any system call". If the thread groupleader was not traced (or was traced by a different tracer), then during execve(2) itwill appear as if it has become a tracee of the tracer of the execing tracee.

All of the above effects are the artifacts of the thread ID change in thetracee.

The PTRACE_O_TRACEEXEC option is the recommended tool fordealing with this situation. First, it enablesPTRACE_EVENT_EXEC stop,which occurs before execve(2) returns. In thisstop, the tracer can usePTRACE_GETEVENTMSG to retrieve the tracee'sformer thread ID. (This feature was introduced in Linux 3.0). Second, thePTRACE_O_TRACEEXEC optiondisables legacy SIGTRAP generation on execve(2).

When the tracer receives PTRACE_EVENT_EXEC stopnotification, it is guaranteed that except this tracee and the thread groupleader, no other threads from the process are alive.

On receiving the PTRACE_EVENT_EXEC stop notification, thetracer should clean up all its internal data structures describing the threadsof this process, and retain only one data structure--one which describes thesingle still running tracee, with

thread ID == thread group ID == process ID.

Example: two threads call execve(2) atthe same time:

*** we get syscall-enter-stop in thread 1: **

PID1 execve("/bin/foo", "foo" <unfinished ...>

*** we issue PTRACE_SYSCALL for thread 1 **

*** we get syscall-enter-stop in thread 2: **

PID2 execve("/bin/bar", "bar" <unfinished ...>

*** we issue PTRACE_SYSCALL for thread 2 **

*** we get PTRACE_EVENT_EXEC for PID0, we issue PTRACE_SYSCALL **

*** we get syscall-exit-stop for PID0: **

PID0 <... execve resumed> )             = 0

If the PTRACE_O_TRACEEXEC optionis not in effect for the execing tracee, the kernel deliversan extra SIGTRAP to the tracee after execve(2) returns.This is an ordinary signal (similar to one which can be generated by kill-TRAP), not a special kind of ptrace-stop. Employing PTRACE_GETSIGINFO forthis signal returns si_code set to 0 (SI_USER). Thissignal may be blocked by signal mask, and thus may be delivered (much) later.

Usually, the tracer (for example, strace(1))would not want to show this extra post-execve SIGTRAP signalto the user, and would suppress its delivery to the tracee (if SIGTRAP isset to SIG_DFL, it is a killing signal). However, determining whichSIGTRAP to suppress is not easy. Setting the PTRACE_O_TRACEEXEC optionand thus suppressing this extra SIGTRAP is the recommendedapproach.

Real parent

The ptrace API (ab) uses the standard UNIX parent/childsignaling over waitpid(2). This used to causethe real parent of the process to stop receiving several kinds of waitpid(2) notificationswhen the child process is traced by some other process.

Many of these bugs have been fixed, but as of Linux 2.6.38 several stillexist; see BUGS below.

As of Linux 2.6.38, the following is believed to work correctly:

*

exit/death by signalis reported first to the tracer, then, when the tracer consumes the waitpid(2) result,to the real parent (to the real parent only when the whole multithreadedprocess exits). If the tracer and the real parent are the same process, thereport is sent only once.

Return Value

On success, PTRACE_PEEK* requests returnthe requested data, while other requests return zero. On error, all requestsreturn -1, and errno is set appropriately. Since the valuereturned by a successful PTRACE_PEEK* request may be -1, thecaller must clear errno before the call, and then check itafterward to determine whether or not an error occurred.

Errors

EBUSY

(i386 only) There wasan error with allocating or freeing a debug register.

EFAULT

There was an attemptto read from or write to an invalid area in the tracer's or the tracee'smemory, probably because the area wasn't mapped or accessible. Unfortunately,under Linux, different variations of this fault will return EIO or EFAULTmore or less arbitrarily.

EINVAL

An attempt was madeto set an invalid option.

EIO

request is invalid, or an attempt was made to read from or write to aninvalid area in the tracer's or the tracee's memory, or there was aword-alignment violation, or an invalid signal was specified during a restartrequest.

EPERM

The specified processcannot be traced. This could be because the tracer has insufficient privileges(the required capability is CAP_SYS_PTRACE); unprivileged processescannot trace processes that they cannot send signals to or those runningset-user-ID/set-group-ID programs, for obvious reasons. Alternatively, theprocess may already be being traced, or (on kernels before 2.6.26) be init(8) (PID1).

ESRCH

The specified processdoes not exist, or is not currently being traced by the caller, or is notstopped (for requests that require a stopped tracee).

Conforming to

SVr4, 4.3BSD.

Notes

Although arguments to ptrace() areinterpreted according to the prototype given, glibc currently declares ptrace()as a variadic function with only the request argument fixed.It is recommended to always supply four arguments, even if the requestedoperation does not use them, setting unused/ignored arguments to 0L or (void*) 0.

In Linux kernels before 2.6.26, init(8),the process with PID 1, may not be traced.

The layout of the contents of memory and the USER area are quiteoperating-system- and architecture-specific. The offset supplied, and the datareturned, might not entirely match with the definition of struct user.

The size of a "word" is determined by the operating-systemvariant (e.g., for 32-bit Linux it is 32 bits).

This page documents the way the ptrace() call works currentlyin Linux. Its behavior differs noticeably on other flavors of UNIX. In anycase, use of ptrace() is highly specific to the operating systemand architecture.

Bugs

On hosts with 2.6 kernel headers, PTRACE_SETOPTIONS isdeclared with a different value than the one for 2.4. This leads toapplications compiled with 2.6 kernel headers failing when run on 2.4 kernels.This can be worked around by redefining PTRACE_SETOPTIONS to PTRACE_OLDSETOPTIONS,if that is defined.

Group-stop notifications are sent to the tracer, but not to real parent.Last confirmed on 2.6.38.6.

If a thread group leader is traced and exits by calling _exit(2),a PTRACE_EVENT_EXIT stop will happen for it (if requested),but the subsequent WIFEXITED notification will not bedelivered until all other threads exit. As explained above, if one of otherthreads calls execve(2), the death of thethread group leader will never be reported. If the execedthread is not traced by this tracer, the tracer will never know that execve(2) happened.One possible workaround is to PTRACE_DETACH the thread groupleader instead of restarting it in this case. Last confirmed on 2.6.38.6.

A SIGKILL signal may still cause a PTRACE_EVENT_EXIT stopbefore actual signal death. This may be changed in the future; SIGKILL ismeant to always immediately kill tasks even under ptrace. Last confirmed on2.6.38.6.

Some system calls return with EINTR if a signal was sentto a tracee, but delivery was suppressed by the tracer. (This is very typicaloperation: it is usually done by debuggers on every attach, in order to notintroduce a bogus SIGSTOP). As of Linux 3.2.9, the following systemcalls are affected (this list is likely incomplete): epoll_wait(2),and read(2) from an inotify(7) filedescriptor. The usual

symptom of this bug is that when you attach to a quiescent process with

the command

strace -p <process-ID>

then, instead of the usual and expected one-line output such as

restart_syscall(<... resuming interrupted call ...>_

or

select(6, [5], NULL, [5], NULL_

('_' denotes the cursor position), you observe more thanone line. For example:

clock_gettime(CLOCK_MONOTONIC, {15370, 690928118}) = 0

epoll_wait(4,_

What is not visible here is that the process was blockedin epoll_wait(2) before strace(1) hasattached to it. Attaching caused epoll_wait(2) toreturn to user space with the error EINTR. In this particular case,the program reacted to EINTR by checking the current time, andthen executing epoll_wait(2) again.(Programs which do not expect such "stray" EINTR errorsmay behave in an unintended way upon an strace(1) attach.)