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