mirror of https://github.com/mkerrisk/man-pages
537 lines
16 KiB
Groff
537 lines
16 KiB
Groff
.\" Hey Emacs! This file is -*- nroff -*- source.
|
|
.\"
|
|
.\" Copyright (c) 1993 Michael Haardt
|
|
.\" (michael@moria.de),
|
|
.\" Fri Apr 2 11:32:09 MET DST 1993
|
|
.\"
|
|
.\" changes Copyright 1999 Mike Coleman (mkc@acm.org)
|
|
.\" -- major revision to fully document ptrace semantics per recent Linux
|
|
.\" kernel (2.2.10) and glibc (2.1.2)
|
|
.\" Sun Nov 7 03:18:35 CST 1999
|
|
.\"
|
|
.\" This is free documentation; you can redistribute it and/or
|
|
.\" modify it under the terms of the GNU General Public License as
|
|
.\" published by the Free Software Foundation; either version 2 of
|
|
.\" the License, or (at your option) any later version.
|
|
.\"
|
|
.\" The GNU General Public License's references to "object code"
|
|
.\" and "executables" are to be interpreted as the output of any
|
|
.\" document formatting or typesetting system, including
|
|
.\" intermediate and printed output.
|
|
.\"
|
|
.\" This manual is distributed in the hope that it will be useful,
|
|
.\" but WITHOUT ANY WARRANTY; without even the implied warranty of
|
|
.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
|
|
.\" GNU General Public License for more details.
|
|
.\"
|
|
.\" You should have received a copy of the GNU General Public
|
|
.\" License along with this manual; if not, write to the Free
|
|
.\" Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111,
|
|
.\" USA.
|
|
.\"
|
|
.\" Modified Fri Jul 23 23:47:18 1993 by Rik Faith <faith@cs.unc.edu>
|
|
.\" Modified Fri Jan 31 16:46:30 1997 by Eric S. Raymond <esr@thyrsus.com>
|
|
.\" Modified Thu Oct 7 17:28:49 1999 by Andries Brouwer <aeb@cwi.nl>
|
|
.\" Modified, 27 May 2004, Michael Kerrisk <mtk.manpages@gmail.com>
|
|
.\" Added notes on capability requirements
|
|
.\"
|
|
.\" 2006-03-24, Chuck Ebbert <76306.1226@compuserve.com>
|
|
.\" Added PTRACE_SETOPTIONS, PTRACE_GETEVENTMSG, PTRACE_GETSIGINFO,
|
|
.\" PTRACE_SETSIGINFO, PTRACE_SYSEMU, PTRACE_SYSEMU_SINGLESTEP
|
|
.\" (Thanks to Blaisorblade, Daniel Jacobowitz and others who helped.)
|
|
.\"
|
|
.TH PTRACE 2 2009-03-30 "Linux" "Linux Programmer's Manual"
|
|
.SH NAME
|
|
ptrace \- process trace
|
|
.SH SYNOPSIS
|
|
.nf
|
|
.B #include <sys/ptrace.h>
|
|
.sp
|
|
.BI "long ptrace(enum __ptrace_request " request ", pid_t " pid ", "
|
|
.BI " void *" addr ", void *" data );
|
|
.fi
|
|
.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
|
|
call tracing.
|
|
.LP
|
|
The parent can initiate a trace by calling
|
|
.BR fork (2)
|
|
and having the resulting child do a
|
|
.BR PTRACE_TRACEME ,
|
|
followed (typically) by an
|
|
.BR exec (3).
|
|
Alternatively, the parent may commence trace of an existing process using
|
|
.BR 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
|
|
.BR 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
|
|
(or even delivering a different signal instead).
|
|
.LP
|
|
When the parent is finished tracing, it can terminate the child with
|
|
.B PTRACE_KILL
|
|
or cause it to continue executing in a normal, untraced mode
|
|
via
|
|
.BR PTRACE_DETACH .
|
|
.LP
|
|
The value of \fIrequest\fP determines the action to be performed:
|
|
.TP
|
|
.B PTRACE_TRACEME
|
|
Indicates that this process is to be traced by its parent.
|
|
Any signal
|
|
(except
|
|
.BR SIGKILL )
|
|
delivered to this process will cause it to stop and its
|
|
parent to be notified via
|
|
.BR wait (2).
|
|
Also, all subsequent calls to
|
|
.BR execve (2)
|
|
by this process will cause a
|
|
.B 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
|
|
.BR PTRACE_KILL ,
|
|
the child process must
|
|
be stopped.
|
|
.TP
|
|
.BR PTRACE_PEEKTEXT ", " PTRACE_PEEKDATA
|
|
Reads a word at the location
|
|
.I 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.)
|
|
.TP
|
|
.B PTRACE_PEEKUSER
|
|
.\" PTRACE_PEEKUSR in kernel source, but glibc uses PTRACE_PEEKUSER,
|
|
.\" and that is the name that seems common on other systems.
|
|
Reads a word at offset
|
|
.I addr
|
|
in the child's USER area,
|
|
which holds the registers and other information about the process
|
|
(see \fI<sys/user.h>\fP).
|
|
The word is returned as the result of the
|
|
.BR ptrace ()
|
|
call.
|
|
Typically the offset must be word-aligned, though this might vary by
|
|
architecture.
|
|
See NOTES.
|
|
(\fIdata\fP is ignored.)
|
|
.TP
|
|
.BR PTRACE_POKETEXT ", " PTRACE_POKEDATA
|
|
Copies the word
|
|
.I data
|
|
to location
|
|
.I addr
|
|
in the child's memory.
|
|
As above, the two requests are currently equivalent.
|
|
.TP
|
|
.B PTRACE_POKEUSER
|
|
.\" PTRACE_POKEUSR in kernel source, but glibc uses PTRACE_POKEUSER,
|
|
.\" and that is the name that seems common on other systems.
|
|
Copies the word
|
|
.I data
|
|
to offset
|
|
.I addr
|
|
in the child's USER area.
|
|
As above, the offset must typically be word-aligned.
|
|
In order to maintain the integrity of the kernel,
|
|
some modifications to the USER area are disallowed.
|
|
.TP
|
|
.BR PTRACE_GETREGS ", " PTRACE_GETFPREGS
|
|
Copies the child's general purpose or floating-point registers,
|
|
respectively, to location \fIdata\fP in the parent.
|
|
See \fI<sys/user.h>\fP for information on
|
|
the format of this data.
|
|
(\fIaddr\fP is ignored.)
|
|
.TP
|
|
.BR PTRACE_GETSIGINFO " (since Linux 2.3.99-pre6)"
|
|
Retrieve information about the signal that caused the stop.
|
|
Copies a \fIsiginfo_t\fP structure (see
|
|
.BR sigaction (2))
|
|
from the child to location \fIdata\fP in the parent.
|
|
(\fIaddr\fP is ignored.)
|
|
.TP
|
|
.BR PTRACE_SETREGS ", " PTRACE_SETFPREGS
|
|
Copies the child's general purpose or floating-point registers,
|
|
respectively, from location \fIdata\fP in the parent.
|
|
As for
|
|
.BR PTRACE_POKEUSER ,
|
|
some general
|
|
purpose register modifications may be disallowed.
|
|
(\fIaddr\fP is ignored.)
|
|
.TP
|
|
.BR 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.
|
|
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
|
|
.BR ptrace ()
|
|
itself.
|
|
(\fIaddr\fP is ignored.)
|
|
.TP
|
|
.BR PTRACE_SETOPTIONS " (since Linux 2.4.6; see BUGS for caveats)"
|
|
Sets ptrace options from \fIdata\fP in the parent.
|
|
(\fIaddr\fP is ignored.)
|
|
\fIdata\fP is interpreted
|
|
as a bit mask of options, which are specified by the following flags:
|
|
.RS
|
|
.TP
|
|
.BR PTRACE_O_TRACESYSGOOD " (since Linux 2.4.6)"
|
|
When delivering syscall traps, set bit 7 in the signal number
|
|
(i.e., deliver \fI(SIGTRAP | 0x80)\fP
|
|
This makes it easy for the tracer to tell the difference
|
|
between normal traps and those caused by a syscall.
|
|
.RB ( PTRACE_O_TRACESYSGOOD
|
|
may not work on all architectures.)
|
|
.TP
|
|
.BR PTRACE_O_TRACEFORK " (since Linux 2.5.46)"
|
|
Stop the child at the next
|
|
.BR fork (2)
|
|
call with \fISIGTRAP | PTRACE_EVENT_FORK\ <<\ 8\fP and automatically
|
|
start tracing the newly forked process,
|
|
which will start with a
|
|
.BR SIGSTOP .
|
|
The PID for the new process can be retrieved with
|
|
.BR PTRACE_GETEVENTMSG .
|
|
.TP
|
|
.BR PTRACE_O_TRACEVFORK " (since Linux 2.5.46)"
|
|
Stop the child at the next
|
|
.BR vfork (2)
|
|
call with \fISIGTRAP | PTRACE_EVENT_VFORK\ <<\ 8\fP and automatically start
|
|
tracing the newly vforked process, which will start with a
|
|
.BR SIGSTOP .
|
|
The PID for the new process can be retrieved with
|
|
.BR PTRACE_GETEVENTMSG .
|
|
.TP
|
|
.BR PTRACE_O_TRACECLONE " (since Linux 2.5.46)"
|
|
Stop the child at the next
|
|
.BR clone (2)
|
|
call with \fISIGTRAP | PTRACE_EVENT_CLONE\ <<\ 8\fP and automatically start
|
|
tracing the newly cloned process, which will start with a
|
|
.BR SIGSTOP .
|
|
The PID for the new process can be retrieved with
|
|
.BR PTRACE_GETEVENTMSG .
|
|
This option may not catch
|
|
.BR clone (2)
|
|
calls in all cases.
|
|
If the child calls
|
|
.BR clone (2)
|
|
with the
|
|
.B CLONE_VFORK
|
|
flag,
|
|
.B PTRACE_EVENT_VFORK
|
|
will be delivered instead
|
|
if
|
|
.B PTRACE_O_TRACEVFORK
|
|
is set; otherwise if the child calls
|
|
.BR clone (2)
|
|
with the exit signal set to
|
|
.BR SIGCHLD ,
|
|
.B PTRACE_EVENT_FORK
|
|
will be delivered
|
|
if
|
|
.B PTRACE_O_TRACEFORK
|
|
is set.
|
|
.TP
|
|
.BR PTRACE_O_TRACEEXEC " (since Linux 2.5.46)"
|
|
Stop the child at the next
|
|
.BR execve (2)
|
|
call with \fISIGTRAP | PTRACE_EVENT_EXEC\ <<\ 8\fP.
|
|
.TP
|
|
.BR PTRACE_O_TRACEVFORKDONE " (since Linux 2.5.60)"
|
|
Stop the child at the completion of the next
|
|
.BR vfork (2)
|
|
call with \fISIGTRAP | PTRACE_EVENT_VFORK_DONE\ <<\ 8\fP.
|
|
.TP
|
|
.BR PTRACE_O_TRACEEXIT " (since Linux 2.5.60)"
|
|
Stop the child at exit with \fISIGTRAP | PTRACE_EVENT_EXIT\ <<\ 8\fP.
|
|
The child's exit status can be retrieved with
|
|
.BR PTRACE_GETEVENTMSG .
|
|
This stop will be done early during process exit when registers
|
|
are still available, allowing the tracer to see where the exit occurred,
|
|
whereas the normal exit notification is done after the process
|
|
is finished exiting.
|
|
Even though context is available, the tracer cannot prevent the exit from
|
|
happening at this point.
|
|
.RE
|
|
.TP
|
|
.BR PTRACE_GETEVENTMSG " (since Linux 2.5.46)"
|
|
Retrieve a message (as an
|
|
.IR "unsigned long" )
|
|
about the ptrace event
|
|
that just happened, placing it in the location \fIdata\fP in the parent.
|
|
For
|
|
.B PTRACE_EVENT_EXIT
|
|
this is the child's exit status.
|
|
For
|
|
.BR PTRACE_EVENT_FORK ,
|
|
.B PTRACE_EVENT_VFORK
|
|
and
|
|
.B PTRACE_EVENT_CLONE
|
|
this
|
|
is the PID of the new process.
|
|
Since Linux 2.6.18, the PID of the new process is also available
|
|
for
|
|
.BR PTRACE_EVENT_VFORK_DONE .
|
|
(\fIaddr\fP is ignored.)
|
|
.TP
|
|
.B PTRACE_CONT
|
|
Restarts the stopped child process.
|
|
If \fIdata\fP is nonzero and not
|
|
.BR 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.)
|
|
.TP
|
|
.BR PTRACE_SYSCALL ", " PTRACE_SINGLESTEP
|
|
Restarts the stopped child as for
|
|
.BR 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
|
|
.BR SIGTRAP .
|
|
So, for
|
|
.BR PTRACE_SYSCALL ,
|
|
for example, the idea is to inspect
|
|
the arguments to the system call at the first stop,
|
|
then do another
|
|
.B PTRACE_SYSCALL
|
|
and inspect the return value of
|
|
the system call at the second stop.
|
|
The
|
|
.I data
|
|
argument is treated as for
|
|
.BR PTRACE_CONT .
|
|
(\fIaddr\fP is ignored.)
|
|
.TP
|
|
.BR PTRACE_SYSEMU ", " PTRACE_SYSEMU_SINGLESTEP " (since Linux 2.6.14)"
|
|
For
|
|
.BR PTRACE_SYSEMU ,
|
|
continue and stop on entry to the next syscall,
|
|
which will not be executed.
|
|
For
|
|
.BR 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 the child's system calls.
|
|
The
|
|
.I data
|
|
argument is treated as for
|
|
.BR PTRACE_CONT .
|
|
(\fIaddr\fP is ignored;
|
|
not supported on all architectures.)
|
|
.TP
|
|
.B PTRACE_KILL
|
|
Sends the child a
|
|
.B SIGKILL
|
|
to terminate it.
|
|
(\fIaddr\fP and \fIdata\fP are ignored.)
|
|
.TP
|
|
.B PTRACE_ATTACH
|
|
Attaches to the process specified in
|
|
.IR pid ,
|
|
making it a traced "child" of the calling process;
|
|
the behavior of the child is as if it had done a
|
|
.BR PTRACE_TRACEME .
|
|
The calling process actually becomes the parent of the child
|
|
process for most purposes (e.g., it will receive
|
|
notification of child events and appears in
|
|
.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
|
|
.BR SIGSTOP ,
|
|
but will not necessarily have stopped
|
|
by the completion of this call; use
|
|
.BR wait (2)
|
|
to wait for the child to stop.
|
|
(\fIaddr\fP and \fIdata\fP are ignored.)
|
|
.TP
|
|
.B PTRACE_DETACH
|
|
Restarts the stopped child as for
|
|
.BR PTRACE_CONT ,
|
|
but first detaches
|
|
from the process, undoing the reparenting effect of
|
|
.BR PTRACE_ATTACH ,
|
|
and the effects of
|
|
.BR 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 "RETURN VALUE"
|
|
On success,
|
|
.B 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
|
|
.B PTRACE_PEEK*
|
|
request may be \-1, the caller must check
|
|
.I errno
|
|
after such requests to determine whether or not an error occurred.
|
|
.SH ERRORS
|
|
.TP
|
|
.B EBUSY
|
|
(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
|
|
.B EIO
|
|
or
|
|
.B 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.
|
|
.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 );
|
|
unprivileged processes cannot trace processes that they
|
|
cannot send signals to or those running
|
|
set-user-ID/set-group-ID programs, for obvious reasons.
|
|
Alternatively, the process may already be being traced, or be
|
|
.BR init (8)
|
|
(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).
|
|
.SH "CONFORMING TO"
|
|
SVr4, 4.3BSD.
|
|
.SH NOTES
|
|
Although arguments to
|
|
.BR ptrace ()
|
|
are interpreted according to the prototype given,
|
|
glibc 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
|
|
.BR gcc (1)
|
|
behavior.
|
|
.LP
|
|
.BR init (8),
|
|
the process with PID 1, may not be traced.
|
|
.LP
|
|
The layout of the contents of memory and the USER area are quite OS- and
|
|
architecture-specific.
|
|
The offset supplied, and the data returned,
|
|
might not entirely match with the definition of
|
|
.IR "struct user" .
|
|
.\" See http://lkml.org/lkml/2008/5/8/375
|
|
.LP
|
|
The size of a "word" is determined by the OS variant
|
|
(e.g., for 32-bit Linux it is 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
|
|
.BR PTRACE_ATTACH ,
|
|
its original parent can no longer receive notification via
|
|
.BR wait (2)
|
|
when it stops, and there is no way for the new parent to
|
|
effectively simulate this notification.
|
|
.LP
|
|
When the parent receives an event with
|
|
.B PTRACE_EVENT_*
|
|
set,
|
|
the child is not in the normal signal delivery path.
|
|
This means the parent cannot do
|
|
.BR ptrace (PTRACE_CONT)
|
|
with a signal or
|
|
.BR ptrace (PTRACE_KILL).
|
|
.BR kill (2)
|
|
with a
|
|
.B SIGKILL
|
|
signal can be used instead to kill the child process
|
|
after receiving one of these messages.
|
|
.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
|
|
.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
|
|
present in Solaris 2 implements a superset of
|
|
.BR ptrace ()
|
|
functionality in a more powerful and uniform way.
|
|
.SH BUGS
|
|
On hosts with 2.6 kernel headers,
|
|
.B 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
|
|
.B PTRACE_SETOPTIONS
|
|
to
|
|
.BR PTRACE_OLDSETOPTIONS ,
|
|
if that is defined.
|
|
.SH "SEE ALSO"
|
|
.BR gdb (1),
|
|
.BR strace (1),
|
|
.BR execve (2),
|
|
.BR fork (2),
|
|
.BR signal (2),
|
|
.BR wait (2),
|
|
.BR exec (3),
|
|
.BR capabilities (7)
|