mirror of https://github.com/mkerrisk/man-pages
Wrapped long lines (no content changes).
This commit is contained in:
Michael Kerrisk
parent
4b9d4c1ac5
commit
e63ad01dce
239
man2/ptrace.2
239
man2/ptrace.2
|
|
@ -54,24 +54,28 @@ ptrace \- process trace
|
|||
.SH DESCRIPTION
|
||||
The
|
||||
.BR 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
|
||||
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.
|
||||
.LP
|
||||
The parent can initiate a trace by calling
|
||||
.BR fork (2)
|
||||
and having the resulting child do a PTRACE_TRACEME, followed (typically) by an
|
||||
and having the resulting child do a PTRACE_TRACEME,
|
||||
followed (typically) by an
|
||||
.BR exec (3).
|
||||
Alternatively, the parent may commence trace of an existing process using
|
||||
PTRACE_ATTACH.
|
||||
.LP
|
||||
While being traced, the child will stop each time a signal is delivered, even
|
||||
if the signal is being ignored. (The exception is SIGKILL, which has its
|
||||
usual effect.) The parent will be notified at its next
|
||||
While being traced, the child will stop each time a signal is delivered,
|
||||
even if the signal is being ignored.
|
||||
(The exception is SIGKILL, which has its usual effect.)
|
||||
The parent will be notified at its next
|
||||
.BR 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
|
||||
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).
|
||||
.LP
|
||||
When the parent is finished tracing, it can terminate the child with
|
||||
|
|
@ -87,14 +91,18 @@ parent to be notified via
|
|||
.BR wait ().
|
||||
Also, all subsequent calls to
|
||||
.BR exec ()
|
||||
by this process will cause a SIGTRAP to be sent to it, giving the parent a
|
||||
chance to gain control before the new program begins execution. A process
|
||||
probably shouldn't make this request if its parent isn't expecting to trace
|
||||
it. (\fIpid\fP, \fIaddr\fP, and \fIdata\fP are ignored.)
|
||||
by this process will cause a SIGTRAP to be sent to it,
|
||||
giving the parent a chance to gain control before the new program
|
||||
begins execution.
|
||||
A process probably shouldn't make this request if its parent
|
||||
isn't expecting to trace it.
|
||||
(\fIpid\fP, \fIaddr\fP, and \fIdata\fP are ignored.)
|
||||
.LP
|
||||
The above request is used only by the child process; the rest are used only by
|
||||
the parent. In the following requests, \fIpid\fP specifies the child process
|
||||
to be acted on. For requests other than PTRACE_KILL, the child process must
|
||||
The above request is used only by the child process;
|
||||
the rest are used only by the parent.
|
||||
In the following requests, \fIpid\fP specifies the child process
|
||||
to be acted on.
|
||||
For requests other than PTRACE_KILL, the child process must
|
||||
be stopped.
|
||||
.TP
|
||||
PTRACE_PEEKTEXT, PTRACE_PEEKDATA
|
||||
|
|
@ -102,18 +110,22 @@ Reads a word at the location
|
|||
.IR addr
|
||||
in the child's memory, returning the word as the result of the
|
||||
.BR ptrace ()
|
||||
call. Linux does not have separate text and data address spaces, so the two
|
||||
requests are currently equivalent. (The argument \fIdata\fP is ignored.)
|
||||
call.
|
||||
Linux does not have separate text and data address spaces, so the two
|
||||
requests are currently equivalent.
|
||||
(The argument \fIdata\fP is ignored.)
|
||||
.TP
|
||||
PTRACE_PEEKUSR
|
||||
Reads a word at offset
|
||||
.I addr
|
||||
in the child's
|
||||
.B USER
|
||||
area, which holds the registers and other information about the process (see
|
||||
<linux/user.h> and <sys/user.h>). The word is returned as the result of the
|
||||
area, which holds the registers and other information about the process
|
||||
(see <linux/user.h> and <sys/user.h>).
|
||||
The word is returned as the result of the
|
||||
.BR ptrace ()
|
||||
call. Typically the offset must be word-aligned, though this might vary by
|
||||
call.
|
||||
Typically the offset must be word-aligned, though this might vary by
|
||||
architecture. (\fIdata\fP is ignored.)
|
||||
.TP
|
||||
PTRACE_POKETEXT, PTRACE_POKEDATA
|
||||
|
|
@ -130,14 +142,17 @@ to offset
|
|||
.I addr
|
||||
in the child's
|
||||
.B USER
|
||||
area. As above, the offset must typically be word-aligned. In order to
|
||||
maintain the integrity of the kernel, some modifications to the
|
||||
area.
|
||||
As above, the offset must typically be word-aligned.
|
||||
In order to maintain the integrity of the kernel,
|
||||
some modifications to the
|
||||
.B USER
|
||||
area are disallowed.
|
||||
.TP
|
||||
PTRACE_GETREGS, PTRACE_GETFPREGS
|
||||
Copies the child's general purpose or floating-point registers, respectively,
|
||||
to location \fIdata\fP in the parent. See <linux/user.h> for information on
|
||||
Copies the child's general purpose or floating-point registers,
|
||||
respectively, to location \fIdata\fP in the parent.
|
||||
See <linux/user.h> for information on
|
||||
the format of this data. (\fIaddr\fP is ignored.)
|
||||
.TP
|
||||
PTRACE_GETSIGINFO (since Linux 2.3.99-pre6)
|
||||
|
|
@ -148,14 +163,16 @@ from the child to location \fIdata\fP in the parent.
|
|||
(\fIaddr\fP is ignored.)
|
||||
.TP
|
||||
PTRACE_SETREGS, PTRACE_SETFPREGS
|
||||
Copies the child's general purpose or floating-point registers, respectively,
|
||||
from location \fIdata\fP in the parent. As for PTRACE_POKEUSER, some general
|
||||
purpose register modifications may be disallowed. (\fIaddr\fP is ignored.)
|
||||
Copies the child's general purpose or floating-point registers,
|
||||
respectively, from location \fIdata\fP in the parent.
|
||||
As for PTRACE_POKEUSER, some general
|
||||
purpose register modifications may be disallowed.
|
||||
(\fIaddr\fP is ignored.)
|
||||
.TP
|
||||
PTRACE_SETSIGINFO (since Linux 2.3.99-pre6)
|
||||
Set signal information.
|
||||
Copies a \fIsiginfo_t\fP structure from location \fIdata\fP in the parent
|
||||
to the child.
|
||||
Copies a \fIsiginfo_t\fP structure from location \fIdata\fP 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
|
||||
|
|
@ -170,30 +187,32 @@ as a bitmask of options, which are specified by the following flags:
|
|||
.RS
|
||||
.TP
|
||||
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_TRACESYSGOOD
|
||||
may not work on all architectures.)
|
||||
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_TRACESYSGOOD may not work on all architectures.)
|
||||
.TP
|
||||
PTRACE_O_TRACEFORK (since Linux 2.5.46)
|
||||
Stop the child at the next
|
||||
.BR fork ()
|
||||
call with SIGTRAP | PTRACE_EVENT_FORK << 8 and automatically start tracing
|
||||
the newly forked process, which will start with a SIGSTOP.
|
||||
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.
|
||||
.TP
|
||||
PTRACE_O_TRACEVFORK (since Linux 2.5.46)
|
||||
Stop the child at the next
|
||||
.BR vfork ()
|
||||
call with SIGTRAP | PTRACE_EVENT_VFORK << 8 and automatically start tracing
|
||||
the newly vforked process, which will start with a SIGSTOP.
|
||||
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.
|
||||
.TP
|
||||
PTRACE_O_TRACECLONE (since Linux 2.5.46)
|
||||
Stop the child at the next
|
||||
.BR clone ()
|
||||
call with SIGTRAP | PTRACE_EVENT_CLONE << 8 and automatically start tracing
|
||||
the newly cloned process, which will start with a SIGSTOP.
|
||||
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
|
||||
.BR clone ()
|
||||
|
|
@ -218,9 +237,10 @@ 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.
|
||||
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 context is available, the tracer cannot prevent the exit from
|
||||
happening at this point.
|
||||
.RE
|
||||
|
|
@ -237,61 +257,71 @@ is the PID of the new process. (\fIaddr\fP is ignored.)
|
|||
PTRACE_CONT
|
||||
Restarts the stopped child process. If \fIdata\fP 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. (\fIaddr\fP is
|
||||
ignored.)
|
||||
otherwise, no signal is delivered.
|
||||
Thus, for example, the parent can control
|
||||
whether a signal sent to the child is delivered or not.
|
||||
(\fIaddr\fP is ignored.)
|
||||
.TP
|
||||
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 system call, or after execution
|
||||
of a single instruction, respectively. (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 arguments 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. (\fIaddr\fP is ignored.)
|
||||
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 system call,
|
||||
or after execution of a single instruction, respectively.
|
||||
(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 arguments 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.
|
||||
(\fIaddr\fP is ignored.)
|
||||
.TP
|
||||
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_SINGLESTEP, do the same
|
||||
but also singlestep if not a syscall. This call is used by programs like
|
||||
User Mode Linux that want to emulate all of the the child's syscalls.
|
||||
(\fIaddr\fP and \fIdata\fP are ignored; not supported on all architectures.)
|
||||
(\fIaddr\fP and \fIdata\fP are ignored;
|
||||
not supported on all architectures.)
|
||||
.TP
|
||||
PTRACE_KILL
|
||||
Sends the child a SIGKILL to terminate it. (\fIaddr\fP and \fIdata\fP are
|
||||
ignored.)
|
||||
Sends the child a SIGKILL to terminate it.
|
||||
(\fIaddr\fP and \fIdata\fP are ignored.)
|
||||
.TP
|
||||
PTRACE_ATTACH
|
||||
Attaches to the process specified in
|
||||
.IR pid ,
|
||||
making it a traced "child" of the current process; the behavior of the child
|
||||
is as if it had done a PTRACE_TRACEME. The current process actually becomes
|
||||
the parent of the child process for most purposes (e.g., it will receive
|
||||
making it a traced "child" of the current process;
|
||||
the behavior of the child is as if it had done a PTRACE_TRACEME.
|
||||
The current process actually becomes the parent of the child
|
||||
process for most purposes (e.g., it will receive
|
||||
notification of child events and appears in
|
||||
.BR ps (1)
|
||||
output as the child's parent), but a
|
||||
.BR 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
|
||||
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
|
||||
.BR wait ()
|
||||
to wait for the child to stop. (\fIaddr\fP and \fIdata\fP are ignored.)
|
||||
to wait for the child to stop.
|
||||
(\fIaddr\fP and \fIdata\fP are ignored.)
|
||||
.TP
|
||||
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 perhaps not intended, under Linux a traced child
|
||||
can be detached in this way regardless of which method was used to initiate
|
||||
tracing. (\fIaddr\fP is ignored.)
|
||||
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 perhaps not intended, under Linux a traced child can be
|
||||
detached in this way regardless of which method was used to initiate
|
||||
tracing.
|
||||
(\fIaddr\fP is ignored.)
|
||||
.SH NOTES
|
||||
Although arguments to
|
||||
.BR ptrace ()
|
||||
are interpreted according to the prototype given, GNU libc currently declares
|
||||
are interpreted according to the prototype given,
|
||||
GNU libc currently declares
|
||||
.BR ptrace ()
|
||||
as a variadic function with only the \fIrequest\fP argument fixed. This means
|
||||
that unneeded trailing arguments may be omitted, though doing so makes use of
|
||||
undocumented
|
||||
as a variadic function with only the \fIrequest\fP argument fixed.
|
||||
This means that unneeded trailing arguments may be omitted,
|
||||
though doing so makes use of undocumented
|
||||
.BR gcc (1)
|
||||
behavior.
|
||||
.LP
|
||||
|
|
@ -301,76 +331,85 @@ 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.
|
||||
.LP
|
||||
The size of a "word" is determined by the OS variant (e.g., for 32-bit Linux
|
||||
it's 32 bits, etc.).
|
||||
The size of a "word" is determined by the OS variant
|
||||
(e.g., for 32-bit Linux it's 32 bits, etc.).
|
||||
.LP
|
||||
Tracing causes a few subtle differences in the semantics of traced processes.
|
||||
For example, if a process is attached to with PTRACE_ATTACH, its original
|
||||
parent can no longer receive notification via
|
||||
Tracing causes a few subtle differences in the semantics of
|
||||
traced processes.
|
||||
For example, if a process is attached to with PTRACE_ATTACH,
|
||||
its original parent can no longer receive notification via
|
||||
.BR wait ()
|
||||
when it stops, and there is no way for the new parent to effectively simulate
|
||||
this notification.
|
||||
when it stops, and there is no way for the new parent to
|
||||
effectively simulate this notification.
|
||||
.LP
|
||||
This page documents the way the
|
||||
.BR ptrace ()
|
||||
call works currently in Linux. Its behavior differs noticeably on other
|
||||
flavors of Unix. In any case, use of
|
||||
call works currently in Linux.
|
||||
Its behavior differs noticeably on other flavors of Unix.
|
||||
In any case, use of
|
||||
.BR ptrace ()
|
||||
is highly OS- and architecture-specific.
|
||||
.LP
|
||||
The SunOS man page describes
|
||||
.BR ptrace ()
|
||||
as "unique and arcane", which it is. The proc-based debugging interface
|
||||
as "unique and arcane", which it is.
|
||||
The proc-based debugging interface
|
||||
present in Solaris 2 implements a superset of
|
||||
.BR ptrace ()
|
||||
functionality in a more powerful and uniform way.
|
||||
.SH "RETURN VALUE"
|
||||
On success, PTRACE_PEEK* requests return the requested data, while other requests
|
||||
return zero. On error, all requests return \-1, and
|
||||
On success, PTRACE_PEEK* requests return the requested data,
|
||||
while other requests return zero.
|
||||
On error, all requests return \-1, and
|
||||
.I errno
|
||||
is set appropriately. Since the value returned by a successful PTRACE_PEEK*
|
||||
is set appropriately.
|
||||
Since the value returned by a successful PTRACE_PEEK*
|
||||
request may be \-1, the caller must check
|
||||
.I errno
|
||||
after such requests to determine whether or not an error occurred.
|
||||
.SH 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 compiled with such
|
||||
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 compiled 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.
|
||||
.SH ERRORS
|
||||
.TP
|
||||
.B EBUSY
|
||||
(i386 only) There was an error with allocating or freeing a debug register.
|
||||
(i386 only) There was an error with allocating or freeing a debug
|
||||
register.
|
||||
.TP
|
||||
.B 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.
|
||||
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.
|
||||
.TP
|
||||
.B EINVAL
|
||||
An attempt was made to set an invalid option.
|
||||
.TP
|
||||
.B EIO
|
||||
\fIrequest\fP 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 specified during a restart request.
|
||||
\fIrequest\fP 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 specified during a restart request.
|
||||
.TP
|
||||
.B EPERM
|
||||
The specified process cannot be traced. This could be because the
|
||||
parent has insufficient privileges (the required capability is
|
||||
.BR 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.
|
||||
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
|
||||
.BR init
|
||||
(PID 1).
|
||||
.TP
|
||||
.B 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).
|
||||
The specified process does not exist, or is not currently being traced
|
||||
by the caller, or is not stopped (for requests that require that).
|
||||
.SH "CONFORMING TO"
|
||||
SVr4, SVID EXT, AT&T, X/OPEN, 4.3BSD
|
||||
.SH "SEE ALSO"
|
||||
|
|
|
|||
Loading…
Reference in New Issue