]>
Commit | Line | Data |
---|---|---|
fea681da MK |
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 | |
c13182ef | 9 | .\" kernel (2.2.10) and glibc (2.1.2) |
fea681da MK |
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> | |
c11b1abf | 35 | .\" Modified, 27 May 2004, Michael Kerrisk <mtk.manpages@gmail.com> |
fea681da MK |
36 | .\" Added notes on capability requirements |
37 | .\" | |
44b35ee0 MK |
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.) | |
42 | .\" | |
a5b9e015 | 43 | .TH PTRACE 2 2007-11-15 "Linux" "Linux Programmer's Manual" |
fea681da MK |
44 | .SH NAME |
45 | ptrace \- process trace | |
46 | .SH SYNOPSIS | |
44b35ee0 | 47 | .nf |
fea681da MK |
48 | .B #include <sys/ptrace.h> |
49 | .sp | |
44b35ee0 MK |
50 | .BI "long ptrace(enum __ptrace_request " request ", pid_t " pid ", " |
51 | .BI " void *" addr ", void *" data ); | |
52 | .fi | |
fea681da MK |
53 | .SH DESCRIPTION |
54 | The | |
e511ffb6 | 55 | .BR ptrace () |
c13182ef MK |
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. | |
e63ad01d | 59 | It is primarily used to implement breakpoint debugging and system |
fea681da MK |
60 | call tracing. |
61 | .LP | |
62 | The parent can initiate a trace by calling | |
c13182ef | 63 | .BR fork (2) |
8bd58774 MK |
64 | and having the resulting child do a |
65 | .BR PTRACE_TRACEME , | |
e63ad01d | 66 | followed (typically) by an |
fea681da MK |
67 | .BR exec (3). |
68 | Alternatively, the parent may commence trace of an existing process using | |
8bd58774 | 69 | .BR PTRACE_ATTACH . |
fea681da | 70 | .LP |
c13182ef MK |
71 | While being traced, the child will stop each time a signal is delivered, |
72 | even if the signal is being ignored. | |
8bd58774 MK |
73 | (The exception is |
74 | .BR SIGKILL , | |
75 | which has its usual effect.) | |
e63ad01d | 76 | The parent will be notified at its next |
fea681da | 77 | .BR wait (2) |
c13182ef MK |
78 | and may inspect and modify the child process while it is stopped. |
79 | The parent then causes the child to continue, | |
e63ad01d | 80 | optionally ignoring the delivered signal |
fea681da MK |
81 | (or even delivering a different signal instead). |
82 | .LP | |
83 | When the parent is finished tracing, it can terminate the child with | |
8bd58774 MK |
84 | .B PTRACE_KILL |
85 | or cause it to continue executing in a normal, untraced mode | |
86 | via | |
87 | .BR PTRACE_DETACH . | |
fea681da MK |
88 | .LP |
89 | The value of \fIrequest\fP determines the action to be performed: | |
90 | .TP | |
8bd58774 | 91 | .B PTRACE_TRACEME |
c13182ef MK |
92 | Indicates that this process is to be traced by its parent. |
93 | Any signal | |
8bd58774 MK |
94 | (except |
95 | .BR SIGKILL ) | |
96 | delivered to this process will cause it to stop and its | |
fea681da | 97 | parent to be notified via |
0bfa087b | 98 | .BR wait (2). |
fea681da | 99 | Also, all subsequent calls to |
0bfa087b | 100 | .BR execve (2) |
8bd58774 MK |
101 | by this process will cause a |
102 | .B SIGTRAP | |
103 | to be sent to it, | |
c13182ef MK |
104 | giving the parent a chance to gain control before the new program |
105 | begins execution. | |
106 | A process probably shouldn't make this request if its parent | |
107 | isn't expecting to trace it. | |
e63ad01d | 108 | (\fIpid\fP, \fIaddr\fP, and \fIdata\fP are ignored.) |
fea681da | 109 | .LP |
c13182ef MK |
110 | The above request is used only by the child process; |
111 | the rest are used only by the parent. | |
e63ad01d | 112 | In the following requests, \fIpid\fP specifies the child process |
c13182ef | 113 | to be acted on. |
8bd58774 MK |
114 | For requests other than |
115 | .BR PTRACE_KILL , | |
116 | the child process must | |
fea681da MK |
117 | be stopped. |
118 | .TP | |
8bd58774 | 119 | .BR PTRACE_PEEKTEXT ", " PTRACE_PEEKDATA |
fea681da | 120 | Reads a word at the location |
0daa9e92 | 121 | .I addr |
fea681da | 122 | in the child's memory, returning the word as the result of the |
e511ffb6 | 123 | .BR ptrace () |
c13182ef | 124 | call. |
e63ad01d | 125 | Linux does not have separate text and data address spaces, so the two |
c13182ef | 126 | requests are currently equivalent. |
e63ad01d | 127 | (The argument \fIdata\fP is ignored.) |
fea681da | 128 | .TP |
428d3520 | 129 | .B PTRACE_PEEKUSER |
254255af MK |
130 | .\" PTRACE_PEEKUSR in kernel source, but glibc uses PTRACE_PEEKUSER, |
131 | .\" and that is the name that seems common on other systems. | |
fea681da MK |
132 | Reads a word at offset |
133 | .I addr | |
8bd58774 MK |
134 | in the child's USER area, |
135 | which holds the registers and other information about the process | |
6beb1671 | 136 | (see \fI<linux/user.h>\fP and \fI<sys/user.h>\fP). |
e63ad01d | 137 | The word is returned as the result of the |
e511ffb6 | 138 | .BR ptrace () |
c13182ef | 139 | call. |
e63ad01d | 140 | Typically the offset must be word-aligned, though this might vary by |
fea681da MK |
141 | architecture. (\fIdata\fP is ignored.) |
142 | .TP | |
8bd58774 | 143 | .BR PTRACE_POKETEXT ", " PTRACE_POKEDATA |
fea681da | 144 | Copies the word |
0daa9e92 | 145 | .I data |
fea681da | 146 | to location |
0daa9e92 | 147 | .I addr |
c13182ef MK |
148 | in the child's memory. |
149 | As above, the two requests are currently equivalent. | |
fea681da | 150 | .TP |
428d3520 | 151 | .B PTRACE_POKEUSER |
254255af MK |
152 | .\" PTRACE_POKEUSR in kernel source, but glibc uses PTRACE_POKEUSER, |
153 | .\" and that is the name that seems common on other systems. | |
fea681da | 154 | Copies the word |
0daa9e92 | 155 | .I data |
fea681da MK |
156 | to offset |
157 | .I addr | |
8bd58774 | 158 | in the child's USER area. |
c13182ef MK |
159 | As above, the offset must typically be word-aligned. |
160 | In order to maintain the integrity of the kernel, | |
8bd58774 | 161 | some modifications to the USER area are disallowed. |
fea681da | 162 | .TP |
8bd58774 | 163 | .BR PTRACE_GETREGS ", " PTRACE_GETFPREGS |
c13182ef MK |
164 | Copies the child's general purpose or floating-point registers, |
165 | respectively, to location \fIdata\fP in the parent. | |
c84371c6 | 166 | See \fI<linux/user.h>\fP for information on |
fea681da MK |
167 | the format of this data. (\fIaddr\fP is ignored.) |
168 | .TP | |
8bd58774 | 169 | .BR PTRACE_GETSIGINFO " (since Linux 2.3.99-pre6)" |
44b35ee0 MK |
170 | Retrieve information about the signal that caused the stop. |
171 | Copies a \fIsiginfo_t\fP structure (see | |
172 | .BR sigaction (2)) | |
173 | from the child to location \fIdata\fP in the parent. | |
174 | (\fIaddr\fP is ignored.) | |
175 | .TP | |
6beb1671 | 176 | .BR PTRACE_SETREGS ", " PTRACE_SETFPREGS |
c13182ef MK |
177 | Copies the child's general purpose or floating-point registers, |
178 | respectively, from location \fIdata\fP in the parent. | |
8bd58774 MK |
179 | As for |
180 | .BR PTRACE_POKEUSER , | |
181 | some general | |
c13182ef | 182 | purpose register modifications may be disallowed. |
e63ad01d | 183 | (\fIaddr\fP is ignored.) |
fea681da | 184 | .TP |
8bd58774 | 185 | .BR PTRACE_SETSIGINFO " (since Linux 2.3.99-pre6)" |
44b35ee0 | 186 | Set signal information. |
c13182ef | 187 | Copies a \fIsiginfo_t\fP structure from location \fIdata\fP in the |
e63ad01d | 188 | parent to the child. |
44b35ee0 | 189 | This will only affect signals that would normally be delivered to |
c13182ef MK |
190 | the child and were caught by the tracer. |
191 | It may be difficult to tell | |
44b35ee0 MK |
192 | these normal signals from synthetic signals generated by |
193 | .BR ptrace () | |
194 | itself. (\fIaddr\fP is ignored.) | |
195 | .TP | |
8bd58774 | 196 | .BR PTRACE_SETOPTIONS " (since Linux 2.4.6; see BUGS for caveats)" |
c13182ef | 197 | Sets ptrace options from \fIdata\fP in the parent. |
44b35ee0 MK |
198 | (\fIaddr\fP is ignored.) |
199 | \fIdata\fP is interpreted | |
10f5f294 | 200 | as a bit mask of options, which are specified by the following flags: |
44b35ee0 MK |
201 | .RS |
202 | .TP | |
8bd58774 | 203 | .BR PTRACE_O_TRACESYSGOOD " (since Linux 2.4.6)" |
c13182ef | 204 | When delivering syscall traps, set bit 7 in the signal number |
8bd58774 | 205 | (i.e., deliver \fI(SIGTRAP | 0x80)\fP |
e63ad01d | 206 | This makes it easy for the tracer to tell the difference |
c13182ef | 207 | between normal traps and those caused by a syscall. |
8bd58774 MK |
208 | .RB ( PTRACE_O_TRACESYSGOOD |
209 | may not work on all architectures.) | |
44b35ee0 | 210 | .TP |
8bd58774 | 211 | .BR PTRACE_O_TRACEFORK " (since Linux 2.5.46)" |
44b35ee0 | 212 | Stop the child at the next |
0bfa087b | 213 | .BR fork (2) |
8bd58774 | 214 | call with \fISIGTRAP | PTRACE_EVENT_FORK\ <<\ 8\fP and automatically |
c13182ef | 215 | start tracing the newly forked process, |
8bd58774 MK |
216 | which will start with a |
217 | .BR SIGSTOP . | |
218 | The PID for the new process can be retrieved with | |
219 | .BR PTRACE_GETEVENTMSG . | |
44b35ee0 | 220 | .TP |
8bd58774 | 221 | .BR PTRACE_O_TRACEVFORK " (since Linux 2.5.46)" |
44b35ee0 | 222 | Stop the child at the next |
0bfa087b | 223 | .BR vfork (2) |
8bd58774 MK |
224 | call with \fISIGTRAP | PTRACE_EVENT_VFORK\ <<\ 8\fP and automatically start |
225 | tracing the newly vforked process, which will start with a | |
226 | .BR SIGSTOP . | |
227 | The PID for the new process can be retrieved with | |
228 | .BR PTRACE_GETEVENTMSG . | |
44b35ee0 | 229 | .TP |
8bd58774 | 230 | .BR PTRACE_O_TRACECLONE " (since Linux 2.5.46)" |
44b35ee0 | 231 | Stop the child at the next |
0bfa087b | 232 | .BR clone (2) |
8bd58774 MK |
233 | call with \fISIGTRAP | PTRACE_EVENT_CLONE\ <<\ 8\fP and automatically start |
234 | tracing the newly cloned process, which will start with a | |
235 | .BR SIGSTOP . | |
236 | The PID for the new process can be retrieved with | |
237 | .BR PTRACE_GETEVENTMSG . | |
44b35ee0 | 238 | This option may not catch |
0bfa087b | 239 | .BR clone (2) |
c13182ef MK |
240 | calls in all cases. |
241 | If the child calls | |
0bfa087b | 242 | .BR clone (2) |
8bd58774 | 243 | with the |
0daa9e92 | 244 | .B CLONE_VFORK |
8bd58774 MK |
245 | flag, |
246 | .B PTRACE_EVENT_VFORK | |
247 | will be delivered instead | |
248 | if | |
249 | .B PTRACE_O_TRACEVFORK | |
250 | is set; otherwise if the child calls | |
0bfa087b | 251 | .BR clone (2) |
8bd58774 MK |
252 | with the exit signal set to |
253 | .BR SIGCHLD , | |
254 | .B PTRACE_EVENT_FORK | |
255 | will be delivered | |
256 | if | |
257 | .B PTRACE_O_TRACEFORK | |
258 | is set. | |
44b35ee0 | 259 | .TP |
8bd58774 | 260 | .BR PTRACE_O_TRACEEXEC " (since Linux 2.5.46)" |
44b35ee0 | 261 | Stop the child at the next |
0bfa087b | 262 | .BR execve (2) |
8bd58774 | 263 | call with \fISIGTRAP | PTRACE_EVENT_EXEC\ <<\ 8\fP. |
44b35ee0 | 264 | .TP |
8bd58774 | 265 | .BR PTRACE_O_TRACEVFORKDONE " (since Linux 2.5.60)" |
44b35ee0 | 266 | Stop the child at the completion of the next |
0bfa087b | 267 | .BR vfork (2) |
8bd58774 | 268 | call with \fISIGTRAP | PTRACE_EVENT_VFORK_DONE\ <<\ 8\fP. |
44b35ee0 | 269 | .TP |
8bd58774 MK |
270 | .BR PTRACE_O_TRACEEXIT " (since Linux 2.5.60)" |
271 | Stop the child at exit with \fISIGTRAP | PTRACE_EVENT_EXIT\ <<\ 8\fP. | |
272 | The child's exit status can be retrieved with | |
273 | .BR PTRACE_GETEVENTMSG . | |
c13182ef MK |
274 | This stop will be done early during process exit when registers |
275 | are still available, allowing the tracer to see where the exit occurred, | |
276 | whereas the normal exit notification is done after the process | |
e63ad01d | 277 | is finished exiting. |
44b35ee0 MK |
278 | Even though context is available, the tracer cannot prevent the exit from |
279 | happening at this point. | |
280 | .RE | |
281 | .TP | |
8bd58774 | 282 | .BR PTRACE_GETEVENTMSG " (since Linux 2.5.46)" |
c13182ef MK |
283 | Retrieve a message (as an |
284 | .IR "unsigned long" ) | |
44b35ee0 MK |
285 | about the ptrace event |
286 | that just happened, placing it in the location \fIdata\fP in the parent. | |
8bd58774 | 287 | For |
0daa9e92 | 288 | .B PTRACE_EVENT_EXIT |
8bd58774 MK |
289 | this is the child's exit status. |
290 | For | |
291 | .BR PTRACE_EVENT_FORK , | |
0daa9e92 | 292 | .B PTRACE_EVENT_VFORK |
8bd58774 MK |
293 | and |
294 | .B PTRACE_EVENT_CLONE | |
295 | this | |
c13182ef | 296 | is the PID of the new process. |
53e4da48 | 297 | Since Linux 2.6.18, the PID of the new process is also available |
8bd58774 MK |
298 | for |
299 | .BR PTRACE_EVENT_VFORK_DONE . | |
53e4da48 | 300 | (\fIaddr\fP is ignored.) |
44b35ee0 | 301 | .TP |
8bd58774 | 302 | .B PTRACE_CONT |
c13182ef | 303 | Restarts the stopped child process. |
eba72288 | 304 | If \fIdata\fP is non-zero and not |
8bd58774 MK |
305 | .BR SIGSTOP , |
306 | it is interpreted as a signal to be delivered to the child; | |
c13182ef | 307 | otherwise, no signal is delivered. |
e63ad01d | 308 | Thus, for example, the parent can control |
c13182ef | 309 | whether a signal sent to the child is delivered or not. |
e63ad01d | 310 | (\fIaddr\fP is ignored.) |
fea681da | 311 | .TP |
8bd58774 MK |
312 | .BR PTRACE_SYSCALL ", " PTRACE_SINGLESTEP |
313 | Restarts the stopped child as for | |
314 | .BR PTRACE_CONT , | |
315 | but arranges for | |
c13182ef MK |
316 | the child to be stopped at the next entry to or exit from a system call, |
317 | or after execution of a single instruction, respectively. | |
318 | (The child will also, as usual, be stopped upon receipt of a signal.) | |
319 | From the parent's perspective, the child will appear to have been | |
8bd58774 MK |
320 | stopped by receipt of a |
321 | .BR SIGTRAP . | |
322 | So, for | |
323 | .BR PTRACE_SYSCALL , | |
324 | for example, the idea is to inspect | |
c13182ef | 325 | the arguments to the system call at the first stop, |
8bd58774 MK |
326 | then do another |
327 | .B PTRACE_SYSCALL | |
328 | and inspect the return value of | |
c13182ef | 329 | the system call at the second stop. |
e63ad01d | 330 | (\fIaddr\fP is ignored.) |
fea681da | 331 | .TP |
6beb1671 | 332 | .BR PTRACE_SYSEMU ", " PTRACE_SYSEMU_SINGLESTEP " (since Linux 2.6.14)" |
8bd58774 MK |
333 | For |
334 | .BR PTRACE_SYSEMU , | |
335 | continue and stop on entry to the next syscall, | |
c13182ef | 336 | which will not be executed. |
8bd58774 MK |
337 | For |
338 | .BR PTRACE_SYSEMU_SINGLESTEP , | |
339 | do the same | |
c13182ef MK |
340 | but also singlestep if not a syscall. |
341 | This call is used by programs like | |
a832b2d8 | 342 | User Mode Linux that want to emulate all the child's system calls. |
c13182ef | 343 | (\fIaddr\fP and \fIdata\fP are ignored; |
e63ad01d | 344 | not supported on all architectures.) |
44b35ee0 | 345 | .TP |
8bd58774 MK |
346 | .B PTRACE_KILL |
347 | Sends the child a | |
348 | .B SIGKILL | |
349 | to terminate it. | |
e63ad01d | 350 | (\fIaddr\fP and \fIdata\fP are ignored.) |
fea681da | 351 | .TP |
8bd58774 | 352 | .B PTRACE_ATTACH |
fea681da MK |
353 | Attaches to the process specified in |
354 | .IR pid , | |
a1ffe9f5 | 355 | making it a traced "child" of the calling process; |
8bd58774 MK |
356 | the behavior of the child is as if it had done a |
357 | .BR PTRACE_TRACEME . | |
a1ffe9f5 | 358 | The calling process actually becomes the parent of the child |
e63ad01d | 359 | process for most purposes (e.g., it will receive |
fea681da MK |
360 | notification of child events and appears in |
361 | .BR ps (1) | |
362 | output as the child's parent), but a | |
363 | .BR getppid (2) | |
c13182ef | 364 | by the child will still return the PID of the original parent. |
8bd58774 MK |
365 | The child is sent a |
366 | .BR SIGSTOP , | |
367 | but will not necessarily have stopped | |
e63ad01d | 368 | by the completion of this call; use |
0bfa087b | 369 | .BR wait (2) |
c13182ef | 370 | to wait for the child to stop. |
e63ad01d | 371 | (\fIaddr\fP and \fIdata\fP are ignored.) |
fea681da | 372 | .TP |
8bd58774 MK |
373 | .B PTRACE_DETACH |
374 | Restarts the stopped child as for | |
375 | .BR PTRACE_CONT , | |
376 | but first detaches | |
377 | from the process, undoing the reparenting effect of | |
378 | .BR PTRACE_ATTACH , | |
379 | and the effects of | |
380 | .BR PTRACE_TRACEME . | |
c13182ef | 381 | Although perhaps not intended, under Linux a traced child can be |
e63ad01d | 382 | detached in this way regardless of which method was used to initiate |
c13182ef | 383 | tracing. |
e63ad01d | 384 | (\fIaddr\fP is ignored.) |
2b2581ee | 385 | .SH "RETURN VALUE" |
988db661 | 386 | On success, |
0daa9e92 | 387 | .B PTRACE_PEEK* |
8bd58774 | 388 | requests return the requested data, |
2b2581ee MK |
389 | while other requests return zero. |
390 | On error, all requests return \-1, and | |
391 | .I errno | |
392 | is set appropriately. | |
8bd58774 | 393 | Since the value returned by a successful |
0daa9e92 | 394 | .B PTRACE_PEEK* |
2b2581ee MK |
395 | request may be \-1, the caller must check |
396 | .I errno | |
397 | after such requests to determine whether or not an error occurred. | |
398 | .SH ERRORS | |
399 | .TP | |
400 | .B EBUSY | |
401 | (i386 only) There was an error with allocating or freeing a debug | |
402 | register. | |
403 | .TP | |
404 | .B EFAULT | |
405 | There was an attempt to read from or write to an invalid area in | |
406 | the parent's or child's memory, | |
407 | probably because the area wasn't mapped or accessible. | |
408 | Unfortunately, under Linux, different variations of this fault | |
2f0af33b MK |
409 | will return |
410 | .B EIO | |
411 | or | |
412 | .B EFAULT | |
413 | more or less arbitrarily. | |
2b2581ee MK |
414 | .TP |
415 | .B EINVAL | |
416 | An attempt was made to set an invalid option. | |
417 | .TP | |
418 | .B EIO | |
419 | \fIrequest\fP is invalid, or an attempt was made to read from or | |
420 | write to an invalid area in the parent's or child's memory, | |
421 | or there was a word-alignment violation, | |
422 | or an invalid signal was specified during a restart request. | |
423 | .TP | |
424 | .B EPERM | |
425 | The specified process cannot be traced. | |
426 | This could be because the | |
427 | parent has insufficient privileges (the required capability is | |
428 | .BR CAP_SYS_PTRACE ); | |
429 | non-root processes cannot trace processes that they | |
430 | cannot send signals to or those running | |
431 | set-user-ID/set-group-ID programs, for obvious reasons. | |
432 | Alternatively, the process may already be being traced, or be | |
66ee0c7e | 433 | .BR init (8) |
2b2581ee MK |
434 | (PID 1). |
435 | .TP | |
436 | .B ESRCH | |
437 | The specified process does not exist, or is not currently being traced | |
438 | by the caller, or is not stopped (for requests that require that). | |
439 | .SH "CONFORMING TO" | |
440 | SVr4, 4.3BSD | |
fea681da MK |
441 | .SH NOTES |
442 | Although arguments to | |
e511ffb6 | 443 | .BR ptrace () |
c13182ef | 444 | are interpreted according to the prototype given, |
5260fe08 | 445 | glibc currently declares |
e511ffb6 | 446 | .BR ptrace () |
c13182ef MK |
447 | as a variadic function with only the \fIrequest\fP argument fixed. |
448 | This means that unneeded trailing arguments may be omitted, | |
e63ad01d | 449 | though doing so makes use of undocumented |
197889d0 | 450 | .BR gcc (1) |
fea681da MK |
451 | behavior. |
452 | .LP | |
453 | .BR init (8), | |
e360c3a9 | 454 | the process with PID 1, may not be traced. |
fea681da MK |
455 | .LP |
456 | The layout of the contents of memory and the USER area are quite OS- and | |
457 | architecture-specific. | |
458 | .LP | |
c13182ef | 459 | The size of a "word" is determined by the OS variant |
3758f6da | 460 | (e.g., for 32-bit Linux it is 32 bits, etc.). |
fea681da | 461 | .LP |
c13182ef | 462 | Tracing causes a few subtle differences in the semantics of |
e63ad01d | 463 | traced processes. |
8bd58774 MK |
464 | For example, if a process is attached to with |
465 | .BR PTRACE_ATTACH , | |
c13182ef | 466 | its original parent can no longer receive notification via |
0bfa087b | 467 | .BR wait (2) |
c13182ef | 468 | when it stops, and there is no way for the new parent to |
e63ad01d | 469 | effectively simulate this notification. |
fea681da | 470 | .LP |
8bd58774 | 471 | When the parent receives an event with |
0daa9e92 | 472 | .B PTRACE_EVENT_* |
8bd58774 | 473 | set, |
cd270bc0 MK |
474 | the child is not in the normal signal delivery path. |
475 | This means the parent cannot do | |
9110c53a | 476 | .BR ptrace (PTRACE_CONT) |
6d3925ac | 477 | with a signal or |
9110c53a | 478 | .BR ptrace (PTRACE_KILL). |
0bfa087b | 479 | .BR kill (2) |
8bd58774 | 480 | with a |
0daa9e92 | 481 | .B SIGKILL |
8bd58774 | 482 | signal can be used instead to kill the child process |
6d3925ac MK |
483 | after receiving one of these messages. |
484 | .LP | |
fea681da | 485 | This page documents the way the |
e511ffb6 | 486 | .BR ptrace () |
c13182ef MK |
487 | call works currently in Linux. |
488 | Its behavior differs noticeably on other flavors of Unix. | |
e63ad01d | 489 | In any case, use of |
e511ffb6 | 490 | .BR ptrace () |
fea681da MK |
491 | is highly OS- and architecture-specific. |
492 | .LP | |
c13182ef | 493 | The SunOS man page describes |
e511ffb6 | 494 | .BR ptrace () |
c13182ef | 495 | as "unique and arcane", which it is. |
e63ad01d | 496 | The proc-based debugging interface |
fea681da | 497 | present in Solaris 2 implements a superset of |
e511ffb6 | 498 | .BR ptrace () |
fea681da | 499 | functionality in a more powerful and uniform way. |
a1d5f77c | 500 | .SH BUGS |
8bd58774 | 501 | On hosts with 2.6 kernel headers, |
0daa9e92 | 502 | .B PTRACE_SETOPTIONS |
8bd58774 | 503 | is declared |
a1d5f77c MK |
504 | with a different value than the one for 2.4. |
505 | This leads to applications compiled with such | |
506 | headers failing when run on 2.4 kernels. | |
8bd58774 | 507 | This can be worked around by redefining |
0daa9e92 | 508 | .B PTRACE_SETOPTIONS |
8bd58774 MK |
509 | to |
510 | .BR PTRACE_OLDSETOPTIONS , | |
511 | if that is defined. | |
fea681da MK |
512 | .SH "SEE ALSO" |
513 | .BR gdb (1), | |
514 | .BR strace (1), | |
515 | .BR execve (2), | |
516 | .BR fork (2), | |
517 | .BR signal (2), | |
518 | .BR wait (2), | |
519 | .BR exec (3), | |
520 | .BR capabilities (7) |