X-Git-Url: http://git.osdn.net/view?p=linuxjm%2FLDP_man-pages.git;a=blobdiff_plain;f=original%2Fman2%2Fptrace.2;h=bb41cfc46a1e171b3085f73415a06df955358700;hp=37c4dff3d10b0f87544008aa87f957f912c7efe8;hb=781fb70b02c5d368a8ccd67d3c074c7aa8eb0c1a;hpb=657aaa2623246005bf75eb3c64da9382236c130a diff --git a/original/man2/ptrace.2 b/original/man2/ptrace.2 index 37c4dff3..bb41cfc4 100644 --- a/original/man2/ptrace.2 +++ b/original/man2/ptrace.2 @@ -42,10 +42,11 @@ .\" (Thanks to Blaisorblade, Daniel Jacobowitz and others who helped.) .\" 2011-09, major update by Denys Vlasenko .\" -.\" FIXME (later): Linux 3.1 adds PTRACE_SEIZE, PTRACE_INTERRUPT, +.\" FIXME Linux 2.6.34 adds PTRACE_GETREGSET/PTRACE_SETREGSET +.\" FIXME Linux 3.1 adds PTRACE_SEIZE, PTRACE_INTERRUPT, .\" and PTRACE_LISTEN. .\" -.TH PTRACE 2 2012-03-06 "Linux" "Linux Programmer's Manual" +.TH PTRACE 2 2012-03-24 "Linux" "Linux Programmer's Manual" .SH NAME ptrace \- process trace .SH SYNOPSIS @@ -373,6 +374,10 @@ value such that status>>8 == (SIGTRAP | (PTRACE_EVENT_EXEC<<8)) .fi +If the execing thread is not a thread group leader, +the thread ID is reset to thread group leader's ID before this stop. +Since Linux 3.0, the former thread ID can be retrieved with +.BR PTRACE_GETEVENTMSG . .TP .BR PTRACE_O_TRACEVFORKDONE " (since Linux 2.5.60)" Stop the tracee at the completion of the next @@ -467,7 +472,7 @@ The .I data argument is treated as for .BR PTRACE_CONT . -.RI (addr +.RI ( addr is ignored.) .TP .BR PTRACE_SYSEMU ", " PTRACE_SYSEMU_SINGLESTEP " (since Linux 2.6.14)" @@ -552,13 +557,6 @@ Under Linux, a tracee can be detached in this way regardless of which method was used to initiate tracing. .RI ( addr is ignored.) -.\" -.\" In the text below, we decided to avoid prettifying the text with markup: -.\" it would make the source nearly impossible to edit, and we _do_ intend -.\" to edit it often, in order to keep it updated: -.\" ptrace API is full of quirks, no need to compound this situation by -.\" making it excruciatingly painful to document them! -.\" .SS Death under ptrace When a (possibly multithreaded) process receives a killing signal (one whose disposition is set to @@ -722,11 +720,9 @@ Example: .\" describe how wait notifications queue (or not queue) .LP The following kinds of ptrace-stops exist: signal-delivery-stops, -group-stop, PTRACE_EVENT stops, syscall-stops -.BR PTRACE_SINGLESTEP , -.BR PTRACE_SYSEMU , -and -.BE PTRACE_SYSEMU_SINGLESTEP . +group-stops, +.B PTRACE_EVENT +stops, syscall-stops. They all are reported by .BR waitpid (2) with @@ -740,7 +736,7 @@ and if there is ambiguity in that value, by querying .I WSTOPSIG(status) macro can't be used to perform this examination, because it returns the value -(\fIstatus\>>8)\ \fB&\ 0xff\fP\fP.) +.IR "(status\>>8)\ &\ 0xff" .) .SS Signal-delivery-stop When a (possibly multithreaded) process receives any signal except .BR SIGKILL , @@ -766,9 +762,9 @@ Signal-delivery-stop is observed by the tracer as .BR waitpid (2) returning with .I WIFSTOPPED(status) -true, with the stopping signal returned by +true, with the signal returned by .IR WSTOPSIG(status) . -If the stopping signal is +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. @@ -802,12 +798,17 @@ value: the tracer can cause a different signal to be injected. .LP Note that a suppressed signal still causes system calls to return prematurely. -Restartable system calls will be restarted (the tracer will -observe the tracee to execute -.BR restart_syscall(2) -if the tracer uses -.BR PTRACE_SYSCALL ); -non-restartable system calls may fail with +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 syscalls 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 syscalls to fail with .B EINTR even though no observable signal is injected to the tracee. .LP @@ -842,7 +843,7 @@ The 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 +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). @@ -1002,7 +1003,7 @@ with the exit signal set to .TP .B PTRACE_EVENT_CLONE Stop before return from -.BR clone (2) +.BR clone (2). .TP .B PTRACE_EVENT_VFORK_DONE Stop before return from @@ -1023,6 +1024,9 @@ can be used to retrieve the new thread's ID. .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 @@ -1044,7 +1048,8 @@ to finish exiting. on .B PTRACE_EVENT stops returns -.B SIGTRAP in +.B SIGTRAP +in .IR si_signo , with .I si_code @@ -1148,7 +1153,7 @@ But such detection is fragile and is best avoided. .LP Using the .B PTRACE_O_TRACESYSGOOD -option is the recommended method to distinquish syscall-stops +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 @@ -1248,7 +1253,7 @@ is .BR PTRACE_SINGLESTEP , .BR PTRACE_SYSEMU , or -.BR PTRACE_SYSEMU_SINGLESTEP. +.BR PTRACE_SYSEMU_SINGLESTEP . If the tracee is in signal-delivery-stop, .I sig is the signal to be injected (if it is nonzero). @@ -1257,7 +1262,7 @@ Otherwise, may be ignored. (When restarting a tracee from a ptrace-stop other than signal-delivery-stop, recommended practice is to always pass 0 in -.I sig .) +.IR sig .) .SS Attaching and detaching A thread can be attached to the tracer using the call @@ -1290,9 +1295,9 @@ may be lost. Since attaching sends .B SIGSTOP and the tracer usually suppresses it, this may cause a stray -.I EINTR +.B EINTR return from the currently executing system call in the tracee, -as described in the "signal injection and suppression" section. +as described in the "Signal injection and suppression" section. .LP The request @@ -1406,12 +1411,6 @@ death as if they exited via .BR _exit (2) with exit code 0. .IP * -Then a -.B PTRACE_EVENT_EXEC -stop happens, if the -.BR PTRACE_O_TRACEEXEC -option was turned on. -.IP * The execing tracee changes its thread ID while it is in the .BR execve (2). (Remember, under ptrace, the "pid" returned from @@ -1420,9 +1419,22 @@ or fed into ptrace calls, is the tracee's thread ID.) That is, the tracee's thread ID is reset to be the same as its process ID, which is the same as the thread group leader's thread ID. .IP * -If the thread group leader has reported its death by this time, +Then a +.B PTRACE_EVENT_EXEC +stop happens, if the +.BR PTRACE_O_TRACEEXEC +option was turned on. +.IP * +If the thread group leader has reported its +.B PTRACE_EVENT_EXIT +stop by this time, it appears to the tracer that the dead thread leader "reappears from nowhere". +(Note: the thread group leader does not report death via +.I WIFEXITED(status) +until there is at least one other live thread. +This eliminates the possibility that the tracer will see +it dying and then reappearing.) If the thread group leader was still alive, for the tracer this may look as if thread group leader returns from a different system call than it entered, @@ -1440,15 +1452,11 @@ the thread ID change in the tracee. The .B PTRACE_O_TRACEEXEC option is the recommended tool for dealing with this situation. -It enables -.B PTRACE_EVENT_EXEC -stop, which occurs before -.BR execve (2) -returns. First, it enables -.BR PTRACE_EVENT_EXEC -stop, +.BR PTRACE_EVENT_EXEC +stop, which occurs before -.BR execve(2) +.BR execve (2) returns. In this stop, the tracer can use .B PTRACE_GETEVENTMSG @@ -1475,23 +1483,17 @@ data structures describing the threads of this process, and retain only one data structure\(emone which describes the single still running tracee, with - thread ID == thread group ID == process id. -.LP -Currently, there is no way to retrieve the former -thread ID of the execing tracee. -If the tracer doesn't keep track of its tracees' thread group relations, -it may be unable to know which tracee execed and therefore no longer -exists under the old thread ID due to a thread ID change. + thread ID == thread group ID == process ID. .LP Example: two threads call .BR execve (2) at the same time: .LP .nf -*** we get syscall-entry-stop in thread 1: ** +*** we get syscall-enter-stop in thread 1: ** PID1 execve("/bin/foo", "foo" *** we issue PTRACE_SYSCALL for thread 1 ** -*** we get syscall-entry-stop in thread 2: ** +*** we get syscall-enter-stop in thread 2: ** PID2 execve("/bin/bar", "bar" *** we issue PTRACE_SYSCALL for thread 2 ** *** we get PTRACE_EVENT_EXEC for PID0, we issue PTRACE_SYSCALL ** @@ -1499,10 +1501,6 @@ PID2 execve("/bin/bar", "bar" PID0 <... execve resumed> ) = 0 .fi .LP -In this situation, there is no way to know which -.BR execve (2) -succeeded. -.LP If the .B PTRACE_O_TRACEEXEC option is @@ -1713,6 +1711,22 @@ This may be changed in the future; .B SIGKILL is meant to always immediately kill tasks even under ptrace. Last confirmed on 2.6.38.6. +.LP +Some system calls return with +.B EINTR +if a signal was sent to a tracee, but delivery was suppressed by the tracer. +(This is very typical operation: it is usually +done by debuggers on every attach, in order to not introduce +a bogus +.BR SIGSTOP ). +As of Linux 3.2.9, the following system calls are affected +(this list is likely incomplete): +.BR epoll_wait (2), +and +.BR read (2) +from an +.BR inotify (7) +file descriptor. .SH "SEE ALSO" .BR gdb (1), .BR strace (1),