2004-11-03 13:51:07 +00:00
|
|
|
.\" 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
|
2007-04-12 22:42:49 +00:00
|
|
|
.\" kernel (2.2.10) and glibc (2.1.2)
|
2004-11-03 13:51:07 +00:00
|
|
|
.\" 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>
|
2004-11-03 14:43:40 +00:00
|
|
|
.\" Modified, 27 May 2004, Michael Kerrisk <mtk-manpages@gmx.net>
|
2004-11-03 13:51:07 +00:00
|
|
|
.\" Added notes on capability requirements
|
|
|
|
.\"
|
2006-03-23 22:00:08 +00:00
|
|
|
.\" 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 2006-03-24 "Linux 2.6.16" "Linux Programmer's Manual"
|
2004-11-03 13:51:07 +00:00
|
|
|
.SH NAME
|
|
|
|
ptrace \- process trace
|
|
|
|
.SH SYNOPSIS
|
2006-03-23 22:00:08 +00:00
|
|
|
.nf
|
2004-11-03 13:51:07 +00:00
|
|
|
.B #include <sys/ptrace.h>
|
|
|
|
.sp
|
2006-03-23 22:00:08 +00:00
|
|
|
.BI "long ptrace(enum __ptrace_request " request ", pid_t " pid ", "
|
|
|
|
.BI " void *" addr ", void *" data );
|
|
|
|
.fi
|
2004-11-03 13:51:07 +00:00
|
|
|
.SH DESCRIPTION
|
|
|
|
The
|
2005-10-19 06:54:38 +00:00
|
|
|
.BR ptrace ()
|
2007-04-12 22:42:49 +00:00
|
|
|
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.
|
2006-03-25 21:28:28 +00:00
|
|
|
It is primarily used to implement breakpoint debugging and system
|
2004-11-03 13:51:07 +00:00
|
|
|
call tracing.
|
|
|
|
.LP
|
|
|
|
The parent can initiate a trace by calling
|
2007-04-12 22:42:49 +00:00
|
|
|
.BR fork (2)
|
|
|
|
and having the resulting child do a PTRACE_TRACEME,
|
2006-03-25 21:28:28 +00:00
|
|
|
followed (typically) by an
|
2004-11-03 13:51:07 +00:00
|
|
|
.BR exec (3).
|
|
|
|
Alternatively, the parent may commence trace of an existing process using
|
|
|
|
PTRACE_ATTACH.
|
|
|
|
.LP
|
2007-04-12 22:42:49 +00:00
|
|
|
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.)
|
2006-03-25 21:28:28 +00:00
|
|
|
The parent will be notified at its next
|
2004-11-03 13:51:07 +00:00
|
|
|
.BR wait (2)
|
2007-04-12 22:42:49 +00:00
|
|
|
and may inspect and modify the child process while it is stopped.
|
|
|
|
The parent then causes the child to continue,
|
2006-03-25 21:28:28 +00:00
|
|
|
optionally ignoring the delivered signal
|
2004-11-03 13:51:07 +00:00
|
|
|
(or even delivering a different signal instead).
|
|
|
|
.LP
|
|
|
|
When the parent is finished tracing, it can terminate the child with
|
|
|
|
PTRACE_KILL or cause it to continue executing in a normal, untraced mode
|
|
|
|
via PTRACE_DETACH.
|
|
|
|
.LP
|
|
|
|
The value of \fIrequest\fP determines the action to be performed:
|
|
|
|
.TP
|
|
|
|
PTRACE_TRACEME
|
2007-04-12 22:42:49 +00:00
|
|
|
Indicates that this process is to be traced by its parent.
|
|
|
|
Any signal
|
2004-11-03 13:51:07 +00:00
|
|
|
(except SIGKILL) delivered to this process will cause it to stop and its
|
|
|
|
parent to be notified via
|
2007-05-11 23:07:02 +00:00
|
|
|
.BR wait (2).
|
2004-11-03 13:51:07 +00:00
|
|
|
Also, all subsequent calls to
|
2007-05-11 23:07:02 +00:00
|
|
|
.BR execve (2)
|
2007-04-12 22:42:49 +00:00
|
|
|
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.
|
2006-03-25 21:28:28 +00:00
|
|
|
(\fIpid\fP, \fIaddr\fP, and \fIdata\fP are ignored.)
|
2004-11-03 13:51:07 +00:00
|
|
|
.LP
|
2007-04-12 22:42:49 +00:00
|
|
|
The above request is used only by the child process;
|
|
|
|
the rest are used only by the parent.
|
2006-03-25 21:28:28 +00:00
|
|
|
In the following requests, \fIpid\fP specifies the child process
|
2007-04-12 22:42:49 +00:00
|
|
|
to be acted on.
|
2006-03-25 21:28:28 +00:00
|
|
|
For requests other than PTRACE_KILL, the child process must
|
2004-11-03 13:51:07 +00:00
|
|
|
be stopped.
|
|
|
|
.TP
|
|
|
|
PTRACE_PEEKTEXT, PTRACE_PEEKDATA
|
|
|
|
Reads a word at the location
|
|
|
|
.IR addr
|
|
|
|
in the child's memory, returning the word as the result of the
|
2005-10-19 06:54:38 +00:00
|
|
|
.BR ptrace ()
|
2007-04-12 22:42:49 +00:00
|
|
|
call.
|
2006-03-25 21:28:28 +00:00
|
|
|
Linux does not have separate text and data address spaces, so the two
|
2007-04-12 22:42:49 +00:00
|
|
|
requests are currently equivalent.
|
2006-03-25 21:28:28 +00:00
|
|
|
(The argument \fIdata\fP is ignored.)
|
2004-11-03 13:51:07 +00:00
|
|
|
.TP
|
|
|
|
PTRACE_PEEKUSR
|
|
|
|
Reads a word at offset
|
|
|
|
.I addr
|
|
|
|
in the child's
|
|
|
|
.B USER
|
2007-04-12 22:42:49 +00:00
|
|
|
area, which holds the registers and other information about the process
|
|
|
|
(see <linux/user.h> and <sys/user.h>).
|
2006-03-25 21:28:28 +00:00
|
|
|
The word is returned as the result of the
|
2005-10-19 06:54:38 +00:00
|
|
|
.BR ptrace ()
|
2007-04-12 22:42:49 +00:00
|
|
|
call.
|
2006-03-25 21:28:28 +00:00
|
|
|
Typically the offset must be word-aligned, though this might vary by
|
2004-11-03 13:51:07 +00:00
|
|
|
architecture. (\fIdata\fP is ignored.)
|
|
|
|
.TP
|
|
|
|
PTRACE_POKETEXT, PTRACE_POKEDATA
|
|
|
|
Copies the word
|
|
|
|
.IR data
|
|
|
|
to location
|
|
|
|
.IR addr
|
2007-04-12 22:42:49 +00:00
|
|
|
in the child's memory.
|
|
|
|
As above, the two requests are currently equivalent.
|
2004-11-03 13:51:07 +00:00
|
|
|
.TP
|
|
|
|
PTRACE_POKEUSR
|
|
|
|
Copies the word
|
|
|
|
.IR data
|
|
|
|
to offset
|
|
|
|
.I addr
|
|
|
|
in the child's
|
|
|
|
.B USER
|
2007-04-12 22:42:49 +00:00
|
|
|
area.
|
|
|
|
As above, the offset must typically be word-aligned.
|
|
|
|
In order to maintain the integrity of the kernel,
|
2006-03-25 21:28:28 +00:00
|
|
|
some modifications to the
|
2004-11-03 13:51:07 +00:00
|
|
|
.B USER
|
|
|
|
area are disallowed.
|
|
|
|
.TP
|
|
|
|
PTRACE_GETREGS, PTRACE_GETFPREGS
|
2007-04-12 22:42:49 +00:00
|
|
|
Copies the child's general purpose or floating-point registers,
|
|
|
|
respectively, to location \fIdata\fP in the parent.
|
2006-03-25 21:28:28 +00:00
|
|
|
See <linux/user.h> for information on
|
2004-11-03 13:51:07 +00:00
|
|
|
the format of this data. (\fIaddr\fP is ignored.)
|
|
|
|
.TP
|
2006-03-23 22:00:08 +00:00
|
|
|
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
|
2004-11-03 13:51:07 +00:00
|
|
|
PTRACE_SETREGS, PTRACE_SETFPREGS
|
2007-04-12 22:42:49 +00:00
|
|
|
Copies the child's general purpose or floating-point registers,
|
|
|
|
respectively, from location \fIdata\fP in the parent.
|
2006-03-25 21:28:28 +00:00
|
|
|
As for PTRACE_POKEUSER, some general
|
2007-04-12 22:42:49 +00:00
|
|
|
purpose register modifications may be disallowed.
|
2006-03-25 21:28:28 +00:00
|
|
|
(\fIaddr\fP is ignored.)
|
2004-11-03 13:51:07 +00:00
|
|
|
.TP
|
2006-03-23 22:00:08 +00:00
|
|
|
PTRACE_SETSIGINFO (since Linux 2.3.99-pre6)
|
|
|
|
Set signal information.
|
2007-04-12 22:42:49 +00:00
|
|
|
Copies a \fIsiginfo_t\fP structure from location \fIdata\fP in the
|
2006-03-25 21:28:28 +00:00
|
|
|
parent to the child.
|
2006-03-23 22:00:08 +00:00
|
|
|
This will only affect signals that would normally be delivered to
|
2007-04-12 22:42:49 +00:00
|
|
|
the child and were caught by the tracer.
|
|
|
|
It may be difficult to tell
|
2006-03-23 22:00:08 +00:00
|
|
|
these normal signals from synthetic signals generated by
|
|
|
|
.BR ptrace ()
|
|
|
|
itself. (\fIaddr\fP is ignored.)
|
|
|
|
.TP
|
|
|
|
PTRACE_SETOPTIONS (since Linux 2.4.6; see BUGS for caveats)
|
2007-04-12 22:42:49 +00:00
|
|
|
Sets ptrace options from \fIdata\fP in the parent.
|
2006-03-23 22:00:08 +00:00
|
|
|
(\fIaddr\fP is ignored.)
|
|
|
|
\fIdata\fP is interpreted
|
|
|
|
as a bitmask of options, which are specified by the following flags:
|
|
|
|
.RS
|
|
|
|
.TP
|
|
|
|
PTRACE_O_TRACESYSGOOD (since Linux 2.4.6)
|
2007-04-12 22:42:49 +00:00
|
|
|
When delivering syscall traps, set bit 7 in the signal number
|
|
|
|
(i.e., deliver (SIGTRAP | 0x80)
|
2006-03-25 21:28:28 +00:00
|
|
|
This makes it easy for the tracer to tell the difference
|
2007-04-12 22:42:49 +00:00
|
|
|
between normal traps and those caused by a syscall.
|
2006-03-25 21:28:28 +00:00
|
|
|
(PTRACE_O_TRACESYSGOOD may not work on all architectures.)
|
2006-03-23 22:00:08 +00:00
|
|
|
.TP
|
|
|
|
PTRACE_O_TRACEFORK (since Linux 2.5.46)
|
|
|
|
Stop the child at the next
|
2007-05-11 23:07:02 +00:00
|
|
|
.BR fork (2)
|
2007-04-12 22:42:49 +00:00
|
|
|
call with SIGTRAP | PTRACE_EVENT_FORK << 8 and automatically
|
|
|
|
start tracing the newly forked process,
|
2006-03-25 21:28:28 +00:00
|
|
|
which will start with a SIGSTOP.
|
2006-03-23 22:00:08 +00:00
|
|
|
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
|
2007-05-11 23:07:02 +00:00
|
|
|
.BR vfork (2)
|
2007-04-12 22:42:49 +00:00
|
|
|
call with SIGTRAP | PTRACE_EVENT_VFORK << 8 and automatically start
|
2006-03-25 21:28:28 +00:00
|
|
|
tracing the newly vforked process, which will start with a SIGSTOP.
|
2006-03-23 22:00:08 +00:00
|
|
|
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
|
2007-05-11 23:07:02 +00:00
|
|
|
.BR clone (2)
|
2007-04-12 22:42:49 +00:00
|
|
|
call with SIGTRAP | PTRACE_EVENT_CLONE << 8 and automatically start
|
2006-03-25 21:28:28 +00:00
|
|
|
tracing the newly cloned process, which will start with a SIGSTOP.
|
2006-03-23 22:00:08 +00:00
|
|
|
The PID for the new process can be retrieved with PTRACE_GETEVENTMSG.
|
|
|
|
This option may not catch
|
2007-05-11 23:07:02 +00:00
|
|
|
.BR clone (2)
|
2007-04-12 22:42:49 +00:00
|
|
|
calls in all cases.
|
|
|
|
If the child calls
|
2007-05-11 23:07:02 +00:00
|
|
|
.BR clone (2)
|
2006-03-23 22:00:08 +00:00
|
|
|
with the CLONE_VFORK flag, PTRACE_EVENT_VFORK will be delivered instead
|
|
|
|
if PTRACE_O_TRACEVFORK is set; otherwise if the child calls
|
2007-05-11 23:07:02 +00:00
|
|
|
.BR clone (2)
|
2006-03-23 22:00:08 +00:00
|
|
|
with the exit signal set to SIGCHLD, PTRACE_EVENT_FORK will be delivered
|
|
|
|
if PTRACE_O_TRACEFORK is set.
|
|
|
|
.TP
|
|
|
|
PTRACE_O_TRACEEXEC (since Linux 2.5.46)
|
|
|
|
Stop the child at the next
|
2007-05-11 23:07:02 +00:00
|
|
|
.BR execve (2)
|
2006-03-23 22:00:08 +00:00
|
|
|
call with SIGTRAP | PTRACE_EVENT_EXEC << 8.
|
|
|
|
.TP
|
|
|
|
PTRACE_O_TRACEVFORKDONE (since Linux 2.5.60)
|
|
|
|
Stop the child at the completion of the next
|
2007-05-11 23:07:02 +00:00
|
|
|
.BR vfork (2)
|
2006-03-23 22:00:08 +00:00
|
|
|
call with SIGTRAP | PTRACE_EVENT_VFORK_DONE << 8.
|
|
|
|
.TP
|
|
|
|
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.
|
2007-04-12 22:42:49 +00:00
|
|
|
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
|
2006-03-25 21:28:28 +00:00
|
|
|
is finished exiting.
|
2006-03-23 22:00:08 +00:00
|
|
|
Even though context is available, the tracer cannot prevent the exit from
|
|
|
|
happening at this point.
|
|
|
|
.RE
|
|
|
|
.TP
|
|
|
|
PTRACE_GETEVENTMSG (since Linux 2.5.46)
|
2007-04-12 22:42:49 +00:00
|
|
|
Retrieve a message (as an
|
|
|
|
.IR "unsigned long" )
|
2006-03-23 22:00:08 +00:00
|
|
|
about the ptrace event
|
|
|
|
that just happened, placing it in the location \fIdata\fP in the parent.
|
2007-04-12 22:42:49 +00:00
|
|
|
For PTRACE_EVENT_EXIT this is the child's exit status.
|
|
|
|
For PTRACE_EVENT_FORK, PTRACE_EVENT_VFORK and PTRACE_EVENT_CLONE this
|
|
|
|
is the PID of the new process.
|
2006-11-25 01:21:51 +00:00
|
|
|
Since Linux 2.6.18, the PID of the new process is also available
|
|
|
|
for PTRACE_EVENT_VFORK_DONE.
|
|
|
|
(\fIaddr\fP is ignored.)
|
2006-03-23 22:00:08 +00:00
|
|
|
.TP
|
2004-11-03 13:51:07 +00:00
|
|
|
PTRACE_CONT
|
2007-04-12 22:42:49 +00:00
|
|
|
Restarts the stopped child process.
|
|
|
|
If \fIdata\fP is non-zero and not
|
2004-11-03 13:51:07 +00:00
|
|
|
SIGSTOP, it is interpreted as a signal to be delivered to the child;
|
2007-04-12 22:42:49 +00:00
|
|
|
otherwise, no signal is delivered.
|
2006-03-25 21:28:28 +00:00
|
|
|
Thus, for example, the parent can control
|
2007-04-12 22:42:49 +00:00
|
|
|
whether a signal sent to the child is delivered or not.
|
2006-03-25 21:28:28 +00:00
|
|
|
(\fIaddr\fP is ignored.)
|
2004-11-03 13:51:07 +00:00
|
|
|
.TP
|
|
|
|
PTRACE_SYSCALL, PTRACE_SINGLESTEP
|
2007-04-12 22:42:49 +00:00
|
|
|
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.
|
2006-03-25 21:28:28 +00:00
|
|
|
(\fIaddr\fP is ignored.)
|
2004-11-03 13:51:07 +00:00
|
|
|
.TP
|
2006-03-23 22:00:08 +00:00
|
|
|
PTRACE_SYSEMU, PTRACE_SYSEMU_SINGLESTEP (since Linux 2.6.14)
|
|
|
|
For PTRACE_SYSEMU, continue and stop on entry to the next syscall,
|
2007-04-12 22:42:49 +00:00
|
|
|
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
|
2006-12-27 02:47:18 +00:00
|
|
|
User Mode Linux that want to emulate all the child's system calls.
|
2007-04-12 22:42:49 +00:00
|
|
|
(\fIaddr\fP and \fIdata\fP are ignored;
|
2006-03-25 21:28:28 +00:00
|
|
|
not supported on all architectures.)
|
2006-03-23 22:00:08 +00:00
|
|
|
.TP
|
2004-11-03 13:51:07 +00:00
|
|
|
PTRACE_KILL
|
2007-04-12 22:42:49 +00:00
|
|
|
Sends the child a SIGKILL to terminate it.
|
2006-03-25 21:28:28 +00:00
|
|
|
(\fIaddr\fP and \fIdata\fP are ignored.)
|
2004-11-03 13:51:07 +00:00
|
|
|
.TP
|
|
|
|
PTRACE_ATTACH
|
|
|
|
Attaches to the process specified in
|
|
|
|
.IR pid ,
|
2007-04-12 22:42:49 +00:00
|
|
|
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
|
2006-03-25 21:28:28 +00:00
|
|
|
process for most purposes (e.g., it will receive
|
2004-11-03 13:51:07 +00:00
|
|
|
notification of child events and appears in
|
|
|
|
.BR ps (1)
|
|
|
|
output as the child's parent), but a
|
|
|
|
.BR getppid (2)
|
2007-04-12 22:42:49 +00:00
|
|
|
by the child will still return the PID of the original parent.
|
|
|
|
The child is sent a SIGSTOP, but will not necessarily have stopped
|
2006-03-25 21:28:28 +00:00
|
|
|
by the completion of this call; use
|
2007-05-11 23:07:02 +00:00
|
|
|
.BR wait (2)
|
2007-04-12 22:42:49 +00:00
|
|
|
to wait for the child to stop.
|
2006-03-25 21:28:28 +00:00
|
|
|
(\fIaddr\fP and \fIdata\fP are ignored.)
|
2004-11-03 13:51:07 +00:00
|
|
|
.TP
|
|
|
|
PTRACE_DETACH
|
2007-04-12 22:42:49 +00:00
|
|
|
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
|
2006-03-25 21:28:28 +00:00
|
|
|
detached in this way regardless of which method was used to initiate
|
2007-04-12 22:42:49 +00:00
|
|
|
tracing.
|
2006-03-25 21:28:28 +00:00
|
|
|
(\fIaddr\fP is ignored.)
|
2004-11-03 13:51:07 +00:00
|
|
|
.SH NOTES
|
|
|
|
Although arguments to
|
2005-10-19 06:54:38 +00:00
|
|
|
.BR ptrace ()
|
2007-04-12 22:42:49 +00:00
|
|
|
are interpreted according to the prototype given,
|
2006-03-25 21:28:28 +00:00
|
|
|
GNU libc currently declares
|
2005-10-19 06:54:38 +00:00
|
|
|
.BR ptrace ()
|
2007-04-12 22:42:49 +00:00
|
|
|
as a variadic function with only the \fIrequest\fP argument fixed.
|
|
|
|
This means that unneeded trailing arguments may be omitted,
|
2006-03-25 21:28:28 +00:00
|
|
|
though doing so makes use of undocumented
|
2005-11-02 10:53:26 +00:00
|
|
|
.BR gcc (1)
|
2004-11-03 13:51:07 +00:00
|
|
|
behavior.
|
|
|
|
.LP
|
|
|
|
.BR init (8),
|
2005-07-19 06:32:54 +00:00
|
|
|
the process with PID 1, may not be traced.
|
2004-11-03 13:51:07 +00:00
|
|
|
.LP
|
|
|
|
The layout of the contents of memory and the USER area are quite OS- and
|
|
|
|
architecture-specific.
|
|
|
|
.LP
|
2007-04-12 22:42:49 +00:00
|
|
|
The size of a "word" is determined by the OS variant
|
2006-03-25 21:28:28 +00:00
|
|
|
(e.g., for 32-bit Linux it's 32 bits, etc.).
|
2004-11-03 13:51:07 +00:00
|
|
|
.LP
|
2007-04-12 22:42:49 +00:00
|
|
|
Tracing causes a few subtle differences in the semantics of
|
2006-03-25 21:28:28 +00:00
|
|
|
traced processes.
|
2007-04-12 22:42:49 +00:00
|
|
|
For example, if a process is attached to with PTRACE_ATTACH,
|
|
|
|
its original parent can no longer receive notification via
|
2007-05-11 23:07:02 +00:00
|
|
|
.BR wait (2)
|
2007-04-12 22:42:49 +00:00
|
|
|
when it stops, and there is no way for the new parent to
|
2006-03-25 21:28:28 +00:00
|
|
|
effectively simulate this notification.
|
2004-11-03 13:51:07 +00:00
|
|
|
.LP
|
2007-04-12 22:42:49 +00:00
|
|
|
When the parent receives an event with PTRACE_EVENT_* set,
|
2006-12-16 19:23:29 +00:00
|
|
|
the child is not in the normal signal delivery path.
|
|
|
|
This means the parent cannot do
|
2006-12-16 20:56:09 +00:00
|
|
|
.BR ptrace (PTRACE_CONT)
|
2006-12-16 19:18:56 +00:00
|
|
|
with a signal or
|
2006-12-16 20:56:09 +00:00
|
|
|
.BR ptrace (PTRACE_KILL).
|
2007-05-11 23:07:02 +00:00
|
|
|
.BR kill (2)
|
2006-12-16 19:18:56 +00:00
|
|
|
with a SIGKILL signal can be used instead to kill the child process
|
|
|
|
after receiving one of these messages.
|
|
|
|
.LP
|
2004-11-03 13:51:07 +00:00
|
|
|
This page documents the way the
|
2005-10-19 06:54:38 +00:00
|
|
|
.BR ptrace ()
|
2007-04-12 22:42:49 +00:00
|
|
|
call works currently in Linux.
|
|
|
|
Its behavior differs noticeably on other flavors of Unix.
|
2006-03-25 21:28:28 +00:00
|
|
|
In any case, use of
|
2005-10-19 06:54:38 +00:00
|
|
|
.BR ptrace ()
|
2004-11-03 13:51:07 +00:00
|
|
|
is highly OS- and architecture-specific.
|
|
|
|
.LP
|
2007-04-12 22:42:49 +00:00
|
|
|
The SunOS man page describes
|
2005-10-19 06:54:38 +00:00
|
|
|
.BR ptrace ()
|
2007-04-12 22:42:49 +00:00
|
|
|
as "unique and arcane", which it is.
|
2006-03-25 21:28:28 +00:00
|
|
|
The proc-based debugging interface
|
2004-11-03 13:51:07 +00:00
|
|
|
present in Solaris 2 implements a superset of
|
2005-10-19 06:54:38 +00:00
|
|
|
.BR ptrace ()
|
2004-11-03 13:51:07 +00:00
|
|
|
functionality in a more powerful and uniform way.
|
|
|
|
.SH "RETURN VALUE"
|
2007-04-12 22:42:49 +00:00
|
|
|
On success, PTRACE_PEEK* requests return the requested data,
|
|
|
|
while other requests return zero.
|
2006-03-25 21:28:28 +00:00
|
|
|
On error, all requests return \-1, and
|
2005-11-02 11:34:24 +00:00
|
|
|
.I errno
|
2007-04-12 22:42:49 +00:00
|
|
|
is set appropriately.
|
2006-03-25 21:28:28 +00:00
|
|
|
Since the value returned by a successful PTRACE_PEEK*
|
2004-11-03 13:51:07 +00:00
|
|
|
request may be \-1, the caller must check
|
|
|
|
.I errno
|
|
|
|
after such requests to determine whether or not an error occurred.
|
2006-03-23 22:00:08 +00:00
|
|
|
.SH BUGS
|
2007-04-12 22:42:49 +00:00
|
|
|
On hosts with 2.6 kernel headers, PTRACE_SETOPTIONS is declared
|
|
|
|
with a different value than the one for 2.4.
|
2006-03-25 21:28:28 +00:00
|
|
|
This leads to applications compiled with such
|
2006-03-23 22:00:08 +00:00
|
|
|
headers failing when run on 2.4 kernels.
|
|
|
|
This can be worked around by redefining PTRACE_SETOPTIONS to
|
|
|
|
PTRACE_OLDSETOPTIONS, if that is defined.
|
2004-11-03 13:51:07 +00:00
|
|
|
.SH ERRORS
|
|
|
|
.TP
|
|
|
|
.B EBUSY
|
2007-04-12 22:42:49 +00:00
|
|
|
(i386 only) There was an error with allocating or freeing a debug
|
2006-03-25 21:28:28 +00:00
|
|
|
register.
|
2004-11-03 13:51:07 +00:00
|
|
|
.TP
|
|
|
|
.B EFAULT
|
2007-04-12 22:42:49 +00:00
|
|
|
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
|
2006-03-25 21:28:28 +00:00
|
|
|
will return EIO or EFAULT more or less arbitrarily.
|
2004-11-03 13:51:07 +00:00
|
|
|
.TP
|
2006-03-23 22:00:08 +00:00
|
|
|
.B EINVAL
|
|
|
|
An attempt was made to set an invalid option.
|
|
|
|
.TP
|
2004-11-03 13:51:07 +00:00
|
|
|
.B EIO
|
2007-04-12 22:42:49 +00:00
|
|
|
\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,
|
2006-03-25 21:28:28 +00:00
|
|
|
or an invalid signal was specified during a restart request.
|
2004-11-03 13:51:07 +00:00
|
|
|
.TP
|
|
|
|
.B EPERM
|
2007-04-12 22:42:49 +00:00
|
|
|
The specified process cannot be traced.
|
|
|
|
This could be because the
|
2004-11-03 13:51:07 +00:00
|
|
|
parent has insufficient privileges (the required capability is
|
|
|
|
.BR CAP_SYS_PTRACE );
|
|
|
|
non-root processes cannot trace processes that they
|
2007-04-12 22:42:49 +00:00
|
|
|
cannot send signals to or those running
|
2006-03-25 21:28:28 +00:00
|
|
|
set-user-ID/set-group-ID programs, for obvious reasons.
|
2005-07-18 14:25:42 +00:00
|
|
|
Alternatively, the process may already be being traced, or be
|
2007-04-12 22:42:49 +00:00
|
|
|
.BR init
|
2005-07-19 06:32:54 +00:00
|
|
|
(PID 1).
|
2004-11-03 13:51:07 +00:00
|
|
|
.TP
|
|
|
|
.B ESRCH
|
2007-04-12 22:42:49 +00:00
|
|
|
The specified process does not exist, or is not currently being traced
|
2006-03-25 21:28:28 +00:00
|
|
|
by the caller, or is not stopped (for requests that require that).
|
2004-11-03 13:51:07 +00:00
|
|
|
.SH "CONFORMING TO"
|
2006-08-03 13:57:17 +00:00
|
|
|
SVr4, 4.3BSD
|
2004-11-03 13:51:07 +00:00
|
|
|
.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)
|