1 .\" Hey Emacs! This file is -*- nroff -*- source.
3 .\" Copyright (c) 1993 Michael Haardt
4 .\" (michael@moria.de),
5 .\" Fri Apr 2 11:32:09 MET DST 1993
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
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.
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.
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.
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,
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 <mtk.manpages@gmail.com>
36 .\" Added notes on capability requirements
38 .\" 2006-03-24, Chuck Ebbert <76306.1226@compuserve.com>
39 .\" Added PTRACE_SETOPTIONS, PTRACE_GETEVENTMSG, PTRACE_GETSIGINFO,
40 .\" PTRACE_SETSIGINFO, PTRACE_SYSEMU, PTRACE_SYSEMU_SINGLESTEP
41 .\" (Thanks to Blaisorblade, Daniel Jacobowitz and others who helped.)
43 .TH PTRACE 2 2009-03-30 "Linux" "Linux Programmer's Manual"
45 ptrace \- process trace
48 .B #include <sys/ptrace.h>
50 .BI "long ptrace(enum __ptrace_request " request ", pid_t " pid ", "
51 .BI " void *" addr ", void *" data );
56 system call provides a means by which a parent process may observe
57 and control the execution of another process,
58 and examine and change its core image and registers.
59 It is primarily used to implement breakpoint debugging and system
62 The parent can initiate a trace by calling
64 and having the resulting child do a
66 followed (typically) by an
68 Alternatively, the parent may commence trace of an existing process using
71 While being traced, the child will stop each time a signal is delivered,
72 even if the signal is being ignored.
75 which has its usual effect.)
76 The parent will be notified at its next
78 and may inspect and modify the child process while it is stopped.
79 The parent then causes the child to continue,
80 optionally ignoring the delivered signal
81 (or even delivering a different signal instead).
83 When the parent is finished tracing, it can terminate the child with
85 or cause it to continue executing in a normal, untraced mode
89 The value of \fIrequest\fP determines the action to be performed:
92 Indicates that this process is to be traced by its parent.
96 delivered to this process will cause it to stop and its
97 parent to be notified via
99 Also, all subsequent calls to
101 by this process will cause a
104 giving the parent a chance to gain control before the new program
106 A process probably shouldn't make this request if its parent
107 isn't expecting to trace it.
108 (\fIpid\fP, \fIaddr\fP, and \fIdata\fP are ignored.)
110 The above request is used only by the child process;
111 the rest are used only by the parent.
112 In the following requests, \fIpid\fP specifies the child process
114 For requests other than
116 the child process must
119 .BR PTRACE_PEEKTEXT ", " PTRACE_PEEKDATA
120 Reads a word at the location
122 in the child's memory, returning the word as the result of the
125 Linux does not have separate text and data address spaces, so the two
126 requests are currently equivalent.
127 (The argument \fIdata\fP is ignored.)
130 .\" PTRACE_PEEKUSR in kernel source, but glibc uses PTRACE_PEEKUSER,
131 .\" and that is the name that seems common on other systems.
132 Reads a word at offset
134 in the child's USER area,
135 which holds the registers and other information about the process
136 (see \fI<sys/user.h>\fP).
137 The word is returned as the result of the
140 Typically the offset must be word-aligned, though this might vary by
143 (\fIdata\fP is ignored.)
145 .BR PTRACE_POKETEXT ", " PTRACE_POKEDATA
150 in the child's memory.
151 As above, the two requests are currently equivalent.
154 .\" PTRACE_POKEUSR in kernel source, but glibc uses PTRACE_POKEUSER,
155 .\" and that is the name that seems common on other systems.
160 in the child's USER area.
161 As above, the offset must typically be word-aligned.
162 In order to maintain the integrity of the kernel,
163 some modifications to the USER area are disallowed.
165 .BR PTRACE_GETREGS ", " PTRACE_GETFPREGS
166 Copies the child's general purpose or floating-point registers,
167 respectively, to location \fIdata\fP in the parent.
168 See \fI<sys/user.h>\fP for information on
169 the format of this data.
170 (\fIaddr\fP is ignored.)
172 .BR PTRACE_GETSIGINFO " (since Linux 2.3.99-pre6)"
173 Retrieve information about the signal that caused the stop.
174 Copies a \fIsiginfo_t\fP structure (see
176 from the child to location \fIdata\fP in the parent.
177 (\fIaddr\fP is ignored.)
179 .BR PTRACE_SETREGS ", " PTRACE_SETFPREGS
180 Copies the child's general purpose or floating-point registers,
181 respectively, from location \fIdata\fP in the parent.
183 .BR PTRACE_POKEUSER ,
185 purpose register modifications may be disallowed.
186 (\fIaddr\fP is ignored.)
188 .BR PTRACE_SETSIGINFO " (since Linux 2.3.99-pre6)"
189 Set signal information.
190 Copies a \fIsiginfo_t\fP structure from location \fIdata\fP in the
192 This will only affect signals that would normally be delivered to
193 the child and were caught by the tracer.
194 It may be difficult to tell
195 these normal signals from synthetic signals generated by
198 (\fIaddr\fP is ignored.)
200 .BR PTRACE_SETOPTIONS " (since Linux 2.4.6; see BUGS for caveats)"
201 Sets ptrace options from \fIdata\fP in the parent.
202 (\fIaddr\fP is ignored.)
203 \fIdata\fP is interpreted
204 as a bit mask of options, which are specified by the following flags:
207 .BR PTRACE_O_TRACESYSGOOD " (since Linux 2.4.6)"
208 When delivering syscall traps, set bit 7 in the signal number
209 (i.e., deliver \fI(SIGTRAP | 0x80)\fP
210 This makes it easy for the tracer to tell the difference
211 between normal traps and those caused by a syscall.
212 .RB ( PTRACE_O_TRACESYSGOOD
213 may not work on all architectures.)
215 .BR PTRACE_O_TRACEFORK " (since Linux 2.5.46)"
216 Stop the child at the next
218 call with \fISIGTRAP | PTRACE_EVENT_FORK\ <<\ 8\fP and automatically
219 start tracing the newly forked process,
220 which will start with a
222 The PID for the new process can be retrieved with
223 .BR PTRACE_GETEVENTMSG .
225 .BR PTRACE_O_TRACEVFORK " (since Linux 2.5.46)"
226 Stop the child at the next
228 call with \fISIGTRAP | PTRACE_EVENT_VFORK\ <<\ 8\fP and automatically start
229 tracing the newly vforked process, which will start with a
231 The PID for the new process can be retrieved with
232 .BR PTRACE_GETEVENTMSG .
234 .BR PTRACE_O_TRACECLONE " (since Linux 2.5.46)"
235 Stop the child at the next
237 call with \fISIGTRAP | PTRACE_EVENT_CLONE\ <<\ 8\fP and automatically start
238 tracing the newly cloned process, which will start with a
240 The PID for the new process can be retrieved with
241 .BR PTRACE_GETEVENTMSG .
242 This option may not catch
250 .B PTRACE_EVENT_VFORK
251 will be delivered instead
253 .B PTRACE_O_TRACEVFORK
254 is set; otherwise if the child calls
256 with the exit signal set to
261 .B PTRACE_O_TRACEFORK
264 .BR PTRACE_O_TRACEEXEC " (since Linux 2.5.46)"
265 Stop the child at the next
267 call with \fISIGTRAP | PTRACE_EVENT_EXEC\ <<\ 8\fP.
269 .BR PTRACE_O_TRACEVFORKDONE " (since Linux 2.5.60)"
270 Stop the child at the completion of the next
272 call with \fISIGTRAP | PTRACE_EVENT_VFORK_DONE\ <<\ 8\fP.
274 .BR PTRACE_O_TRACEEXIT " (since Linux 2.5.60)"
275 Stop the child at exit with \fISIGTRAP | PTRACE_EVENT_EXIT\ <<\ 8\fP.
276 The child's exit status can be retrieved with
277 .BR PTRACE_GETEVENTMSG .
278 This stop will be done early during process exit when registers
279 are still available, allowing the tracer to see where the exit occurred,
280 whereas the normal exit notification is done after the process
282 Even though context is available, the tracer cannot prevent the exit from
283 happening at this point.
286 .BR PTRACE_GETEVENTMSG " (since Linux 2.5.46)"
287 Retrieve a message (as an
288 .IR "unsigned long" )
289 about the ptrace event
290 that just happened, placing it in the location \fIdata\fP in the parent.
293 this is the child's exit status.
295 .BR PTRACE_EVENT_FORK ,
296 .B PTRACE_EVENT_VFORK
298 .B PTRACE_EVENT_CLONE
300 is the PID of the new process.
301 Since Linux 2.6.18, the PID of the new process is also available
303 .BR PTRACE_EVENT_VFORK_DONE .
304 (\fIaddr\fP is ignored.)
307 Restarts the stopped child process.
308 If \fIdata\fP is nonzero and not
310 it is interpreted as a signal to be delivered to the child;
311 otherwise, no signal is delivered.
312 Thus, for example, the parent can control
313 whether a signal sent to the child is delivered or not.
314 (\fIaddr\fP is ignored.)
316 .BR PTRACE_SYSCALL ", " PTRACE_SINGLESTEP
317 Restarts the stopped child as for
320 the child to be stopped at the next entry to or exit from a system call,
321 or after execution of a single instruction, respectively.
322 (The child will also, as usual, be stopped upon receipt of a signal.)
323 From the parent's perspective, the child will appear to have been
324 stopped by receipt of a
328 for example, the idea is to inspect
329 the arguments to the system call at the first stop,
332 and inspect the return value of
333 the system call at the second stop.
336 argument is treated as for
338 (\fIaddr\fP is ignored.)
340 .BR PTRACE_SYSEMU ", " PTRACE_SYSEMU_SINGLESTEP " (since Linux 2.6.14)"
343 continue and stop on entry to the next syscall,
344 which will not be executed.
346 .BR PTRACE_SYSEMU_SINGLESTEP ,
348 but also singlestep if not a syscall.
349 This call is used by programs like
350 User Mode Linux that want to emulate all the child's system calls.
353 argument is treated as for
355 (\fIaddr\fP is ignored;
356 not supported on all architectures.)
362 (\fIaddr\fP and \fIdata\fP are ignored.)
365 Attaches to the process specified in
367 making it a traced "child" of the calling process;
368 the behavior of the child is as if it had done a
370 The calling process actually becomes the parent of the child
371 process for most purposes (e.g., it will receive
372 notification of child events and appears in
374 output as the child's parent), but a
376 by the child will still return the PID of the original parent.
379 but will not necessarily have stopped
380 by the completion of this call; use
382 to wait for the child to stop.
383 (\fIaddr\fP and \fIdata\fP are ignored.)
386 Restarts the stopped child as for
389 from the process, undoing the reparenting effect of
393 Although perhaps not intended, under Linux a traced child can be
394 detached in this way regardless of which method was used to initiate
396 (\fIaddr\fP is ignored.)
400 requests return the requested data,
401 while other requests return zero.
402 On error, all requests return \-1, and
404 is set appropriately.
405 Since the value returned by a successful
407 request may be \-1, the caller must check
409 after such requests to determine whether or not an error occurred.
413 (i386 only) There was an error with allocating or freeing a debug
417 There was an attempt to read from or write to an invalid area in
418 the parent's or child's memory,
419 probably because the area wasn't mapped or accessible.
420 Unfortunately, under Linux, different variations of this fault
425 more or less arbitrarily.
428 An attempt was made to set an invalid option.
431 \fIrequest\fP is invalid, or an attempt was made to read from or
432 write to an invalid area in the parent's or child's memory,
433 or there was a word-alignment violation,
434 or an invalid signal was specified during a restart request.
437 The specified process cannot be traced.
438 This could be because the
439 parent has insufficient privileges (the required capability is
440 .BR CAP_SYS_PTRACE );
441 unprivileged processes cannot trace processes that they
442 cannot send signals to or those running
443 set-user-ID/set-group-ID programs, for obvious reasons.
444 Alternatively, the process may already be being traced, or be
449 The specified process does not exist, or is not currently being traced
450 by the caller, or is not stopped (for requests that require that).
454 Although arguments to
456 are interpreted according to the prototype given,
457 glibc currently declares
459 as a variadic function with only the \fIrequest\fP argument fixed.
460 This means that unneeded trailing arguments may be omitted,
461 though doing so makes use of undocumented
466 the process with PID 1, may not be traced.
468 The layout of the contents of memory and the USER area are quite OS- and
469 architecture-specific.
470 The offset supplied, and the data returned,
471 might not entirely match with the definition of
473 .\" See http://lkml.org/lkml/2008/5/8/375
475 The size of a "word" is determined by the OS variant
476 (e.g., for 32-bit Linux it is 32 bits, etc.).
478 Tracing causes a few subtle differences in the semantics of
480 For example, if a process is attached to with
482 its original parent can no longer receive notification via
484 when it stops, and there is no way for the new parent to
485 effectively simulate this notification.
487 When the parent receives an event with
490 the child is not in the normal signal delivery path.
491 This means the parent cannot do
492 .BR ptrace (PTRACE_CONT)
494 .BR ptrace (PTRACE_KILL).
498 signal can be used instead to kill the child process
499 after receiving one of these messages.
501 This page documents the way the
503 call works currently in Linux.
504 Its behavior differs noticeably on other flavors of UNIX.
507 is highly OS- and architecture-specific.
509 The SunOS man page describes
511 as "unique and arcane", which it is.
512 The proc-based debugging interface
513 present in Solaris 2 implements a superset of
515 functionality in a more powerful and uniform way.
517 On hosts with 2.6 kernel headers,
520 with a different value than the one for 2.4.
521 This leads to applications compiled with such
522 headers failing when run on 2.4 kernels.
523 This can be worked around by redefining
526 .BR PTRACE_OLDSETOPTIONS ,
OSDN Git Service
