+but first detach from it.
+Under Linux, a tracee can be detached in this way regardless
+of which method was used to initiate tracing.
+.RI ( addr
+is ignored.)
+.SS Death under ptrace
+When a (possibly multithreaded) process receives a killing signal
+(one whose disposition is set to
+.B SIG_DFL
+and whose default action is to kill the process),
+all threads exit.
+Tracees report their death to their tracer(s).
+Notification of this event is delivered via
+.BR waitpid (2).
+.LP
+Note that the killing signal will first cause signal-delivery-stop
+(on one tracee only),
+and only after it is injected by the tracer
+(or after it was dispatched to a thread which isn't traced),
+will death from the signal happen on
+.I all
+tracees within a multithreaded process.
+(The term "signal-delivery-stop" is explained below.)
+.LP
+.B SIGKILL
+does not generate signal-delivery-stop and
+therefore the tracer can't suppress it.
+.B SIGKILL
+kills even within system calls
+(syscall-exit-stop is not generated prior to death by
+.BR SIGKILL ).
+The net effect is that
+.B SIGKILL
+always kills the process (all its threads),
+even if some threads of the process are ptraced.
+.LP
+When the tracee calls
+.BR _exit (2),
+it reports its death to its tracer.
+Other threads are not affected.
+.LP
+When any thread executes
+.BR exit_group (2),
+every tracee in its thread group reports its death to its tracer.
+.LP
+If the
+.B PTRACE_O_TRACEEXIT
+option is on,
+.B PTRACE_EVENT_EXIT
+will happen before actual death.
+This applies to exits via
+.BR exit (2),
+.BR exit_group (2),
+and signal deaths (except
+.BR SIGKILL ),
+and when threads are torn down on
+.BR execve (2)
+in a multithreaded process.
+.LP
+The tracer cannot assume that the ptrace-stopped tracee exists.
+There are many scenarios when the tracee may die while stopped (such as
+.BR SIGKILL ).
+Therefore, the tracer must be prepared to handle an
+.B ESRCH
+error on any ptrace operation.
+Unfortunately, the same error is returned if the tracee
+exists but is not ptrace-stopped
+(for commands which require a stopped tracee),
+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,
+and interpret
+.B ESRCH
+as "tracee died unexpectedly" only if it knows that the tracee has
+been observed to enter ptrace-stop.
+Note that there is no guarantee that
+.I waitpid(WNOHANG)
+will reliably report the tracee's death status if a
+ptrace operation returned
+.BR ESRCH .
+.I waitpid(WNOHANG)
+may return 0 instead.
+In other words, the tracee may be "not yet fully dead",
+but already refusing ptrace requests.
+.LP
+The tracer can't assume that the tracee
+.I always
+ends its life by reporting
+.I WIFEXITED(status)
+or
+.IR WIFSIGNALED(status) ;
+there are cases where this does not occur.
+For example, if a thread other than thread group leader does an
+.BR execve (2),
+it disappears;
+its PID will never be seen again,
+and any subsequent ptrace stops will be reported under
+the thread group leader's PID.
+.SS Stopped states
+A tracee can be in two states: running or stopped.
+For the purposes of ptrace, a tracee which is blocked in a system call
+(such as
+.BR read (2),
+.BR pause (2),
+etc.)
+is nevertheless considered to be running, even if the tracee is blocked
+for a long time.
+The state of the tracee after
+.BR PTRACE_LISTEN
+is somewhat of a gray area: it is not in any ptrace-stop (ptrace commands
+won't work on it, and it will deliver
+.BR waitpid (2)
+notifications),
+but it also may be considered "stopped" because
+it is not executing instructions (is not scheduled), and if it was
+in group-stop before
+.BR PTRACE_LISTEN ,
+it will not respond to signals until
+.B SIGCONT
+is received.
+.LP
+There are many kinds of states when the tracee is stopped, and in ptrace
+discussions they are often conflated.
+Therefore, it is important to use precise terms.
+.LP
+In this manual page, any stopped state in which the tracee is ready
+to accept ptrace commands from the tracer is called
+.IR ptrace-stop .
+Ptrace-stops can
+be further subdivided into
+.IR signal-delivery-stop ,
+.IR group-stop ,
+.IR syscall-stop ,
+and so on.
+These stopped states are described in detail below.
+.LP
+When the running tracee enters ptrace-stop, it notifies its tracer using
+.BR waitpid (2)
+(or one of the other "wait" system calls).
+Most of this manual page assumes that the tracer waits with:
+.LP
+ pid = waitpid(pid_or_minus_1, &status, __WALL);
+.LP
+Ptrace-stopped tracees are reported as returns with
+.I pid
+greater than 0 and
+.I WIFSTOPPED(status)
+true.
+.\" Denys Vlasenko:
+.\" Do we require __WALL usage, or will just using 0 be ok? (With 0,
+.\" I am not 100% sure there aren't ugly corner cases.) Are the
+.\" rules different if user wants to use waitid? Will waitid require
+.\" WEXITED?
+.\"
+.LP
+The
+.B __WALL
+flag does not include the
+.B WSTOPPED
+and
+.B WEXITED
+flags, but implies their functionality.
+.LP
+Setting the
+.B WCONTINUED
+flag when calling
+.BR waitpid (2)
+is not recommended: the "continued" state is per-process and
+consuming it can confuse the real parent of the tracee.
+.LP
+Use of the
+.B WNOHANG
+flag may cause
+.BR waitpid (2)
+to return 0 ("no wait results available yet")
+even if the tracer knows there should be a notification.
+Example:
+.nf
+
+ 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! */
+ }
+.fi
+.\" FIXME .
+.\" waitid usage? WNOWAIT?
+.\" describe how wait notifications queue (or not queue)
+.LP
+The following kinds of ptrace-stops exist: signal-delivery-stops,
+group-stops,
+.B PTRACE_EVENT
+stops, syscall-stops.
+They all are reported by
+.BR waitpid (2)
+with
+.I WIFSTOPPED(status)
+true.
+They may be differentiated by examining the value
+.IR status>>8 ,
+and if there is ambiguity in that value, by querying
+.BR PTRACE_GETSIGINFO .
+(Note: the
+.I WSTOPSIG(status)
+macro can't be used to perform this examination,
+because it returns the value
+.IR "(status>>8)\ &\ 0xff" .)
+.SS Signal-delivery-stop
+When a (possibly multithreaded) process receives any signal except
+.BR SIGKILL ,
+the kernel selects an arbitrary thread which handles the signal.
+(If the signal is generated with
+.BR tgkill (2),
+the target thread can be explicitly selected by the caller.)
+If the selected thread is traced, it enters signal-delivery-stop.
+At this point, the signal is not yet delivered to the process,
+and can be suppressed by the tracer.
+If the tracer doesn't suppress the signal,
+it passes the signal to the tracee in the next ptrace restart request.
+This second step of signal delivery is called
+.I "signal injection"
+in this manual page.
+Note that if the signal is blocked,
+signal-delivery-stop doesn't happen until the signal is unblocked,
+with the usual exception that
+.B SIGSTOP
+can't be blocked.
+.LP
+Signal-delivery-stop is observed by the tracer as
+.BR waitpid (2)
+returning with
+.I WIFSTOPPED(status)
+true, with the signal returned by
+.IR WSTOPSIG(status) .
+If the signal is
+.BR SIGTRAP ,
+this may be a different kind of ptrace-stop;
+see the "Syscall-stops" and "execve" sections below for details.
+If
+.I WSTOPSIG(status)
+returns a stopping signal, this may be a group-stop; see below.
+.SS Signal injection and suppression
+After signal-delivery-stop is observed by the tracer,
+the tracer should restart the tracee with the call
+.LP
+ ptrace(PTRACE_restart, pid, 0, sig)
+.LP
+where
+.B PTRACE_restart
+is one of the restarting ptrace requests.
+If
+.I sig
+is 0, then a signal is not delivered.
+Otherwise, the signal
+.I sig
+is delivered.
+This operation is called
+.I "signal injection"
+in this manual page, to distinguish it from signal-delivery-stop.
+.LP
+The
+.I sig
+value may be different from the
+.I WSTOPSIG(status)
+value: the tracer can cause a different signal to be injected.
+.LP
+Note that a suppressed signal still causes system calls to return
+prematurely.
+In this case, system calls will be restarted: the tracer will
+observe the tracee to reexecute the interrupted system call (or
+.BR restart_syscall (2)
+system call for a few system calls which use a different mechanism
+for restarting) if the tracer uses
+.BR PTRACE_SYSCALL .
+Even system calls (such as
+.BR poll (2))
+which are not restartable after signal are restarted after
+signal is suppressed;
+however, kernel bugs exist which cause some system calls to fail with
+.B EINTR
+even though no observable signal is injected to the tracee.
+.LP
+Restarting ptrace commands issued in ptrace-stops other than
+signal-delivery-stop are not guaranteed to inject a signal, even if
+.I sig
+is nonzero.
+No error is reported; a nonzero
+.I sig
+may simply be ignored.
+Ptrace users should not try to "create a new signal" this way: use
+.BR tgkill (2)
+instead.
+.LP
+The fact that signal injection requests may be ignored
+when restarting the tracee after
+ptrace stops that are not signal-delivery-stops
+is a cause of confusion among ptrace users.
+One typical scenario is that the tracer observes group-stop,
+mistakes it for signal-delivery-stop, restarts the tracee with
+
+ ptrace(PTRACE_restart, pid, 0, stopsig)
+
+with the intention of injecting
+.IR stopsig ,
+but
+.I stopsig
+gets ignored and the tracee continues to run.
+.LP
+The
+.B SIGCONT
+signal has a side effect of waking up (all threads of)
+a group-stopped process.
+This side effect happens before signal-delivery-stop.
+The tracer can't suppress this side effect (it can
+only suppress signal injection, which only causes the
+.BR SIGCONT
+handler to not be executed in the tracee, if such a handler is installed).
+In fact, waking up from group-stop may be followed by
+signal-delivery-stop for signal(s)
+.I other than
+.BR SIGCONT ,
+if they were pending when
+.B SIGCONT
+was delivered.
+In other words,
+.B SIGCONT
+may be not the first signal observed by the tracee after it was sent.
+.LP
+Stopping signals cause (all threads of) a process to enter group-stop.
+This side effect happens after signal injection, and therefore can be
+suppressed by the tracer.
+.LP
+In Linux 2.4 and earlier, the
+.B SIGSTOP
+signal can't be injected.
+.\" In the Linux 2.4 sources, in arch/i386/kernel/signal.c::do_signal(),
+.\" there is:
+.\"
+.\" /* The debugger continued. Ignore SIGSTOP. */
+.\" if (signr == SIGSTOP)
+.\" continue;
+.LP
+.B PTRACE_GETSIGINFO
+can be used to retrieve a
+.I siginfo_t
+structure which corresponds to the delivered signal.
+.B PTRACE_SETSIGINFO
+may be used to modify it.
+If
+.B PTRACE_SETSIGINFO
+has been used to alter
+.IR siginfo_t ,
+the
+.I si_signo
+field and the
+.I sig
+parameter in the restarting command must match,
+otherwise the result is undefined.
+.SS Group-stop
+When a (possibly multithreaded) process receives a stopping signal,
+all threads stop.
+If some threads are traced, they enter a group-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 it was dispatched to a thread which isn't traced),
+will group-stop be initiated on
+.I all
+tracees within the multithreaded process.
+As usual, every tracee reports its group-stop separately
+to the corresponding tracer.
+.LP
+Group-stop is observed by the tracer as
+.BR waitpid (2)
+returning with
+.I WIFSTOPPED(status)
+true, with the stopping signal available via
+.IR WSTOPSIG(status) .
+The same result is returned by some other classes of ptrace-stops,
+therefore the recommended practice is to perform the call
+.LP
+ ptrace(PTRACE_GETSIGINFO, pid, 0, &siginfo)
+.LP
+The call can be avoided if the signal is not
+.BR SIGSTOP ,
+.BR SIGTSTP ,
+.BR SIGTTIN ,
+or
+.BR SIGTTOU ;
+only these four signals are stopping signals.
+If the tracer sees something else, it can't be a group-stop.
+Otherwise, the tracer needs to call
+.BR PTRACE_GETSIGINFO .
+If
+.B PTRACE_GETSIGINFO
+fails with
+.BR EINVAL ,
+then it is definitely a group-stop.
+(Other failure codes are possible, such as
+.B ESRCH
+("no such process") if a
+.B SIGKILL
+killed the tracee.)
+.LP
+If tracee was attached using
+.BR PTRACE_SEIZE ,
+group-stop is indicated by
+.BR PTRACE_EVENT_STOP :
+.IR "status>>16 == PTRACE_EVENT_STOP" .
+This allows detection of group-stops
+without requiring an extra
+.B PTRACE_GETSIGINFO
+call.
+.LP
+As of Linux 2.6.38,
+after the tracer sees the tracee ptrace-stop and until it
+restarts or kills it, the tracee will not run,
+and will not send notifications (except
+.B SIGKILL
+death) to the tracer, even if the tracer enters into another
+.BR waitpid (2)
+call.
+.LP
+The kernel behavior described in the previous paragraph
+causes a problem with transparent handling of stopping signals.
+If the tracer restarts the tracee after group-stop,
+the stopping signal
+is effectively ignored\(emthe tracee doesn't remain stopped, it runs.
+If the tracer doesn't restart the tracee before entering into the next
+.BR waitpid (2),
+future
+.B SIGCONT
+signals will not be reported to the tracer;
+this would cause the
+.B SIGCONT
+signals to have no effect on the tracee.
+.LP
+Since Linux 3.4, there is a method to overcome this problem: instead of
+.BR PTRACE_CONT ,
+a
+.B PTRACE_LISTEN
+command can be used to restart a tracee in a way where it does not execute,
+but waits for a new event which it can report via
+.BR waitpid (2)
+(such as when
+it is restarted by a
+.BR SIGCONT ).
+.SS PTRACE_EVENT stops
+If the tracer sets
+.B PTRACE_O_TRACE_*
+options, the tracee will enter ptrace-stops called
+.B PTRACE_EVENT
+stops.
+.LP
+.B PTRACE_EVENT
+stops are observed by the tracer as
+.BR waitpid (2)
+returning with
+.IR WIFSTOPPED(status) ,
+and
+.I WSTOPSIG(status)
+returns
+.BR SIGTRAP .
+An additional bit is set in the higher byte of the status word:
+the value
+.I status>>8
+will be
+
+ (SIGTRAP | PTRACE_EVENT_foo << 8).
+
+The following events exist:
+.TP
+.B PTRACE_EVENT_VFORK
+Stop before return from
+.BR vfork (2)
+or
+.BR clone (2)
+with the
+.B CLONE_VFORK
+flag.
+When the tracee is continued after this stop, it will wait for child to
+exit/exec before continuing its execution
+(in other words, the usual behavior on
+.BR vfork (2)).
+.TP
+.B PTRACE_EVENT_FORK
+Stop before return from
+.BR fork (2)
+or
+.BR clone (2)
+with the exit signal set to
+.BR SIGCHLD .
+.TP
+.B PTRACE_EVENT_CLONE
+Stop before return from
+.BR clone (2).
+.TP
+.B PTRACE_EVENT_VFORK_DONE
+Stop before return from
+.BR vfork (2)
+or
+.BR clone (2)
+with the
+.B CLONE_VFORK
+flag,
+but after the child unblocked this tracee by exiting or execing.
+.LP
+For all four stops described above,
+the stop occurs in the parent (i.e., the tracee),
+not in the newly created thread.
+.BR PTRACE_GETEVENTMSG
+can be used to retrieve the new thread's ID.
+.TP
+.B PTRACE_EVENT_EXEC
+Stop before return from
+.BR execve (2).
+Since Linux 3.0,
+.BR PTRACE_GETEVENTMSG
+returns the former thread ID.
+.TP
+.B PTRACE_EVENT_EXIT
+Stop before exit (including death from
+.BR exit_group (2)),
+signal death, or exit caused by
+.BR execve (2)
+in a multithreaded process.
+.B PTRACE_GETEVENTMSG
+returns the exit status.
+Registers can be examined
+(unlike when "real" exit happens).
+The tracee is still alive; it needs to be
+.BR PTRACE_CONT ed
+or
+.BR PTRACE_DETACH ed
+to finish exiting.
+.TP
+.B PTRACE_EVENT_STOP
+Stop induced by
+.B PTRACE_INTERRUPT
+command, or group-stop, or initial ptrace-stop when a new child is attached
+(only if attached using
+.BR PTRACE_SEIZE ),
+or
+.B PTRACE_EVENT_STOP
+if
+.B PTRACE_SEIZE
+was used.
+.TP
+.B PTRACE_EVENT_SECCOMP
+Stop triggered by a
+.BR seccomp (2)
+rule on tracee syscall entry when
+.BR PTRACE_O_TRACESECCOMP
+has been set by the tracer.
+The seccomp event message data (from the
+.BR SECCOMP_RET_DATA
+portion of the seccomp filter rule) can be retrieved with
+.BR PTRACE_GETEVENTMSG .
+.LP
+.B PTRACE_GETSIGINFO
+on
+.B PTRACE_EVENT
+stops returns
+.B SIGTRAP
+in
+.IR si_signo ,
+with
+.I si_code
+set to
+.IR "(event<<8)\ |\ SIGTRAP" .
+.SS Syscall-stops
+If the tracee was restarted by
+.BR PTRACE_SYSCALL ,
+the tracee enters
+syscall-enter-stop just prior to entering any system call.
+If the tracer restarts the tracee with
+.BR PTRACE_SYSCALL ,
+the tracee enters syscall-exit-stop when the system call is finished,
+or if it is interrupted by a signal.
+(That is, signal-delivery-stop never happens between syscall-enter-stop
+and syscall-exit-stop; it happens
+.I after
+syscall-exit-stop.)
+.LP
+Other possibilities are that the tracee may stop in a
+.B PTRACE_EVENT
+stop, exit (if it entered
+.BR _exit (2)
+or
+.BR exit_group (2)),
+be killed by
+.BR SIGKILL ,
+or die silently (if it is a thread group leader, the
+.BR execve (2)
+happened in another thread,
+and that thread is not traced by the same tracer;
+this situation is discussed later).
+.LP
+Syscall-enter-stop and syscall-exit-stop are observed by the tracer as
+.BR waitpid (2)
+returning with
+.I WIFSTOPPED(status)
+true, and
+.I WSTOPSIG(status)
+giving
+.BR SIGTRAP .
+If the
+.B PTRACE_O_TRACESYSGOOD
+option was set by the tracer, then
+.I WSTOPSIG(status)
+will give the value
+.IR "(SIGTRAP\ |\ 0x80)" .
+.LP
+Syscall-stops can be distinguished from signal-delivery-stop with
+.B SIGTRAP
+by querying
+.BR PTRACE_GETSIGINFO
+for the following cases:
+.TP
+.IR si_code " <= 0"
+.B SIGTRAP
+was delivered as a result of a user-space action,
+for example, a system call
+.RB ( tgkill (2),
+.BR kill (2),
+.BR sigqueue (3),
+etc.),
+expiration of a POSIX timer,
+change of state on a POSIX message queue,
+or completion of an asynchronous I/O request.
+.TP
+.IR si_code " == SI_KERNEL (0x80)"
+.B SIGTRAP
+was sent by the kernel.
+.TP
+.IR si_code " == SIGTRAP or " si_code " == (SIGTRAP|0x80)"
+This is a syscall-stop.
+.LP
+However, syscall-stops happen very often (twice per system call),
+and performing
+.B PTRACE_GETSIGINFO
+for every syscall-stop may be somewhat expensive.
+.LP
+Some architectures allow the cases to be distinguished
+by examining registers.
+For example, on x86,
+.I rax
+==
+.RB - ENOSYS
+in syscall-enter-stop.
+Since
+.B SIGTRAP
+(like any other signal) always happens
+.I after
+syscall-exit-stop,
+and at this point
+.I rax
+almost never contains
+.RB - ENOSYS ,
+the
+.B SIGTRAP
+looks like "syscall-stop which is not syscall-enter-stop";
+in other words, it looks like a
+"stray syscall-exit-stop" and can be detected this way.
+But such detection is fragile and is best avoided.
+.LP
+Using the
+.B PTRACE_O_TRACESYSGOOD
+option is the recommended method to distinguish syscall-stops
+from other kinds of ptrace-stops,
+since it is reliable and does not incur a performance penalty.
+.LP
+Syscall-enter-stop and syscall-exit-stop are
+indistinguishable from each other by the tracer.
+The tracer needs to keep track of the sequence of
+ptrace-stops in order to not misinterpret syscall-enter-stop as
+syscall-exit-stop or vice versa.
+The rule is that syscall-enter-stop is
+always followed by syscall-exit-stop,
+.B PTRACE_EVENT
+stop or the tracee's death;
+no other kinds of ptrace-stop can occur in between.
+.LP
+If after syscall-enter-stop,
+the tracer uses a restarting command other than
+.BR PTRACE_SYSCALL ,
+syscall-exit-stop is not generated.
+.LP
+.B PTRACE_GETSIGINFO
+on syscall-stops returns
+.B SIGTRAP
+in
+.IR si_signo ,
+with
+.I si_code
+set to
+.B SIGTRAP
+or
+.IR (SIGTRAP|0x80) .
+.SS PTRACE_SINGLESTEP, PTRACE_SYSEMU, PTRACE_SYSEMU_SINGLESTEP stops
+[Details of these kinds of stops are yet to be documented.]
+.\"
+.\" FIXME .
+.\" document stops occurring with PTRACE_SINGLESTEP, PTRACE_SYSEMU,
+.\" PTRACE_SYSEMU_SINGLESTEP
+.SS Informational and restarting ptrace commands
+Most ptrace commands (all except
OSDN Git Service
