man2/ptrace.2

   1 .\" Hey Emacs! This file is -*- nroff -*- source.
   2 .\"
   3 .\" Copyright (c) 1993 Michael Haardt
   4 .\" (michael@moria.de),
   5 .\" Fri Apr  2 11:32:09 MET DST 1993
   6 .\"
   7 .\" changes Copyright 1999 Mike Coleman (mkc@acm.org)
   8 .\" -- major revision to fully document ptrace semantics per recent Linux
   9 .\"    kernel (2.2.10) and glibc (2.1.2)
  10 .\" Sun Nov  7 03:18:35 CST 1999
  11 .\"
  12 .\" This is free documentation; you can redistribute it and/or
  13 .\" modify it under the terms of the GNU General Public License as
  14 .\" published by the Free Software Foundation; either version 2 of
  15 .\" the License, or (at your option) any later version.
  16 .\"
  17 .\" The GNU General Public License's references to "object code"
  18 .\" and "executables" are to be interpreted as the output of any
  19 .\" document formatting or typesetting system, including
  20 .\" intermediate and printed output.
  21 .\"
  22 .\" This manual is distributed in the hope that it will be useful,
  23 .\" but WITHOUT ANY WARRANTY; without even the implied warranty of
  24 .\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  25 .\" GNU General Public License for more details.
  26 .\"
  27 .\" You should have received a copy of the GNU General Public
  28 .\" License along with this manual; if not, write to the Free
  29 .\" Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111,
  30 .\" USA.
  31 .\"
  32 .\" Modified Fri Jul 23 23:47:18 1993 by Rik Faith <faith@cs.unc.edu>
  33 .\" Modified Fri Jan 31 16:46:30 1997 by Eric S. Raymond <esr@thyrsus.com>
  34 .\" Modified Thu Oct  7 17:28:49 1999 by Andries Brouwer <aeb@cwi.nl>
  35 .\" Modified, 27 May 2004, Michael Kerrisk <mtk16@ext.canterbury.ac.nz>
  36 .\"     Added notes on capability requirements
  37 .\"
  38 .TH PTRACE 2 2004-05-27 "Linux 2.6.6" "Linux Programmer's Manual"
  39 .SH NAME
  40 ptrace \- process trace
  41 .SH SYNOPSIS
  42 .B #include <sys/ptrace.h>
  43 .sp
  44 .BI "long ptrace(enum __ptrace_request " request ", pid_t " pid ", void *" addr ", void *" data );
  45 .SH DESCRIPTION
  46 The
  47 .B ptrace
  48 system call provides a means by which a parent process may observe and control
  49 the execution of another process, and examine and change its core image and
  50 registers.  It is primarily used to implement breakpoint debugging and system
  51 call tracing.
  52 .LP
  53 The parent can initiate a trace by calling
  54 .BR fork (2)
  55 and having the resulting child do a PTRACE_TRACEME, followed (typically) by an
  56 .BR exec (3).
  57 Alternatively, the parent may commence trace of an existing process using
  58 PTRACE_ATTACH.
  59 .LP
  60 While being traced, the child will stop each time a signal is delivered, even
  61 if the signal is being ignored.  (The exception is SIGKILL, which has its
  62 usual effect.)  The parent will be notified at its next
  63 .BR wait (2)
  64 and may inspect and modify the child process while it is stopped.  The parent
  65 then causes the child to continue, optionally ignoring the delivered signal
  66 (or even delivering a different signal instead).
  67 .LP
  68 When the parent is finished tracing, it can terminate the child with
  69 PTRACE_KILL or cause it to continue executing in a normal, untraced mode
  70 via PTRACE_DETACH.
  71 .LP
  72 The value of \fIrequest\fP determines the action to be performed:
  73 .TP
  74 PTRACE_TRACEME
  75 Indicates that this process is to be traced by its parent.  Any signal
  76 (except SIGKILL) delivered to this process will cause it to stop and its
  77 parent to be notified via
  78 .BR wait.
  79 Also, all subsequent calls to
  80 .BR exec
  81 by this process will cause a SIGTRAP to be sent to it, giving the parent a
  82 chance to gain control before the new program begins execution.  A process
  83 probably shouldn't make this request if its parent isn't expecting to trace
  84 it.  (\fIpid\fP, \fIaddr\fP, and \fIdata\fP are ignored.)
  85 .LP
  86 The above request is used only by the child process; the rest are used only by
  87 the parent.  In the following requests, \fIpid\fP specifies the child process
  88 to be acted on.  For requests other than PTRACE_KILL, the child process must
  89 be stopped.
  90 .TP
  91 PTRACE_PEEKTEXT, PTRACE_PEEKDATA
  92 Reads a word at the location
  93 .IR addr
  94 in the child's memory, returning the word as the result of the
  95 .B ptrace
  96 call.  Linux does not have separate text and data address spaces, so the two
  97 requests are currently equivalent.  (The argument \fIdata\fP is ignored.)
  98 .TP
  99 PTRACE_PEEKUSR
 100 Reads a word at offset
 101 .I addr
 102 in the child's
 103 .B USER
 104 area, which holds the registers and other information about the process (see
 105 <linux/user.h> and <sys/user.h>).  The word is returned as the result of the
 106 .B ptrace
 107 call.  Typically the offset must be word-aligned, though this might vary by
 108 architecture.  (\fIdata\fP is ignored.)
 109 .TP
 110 PTRACE_POKETEXT, PTRACE_POKEDATA
 111 Copies the word
 112 .IR data
 113 to location
 114 .IR addr
 115 in the child's memory.  As above, the two requests are currently equivalent.
 116 .TP
 117 PTRACE_POKEUSR
 118 Copies the word
 119 .IR data
 120 to offset
 121 .I addr
 122 in the child's
 123 .B USER
 124 area.  As above, the offset must typically be word-aligned.  In order to
 125 maintain the integrity of the kernel, some modifications to the
 126 .B USER
 127 area are disallowed.
 128 .TP
 129 PTRACE_GETREGS, PTRACE_GETFPREGS
 130 Copies the child's general purpose or floating-point registers, respectively,
 131 to location \fIdata\fP in the parent.  See <linux/user.h> for information on
 132 the format of this data.  (\fIaddr\fP is ignored.)
 133 .TP
 134 PTRACE_SETREGS, PTRACE_SETFPREGS
 135 Copies the child's general purpose or floating-point registers, respectively,
 136 from location \fIdata\fP in the parent.  As for PTRACE_POKEUSER, some general
 137 purpose register modifications may be disallowed.  (\fIaddr\fP is ignored.)
 138 .TP
 139 PTRACE_CONT
 140 Restarts the stopped child process.  If \fIdata\fP is non-zero and not
 141 SIGSTOP, it is interpreted as a signal to be delivered to the child;
 142 otherwise, no signal is delivered.  Thus, for example, the parent can control
 143 whether a signal sent to the child is delivered or not.  (\fIaddr\fP is
 144 ignored.)
 145 .TP
 146 PTRACE_SYSCALL, PTRACE_SINGLESTEP
 147 Restarts the stopped child as for PTRACE_CONT, but arranges for the child to
 148 be stopped at the next entry to or exit from a system call, or after execution
 149 of a single instruction, respectively.  (The child will also, as usual, be
 150 stopped upon receipt of a signal.)  From the parent's perspective, the child
 151 will appear to have been stopped by receipt of a SIGTRAP.  So, for
 152 PTRACE_SYSCALL, for example, the idea is to inspect the arguments to the
 153 system call at the first stop, then do another PTRACE_SYSCALL and inspect the
 154 return value of the system call at the second stop.  (\fIaddr\fP is ignored.)
 155 .TP
 156 PTRACE_KILL
 157 Sends the child a SIGKILL to terminate it.  (\fIaddr\fP and \fIdata\fP are
 158 ignored.)
 159 .TP
 160 PTRACE_ATTACH
 161 Attaches to the process specified in
 162 .IR pid ,
 163 making it a traced "child" of the current process; the behavior of the child
 164 is as if it had done a PTRACE_TRACEME.  The current process actually becomes
 165 the parent of the child process for most purposes (e.g., it will receive
 166 notification of child events and appears in
 167 .BR ps (1)
 168 output as the child's parent), but a
 169 .BR getppid (2)
 170 by the child will still return the pid of the original parent.  The child is
 171 sent a SIGSTOP, but will not necessarily have stopped by the completion of
 172 this call; use
 173 .BR wait
 174 to wait for the child to stop.  (\fIaddr\fP and \fIdata\fP are ignored.)
 175 .TP
 176 PTRACE_DETACH
 177 Restarts the stopped child as for PTRACE_CONT, but first detaches from the
 178 process, undoing the reparenting effect of PTRACE_ATTACH, and the effects of
 179 PTRACE_TRACEME.  Although perhaps not intended, under Linux a traced child
 180 can be detached in this way regardless of which method was used to initiate
 181 tracing.  (\fIaddr\fP is ignored.)
 182 .SH NOTES
 183 Although arguments to
 184 .B ptrace
 185 are interpreted according to the prototype given, GNU libc currently declares
 186 .B ptrace
 187 as a variadic function with only the \fIrequest\fP argument fixed.  This means
 188 that unneeded trailing arguments may be omitted, though doing so makes use of
 189 undocumented
 190 .B gcc(1)
 191 behavior.
 192 .LP
 193 .BR init (8),
 194 the process with pid 1, may not be traced.
 195 .LP
 196 The layout of the contents of memory and the USER area are quite OS- and
 197 architecture-specific.
 198 .LP
 199 The size of a "word" is determined by the OS variant (e.g., for 32-bit Linux
 200 it's 32 bits, etc.).
 201 .LP
 202 Tracing causes a few subtle differences in the semantics of traced processes.
 203 For example, if a process is attached to with PTRACE_ATTACH, its original
 204 parent can no longer receive notification via
 205 .BR wait
 206 when it stops, and there is no way for the new parent to effectively simulate
 207 this notification.
 208 .LP
 209 This page documents the way the
 210 .B ptrace
 211 call works currently in Linux.  Its behavior differs noticeably on other
 212 flavors of Unix.  In any case, use of
 213 .B ptrace
 214 is highly OS- and architecture-specific.
 215 .LP
 216 The SunOS man page describes
 217 .B ptrace
 218 as "unique and arcane", which it is.  The proc-based debugging interface
 219 present in Solaris 2 implements a superset of
 220 .B ptrace
 221 functionality in a more powerful and uniform way.
 222 .SH "RETURN VALUE"
 223 On success, PTRACE_PEEK* requests return the requested data, while other requests
 224 return zero.  On error, all requests return \-1, and
 225 .IR errno (3)
 226 is set appropriately.  Since the value returned by a successful PTRACE_PEEK*
 227 request may be \-1, the caller must check
 228 .I errno
 229 after such requests to determine whether or not an error occurred.
 230 .SH ERRORS
 231 .TP
 232 .B EBUSY
 233 (i386 only) There was an error with allocating or freeing a debug register.
 234 .TP
 235 .B EFAULT
 236 There was an attempt to read from or write to an invalid area in the parent's
 237 or child's memory, probably because the area wasn't mapped or accessible.
 238 Unfortunately, under Linux, different variations of this fault will return EIO
 239 or EFAULT more or less arbitrarily.
 240 .TP
 241 .B EIO
 242 \fIrequest\fP is invalid, or an attempt was made to read from or write to an
 243 invalid area in the parent's or child's memory, or there was a word-alignment
 244 violation, or an invalid signal was specified during a restart request.
 245 .TP
 246 .B EPERM
 247 The specified process cannot be traced.  This could be because the
 248 parent has insufficient privileges (the required capability is
 249 .BR CAP_SYS_PTRACE );
 250 non-root processes cannot trace processes that they
 251 cannot send signals to or those running setuid/setgid programs, for obvious
 252 reasons.  Alternatively, the process may already be being traced, or be
 253 .BR init
 254 (pid 1).
 255 .TP
 256 .B ESRCH
 257 The specified process does not exist, or is not currently being traced by the
 258 caller, or is not stopped (for requests that require that).
 259 .SH "CONFORMING TO"
 260 SVr4, SVID EXT, AT&T, X/OPEN, BSD 4.3
 261 .SH "SEE ALSO"
 262 .BR gdb (1),
 263 .BR strace (1),
 264 .BR execve (2),
 265 .BR fork (2),
 266 .BR signal (2),
 267 .BR wait (2),
 268 .BR exec (3),
 269 .BR capabilities (7)