]>
Commit | Line | Data |
---|---|---|
fea681da MK |
1 | .\" Hey Emacs! This file is -*- nroff -*- source. |
2 | .\" | |
181f997f | 3 | .\" Copyright (c) 1993 Michael Haardt <michael@moria.de> |
fea681da MK |
4 | .\" Fri Apr 2 11:32:09 MET DST 1993 |
5 | .\" | |
181f997f | 6 | .\" and changes Copyright (C) 1999 Mike Coleman (mkc@acm.org) |
fea681da | 7 | .\" -- major revision to fully document ptrace semantics per recent Linux |
c13182ef | 8 | .\" kernel (2.2.10) and glibc (2.1.2) |
fea681da MK |
9 | .\" Sun Nov 7 03:18:35 CST 1999 |
10 | .\" | |
181f997f MK |
11 | .\" and Copyright (c) 2011, Denys Vlasenko <vda.linux@googlemail.com> |
12 | .\" | |
fea681da MK |
13 | .\" This is free documentation; you can redistribute it and/or |
14 | .\" modify it under the terms of the GNU General Public License as | |
15 | .\" published by the Free Software Foundation; either version 2 of | |
16 | .\" the License, or (at your option) any later version. | |
17 | .\" | |
18 | .\" The GNU General Public License's references to "object code" | |
19 | .\" and "executables" are to be interpreted as the output of any | |
20 | .\" document formatting or typesetting system, including | |
21 | .\" intermediate and printed output. | |
22 | .\" | |
23 | .\" This manual is distributed in the hope that it will be useful, | |
24 | .\" but WITHOUT ANY WARRANTY; without even the implied warranty of | |
25 | .\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the | |
26 | .\" GNU General Public License for more details. | |
27 | .\" | |
28 | .\" You should have received a copy of the GNU General Public | |
29 | .\" License along with this manual; if not, write to the Free | |
30 | .\" Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111, | |
31 | .\" USA. | |
32 | .\" | |
33 | .\" Modified Fri Jul 23 23:47:18 1993 by Rik Faith <faith@cs.unc.edu> | |
34 | .\" Modified Fri Jan 31 16:46:30 1997 by Eric S. Raymond <esr@thyrsus.com> | |
35 | .\" Modified Thu Oct 7 17:28:49 1999 by Andries Brouwer <aeb@cwi.nl> | |
c11b1abf | 36 | .\" Modified, 27 May 2004, Michael Kerrisk <mtk.manpages@gmail.com> |
fea681da MK |
37 | .\" Added notes on capability requirements |
38 | .\" | |
44b35ee0 MK |
39 | .\" 2006-03-24, Chuck Ebbert <76306.1226@compuserve.com> |
40 | .\" Added PTRACE_SETOPTIONS, PTRACE_GETEVENTMSG, PTRACE_GETSIGINFO, | |
41 | .\" PTRACE_SETSIGINFO, PTRACE_SYSEMU, PTRACE_SYSEMU_SINGLESTEP | |
42 | .\" (Thanks to Blaisorblade, Daniel Jacobowitz and others who helped.) | |
181f997f | 43 | .\" 2011-09, major update by Denys Vlasenko <vda.linux@googlemail.com> |
44b35ee0 | 44 | .\" |
f23cc1df MK |
45 | .\" FIXME Linux 2.6.34 adds PTRACE_GETREGSET/PTRACE_SETREGSET |
46 | .\" FIXME Linux 3.1 adds PTRACE_SEIZE, PTRACE_INTERRUPT, | |
dc85ba7c | 47 | .\" and PTRACE_LISTEN. |
b56defd3 | 48 | .\" |
3fc441b2 | 49 | .TH PTRACE 2 2013-01-27 "Linux" "Linux Programmer's Manual" |
fea681da MK |
50 | .SH NAME |
51 | ptrace \- process trace | |
52 | .SH SYNOPSIS | |
44b35ee0 | 53 | .nf |
fea681da MK |
54 | .B #include <sys/ptrace.h> |
55 | .sp | |
44b35ee0 MK |
56 | .BI "long ptrace(enum __ptrace_request " request ", pid_t " pid ", " |
57 | .BI " void *" addr ", void *" data ); | |
58 | .fi | |
fea681da MK |
59 | .SH DESCRIPTION |
60 | The | |
e511ffb6 | 61 | .BR ptrace () |
181f997f MK |
62 | system call provides a means by which one process (the "tracer") |
63 | may observe and control the execution of another process (the "tracee"), | |
64 | and examine and change the tracee's memory and registers. | |
e63ad01d | 65 | It is primarily used to implement breakpoint debugging and system |
fea681da MK |
66 | call tracing. |
67 | .LP | |
8898a252 | 68 | A tracee first needs to be attached to the tracer. |
181f997f MK |
69 | Attachment and subsequent commands are per thread: |
70 | in a multithreaded process, | |
71 | every thread can be individually attached to a | |
72 | (potentially different) tracer, | |
73 | or left not attached and thus not debugged. | |
74 | Therefore, "tracee" always means "(one) thread", | |
75 | never "a (possibly multithreaded) process". | |
8b20acd1 | 76 | Ptrace commands are always sent to |
181f997f MK |
77 | a specific tracee using a call of the form |
78 | ||
79 | ptrace(PTRACE_foo, pid, ...) | |
80 | ||
81 | where | |
82 | .I pid | |
83 | is the thread ID of the corresponding Linux thread. | |
84 | .LP | |
8898a252 MK |
85 | (Note that in this page, a "multithreaded process" |
86 | means a thread group consisting of threads created using the | |
87 | .BR clone (2) | |
88 | .B CLONE_THREAD | |
89 | flag.) | |
90 | .LP | |
181f997f | 91 | A process can initiate a trace by calling |
c13182ef | 92 | .BR fork (2) |
8bd58774 MK |
93 | and having the resulting child do a |
94 | .BR PTRACE_TRACEME , | |
e63ad01d | 95 | followed (typically) by an |
4d12a715 | 96 | .BR execve (2). |
181f997f | 97 | Alternatively, one process may commence tracing another process using |
8bd58774 | 98 | .BR PTRACE_ATTACH . |
fea681da | 99 | .LP |
4d12a715 | 100 | While being traced, the tracee will stop each time a signal is delivered, |
c13182ef | 101 | even if the signal is being ignored. |
181f997f | 102 | (An exception is |
8bd58774 MK |
103 | .BR SIGKILL , |
104 | which has its usual effect.) | |
181f997f MK |
105 | The tracer will be notified at its next call to |
106 | .BR waitpid (2) | |
8898a252 MK |
107 | (or one of the related "wait" system calls); that call will return a |
108 | .I status | |
109 | value containing information that indicates | |
110 | the cause of the stop in the tracee. | |
111 | While the tracee is stopped, | |
112 | the tracer can use various ptrace requests to inspect and modify the tracee. | |
4d12a715 | 113 | The tracer then causes the tracee to continue, |
e63ad01d | 114 | optionally ignoring the delivered signal |
fea681da MK |
115 | (or even delivering a different signal instead). |
116 | .LP | |
d39a9b98 | 117 | If the |
b16ecdae DV |
118 | .B PTRACE_O_TRACEEXEC |
119 | option is not in effect, all successful calls to | |
120 | .BR execve (2) | |
d39a9b98 | 121 | by the traced process will cause it to be sent a |
b16ecdae | 122 | .B SIGTRAP |
d39a9b98 | 123 | signal, |
b16ecdae DV |
124 | giving the parent a chance to gain control before the new program |
125 | begins execution. | |
126 | .LP | |
181f997f | 127 | When the tracer is finished tracing, it can cause the tracee to continue |
4d12a715 | 128 | executing in a normal, untraced mode via |
8bd58774 | 129 | .BR PTRACE_DETACH . |
fea681da | 130 | .LP |
181f997f MK |
131 | The value of |
132 | .I request | |
133 | determines the action to be performed: | |
fea681da | 134 | .TP |
8bd58774 | 135 | .B PTRACE_TRACEME |
181f997f | 136 | Indicate that this process is to be traced by its parent. |
c13182ef MK |
137 | A process probably shouldn't make this request if its parent |
138 | isn't expecting to trace it. | |
181f997f MK |
139 | .RI ( pid , |
140 | .IR addr , | |
141 | and | |
142 | .IR data | |
143 | are ignored.) | |
fea681da | 144 | .LP |
181f997f MK |
145 | The |
146 | .B PTRACE_TRACEME | |
147 | request is used only by the tracee; | |
148 | the remaining requests are used only by the tracer. | |
149 | In the following requests, | |
150 | .I pid | |
151 | specifies the thread ID of the tracee to be acted on. | |
8bd58774 | 152 | For requests other than |
b16ecdae DV |
153 | .B PTRACE_ATTACH |
154 | and | |
8bd58774 | 155 | .BR PTRACE_KILL , |
4d12a715 | 156 | the tracee must be stopped. |
fea681da | 157 | .TP |
8bd58774 | 158 | .BR PTRACE_PEEKTEXT ", " PTRACE_PEEKDATA |
181f997f | 159 | Read a word at the address |
0daa9e92 | 160 | .I addr |
4d12a715 | 161 | in the tracee's memory, returning the word as the result of the |
e511ffb6 | 162 | .BR ptrace () |
c13182ef | 163 | call. |
181f997f MK |
164 | Linux does not have separate text and data address spaces, |
165 | so these two requests are currently equivalent. | |
166 | .RI ( data | |
167 | is ignored.) | |
fea681da | 168 | .TP |
428d3520 | 169 | .B PTRACE_PEEKUSER |
254255af MK |
170 | .\" PTRACE_PEEKUSR in kernel source, but glibc uses PTRACE_PEEKUSER, |
171 | .\" and that is the name that seems common on other systems. | |
181f997f | 172 | Read a word at offset |
fea681da | 173 | .I addr |
4d12a715 | 174 | in the tracee's USER area, |
8bd58774 | 175 | which holds the registers and other information about the process |
181f997f MK |
176 | (see |
177 | .IR <sys/user.h> ). | |
e63ad01d | 178 | The word is returned as the result of the |
e511ffb6 | 179 | .BR ptrace () |
c13182ef | 180 | call. |
181f997f | 181 | Typically, the offset must be word-aligned, though this might vary by |
8660aec0 MK |
182 | architecture. |
183 | See NOTES. | |
181f997f MK |
184 | .RI ( data |
185 | is ignored.) | |
fea681da | 186 | .TP |
8bd58774 | 187 | .BR PTRACE_POKETEXT ", " PTRACE_POKEDATA |
181f997f | 188 | Copy the word |
0daa9e92 | 189 | .I data |
181f997f | 190 | to the address |
0daa9e92 | 191 | .I addr |
4d12a715 | 192 | in the tracee's memory. |
181f997f | 193 | As for |
d6e37473 | 194 | .BR PTRACE_PEEKTEXT |
181f997f MK |
195 | and |
196 | .BR PTRACE_PEEKDATA , | |
197 | these two requests are currently equivalent. | |
fea681da | 198 | .TP |
428d3520 | 199 | .B PTRACE_POKEUSER |
254255af MK |
200 | .\" PTRACE_POKEUSR in kernel source, but glibc uses PTRACE_POKEUSER, |
201 | .\" and that is the name that seems common on other systems. | |
181f997f | 202 | Copy the word |
0daa9e92 | 203 | .I data |
fea681da MK |
204 | to offset |
205 | .I addr | |
4d12a715 | 206 | in the tracee's USER area. |
181f997f MK |
207 | As for |
208 | .BR PTRACE_PEEKUSER , | |
209 | the offset must typically be word-aligned. | |
c13182ef | 210 | In order to maintain the integrity of the kernel, |
8bd58774 | 211 | some modifications to the USER area are disallowed. |
181f997f | 212 | .\" FIXME In the preceding sentence, which modifications are disallowed, |
7fac88a9 | 213 | .\" and when they are disallowed, how does user space discover that fact? |
fea681da | 214 | .TP |
8bd58774 | 215 | .BR PTRACE_GETREGS ", " PTRACE_GETFPREGS |
a42c0c5a | 216 | Copy the tracee's general-purpose or floating-point registers, |
181f997f MK |
217 | respectively, to the address |
218 | .I data | |
219 | in the tracer. | |
220 | See | |
221 | .I <sys/user.h> | |
222 | for information on the format of this data. | |
223 | .RI ( addr | |
224 | is ignored.) | |
50fe8d53 MK |
225 | Note that SPARC systems have the meaning of |
226 | .I data | |
227 | and | |
228 | .I addr | |
229 | reversed; that is, | |
230 | .I data | |
231 | is ignored and the registers are copied to the address | |
232 | .IR addr . | |
34709982 MK |
233 | .B PTRACE_GETREGS |
234 | and | |
235 | .B PTRACE_GETFPREGS | |
236 | are not present on all architectures. | |
fea681da | 237 | .TP |
8bd58774 | 238 | .BR PTRACE_GETSIGINFO " (since Linux 2.3.99-pre6)" |
44b35ee0 | 239 | Retrieve information about the signal that caused the stop. |
181f997f MK |
240 | Copy a |
241 | .I siginfo_t | |
242 | structure (see | |
44b35ee0 | 243 | .BR sigaction (2)) |
181f997f MK |
244 | from the tracee to the address |
245 | .I data | |
246 | in the tracer. | |
247 | .RI ( addr | |
248 | is ignored.) | |
44b35ee0 | 249 | .TP |
6beb1671 | 250 | .BR PTRACE_SETREGS ", " PTRACE_SETFPREGS |
a42c0c5a | 251 | Copy the tracee's general-purpose or floating-point registers, |
181f997f MK |
252 | respectively, from the address |
253 | .I data | |
254 | in the tracer. | |
8bd58774 MK |
255 | As for |
256 | .BR PTRACE_POKEUSER , | |
a42c0c5a | 257 | some general-purpose register modifications may be disallowed. |
181f997f | 258 | .\" FIXME In the preceding sentence, which modifications are disallowed, |
7fac88a9 | 259 | .\" and when they are disallowed, how does user space discover that fact? |
181f997f MK |
260 | .RI ( addr |
261 | is ignored.) | |
50fe8d53 MK |
262 | Note that SPARC systems have the meaning of |
263 | .I data | |
264 | and | |
265 | .I addr | |
266 | reversed; that is, | |
267 | .I data | |
268 | is ignored and the registers are copied from the address | |
269 | .IR addr . | |
34709982 MK |
270 | .B PTRACE_SETREGS |
271 | and | |
272 | .B PTRACE_SETFPREGS | |
273 | are not present on all architectures. | |
fea681da | 274 | .TP |
8bd58774 | 275 | .BR PTRACE_SETSIGINFO " (since Linux 2.3.99-pre6)" |
181f997f MK |
276 | Set signal information: |
277 | copy a | |
278 | .I siginfo_t | |
279 | structure from the address | |
280 | .I data | |
281 | in the tracer to the tracee. | |
282 | This will affect only signals that would normally be delivered to | |
4d12a715 | 283 | the tracee and were caught by the tracer. |
c13182ef | 284 | It may be difficult to tell |
44b35ee0 MK |
285 | these normal signals from synthetic signals generated by |
286 | .BR ptrace () | |
8660aec0 | 287 | itself. |
181f997f MK |
288 | .RI ( addr |
289 | is ignored.) | |
44b35ee0 | 290 | .TP |
8bd58774 | 291 | .BR PTRACE_SETOPTIONS " (since Linux 2.4.6; see BUGS for caveats)" |
181f997f MK |
292 | Set ptrace options from |
293 | .IR data . | |
294 | .RI ( addr | |
295 | is ignored.) | |
296 | .IR data | |
297 | is interpreted as a bit mask of options, | |
298 | which are specified by the following flags: | |
dc85ba7c | 299 | |
cc7d99c8 | 300 | .RS |
dc85ba7c | 301 | |
b89e39ef MK |
302 | .TP |
303 | .BR PTRACE_O_EXITKILL " (since Linux 3.8)" | |
304 | .\" commit 992fb6e170639b0849bace8e49bf31bd37c4123 | |
305 | If a tracer sets this flag, a | |
306 | .B SIGKILL | |
307 | signal will be sent to every tracee if the tracer exits. | |
308 | This option is useful for ptrace jailers that | |
309 | want to ensure that tracees can never escape the trcer's control. | |
310 | ||
44b35ee0 | 311 | .TP |
8bd58774 | 312 | .BR PTRACE_O_TRACECLONE " (since Linux 2.5.46)" |
4d12a715 | 313 | Stop the tracee at the next |
0bfa087b | 314 | .BR clone (2) |
181f997f MK |
315 | and automatically start tracing the newly cloned process, |
316 | which will start with a | |
8bd58774 | 317 | .BR SIGSTOP . |
8898a252 MK |
318 | A |
319 | .BR waitpid (2) | |
dc85ba7c | 320 | by the tracer will return a |
8898a252 | 321 | .I status |
dc85ba7c MK |
322 | value such that |
323 | ||
324 | .nf | |
325 | status>>8 == (SIGTRAP | (PTRACE_EVENT_CLONE<<8)) | |
326 | .fi | |
327 | ||
181f997f | 328 | The PID of the new process can be retrieved with |
8bd58774 | 329 | .BR PTRACE_GETEVENTMSG . |
181f997f | 330 | .IP |
44b35ee0 | 331 | This option may not catch |
0bfa087b | 332 | .BR clone (2) |
c13182ef | 333 | calls in all cases. |
4d12a715 | 334 | If the tracee calls |
0bfa087b | 335 | .BR clone (2) |
8bd58774 | 336 | with the |
0daa9e92 | 337 | .B CLONE_VFORK |
8bd58774 MK |
338 | flag, |
339 | .B PTRACE_EVENT_VFORK | |
340 | will be delivered instead | |
341 | if | |
342 | .B PTRACE_O_TRACEVFORK | |
4d12a715 | 343 | is set; otherwise if the tracee calls |
0bfa087b | 344 | .BR clone (2) |
8bd58774 MK |
345 | with the exit signal set to |
346 | .BR SIGCHLD , | |
347 | .B PTRACE_EVENT_FORK | |
181f997f | 348 | will be delivered if |
8bd58774 MK |
349 | .B PTRACE_O_TRACEFORK |
350 | is set. | |
cc7d99c8 | 351 | |
44b35ee0 | 352 | .TP |
8bd58774 | 353 | .BR PTRACE_O_TRACEEXEC " (since Linux 2.5.46)" |
4d12a715 | 354 | Stop the tracee at the next |
181f997f | 355 | .BR execve (2). |
8898a252 MK |
356 | A |
357 | .BR waitpid (2) | |
dc85ba7c | 358 | by the tracer will return a |
8898a252 | 359 | .I status |
dc85ba7c MK |
360 | value such that |
361 | ||
362 | .nf | |
363 | status>>8 == (SIGTRAP | (PTRACE_EVENT_EXEC<<8)) | |
364 | .fi | |
365 | ||
8f318249 MK |
366 | If the execing thread is not a thread group leader, |
367 | the thread ID is reset to thread group leader's ID before this stop. | |
b16d33ef DV |
368 | Since Linux 3.0, the former thread ID can be retrieved with |
369 | .BR PTRACE_GETEVENTMSG . | |
dc85ba7c | 370 | |
44b35ee0 | 371 | .TP |
8bd58774 | 372 | .BR PTRACE_O_TRACEEXIT " (since Linux 2.5.60)" |
181f997f | 373 | Stop the tracee at exit. |
8898a252 MK |
374 | A |
375 | .BR waitpid (2) | |
dc85ba7c | 376 | by the tracer will return a |
8898a252 | 377 | .I status |
dc85ba7c MK |
378 | value such that |
379 | ||
380 | .nf | |
381 | status>>8 == (SIGTRAP | (PTRACE_EVENT_EXIT<<8)) | |
382 | .fi | |
383 | ||
4d12a715 | 384 | The tracee's exit status can be retrieved with |
8bd58774 | 385 | .BR PTRACE_GETEVENTMSG . |
181f997f MK |
386 | .IP |
387 | The tracee is stopped early during process exit, | |
388 | when registers are still available, | |
389 | allowing the tracer to see where the exit occurred, | |
c13182ef | 390 | whereas the normal exit notification is done after the process |
e63ad01d | 391 | is finished exiting. |
181f997f MK |
392 | Even though context is available, |
393 | the tracer cannot prevent the exit from happening at this point. | |
cc7d99c8 MK |
394 | |
395 | .TP | |
396 | .BR PTRACE_O_TRACEFORK " (since Linux 2.5.46)" | |
397 | Stop the tracee at the next | |
398 | .BR fork (2) | |
399 | and automatically start tracing the newly forked process, | |
400 | which will start with a | |
401 | .BR SIGSTOP . | |
402 | A | |
403 | .BR waitpid (2) | |
404 | by the tracer will return a | |
405 | .I status | |
406 | value such that | |
407 | ||
408 | .nf | |
409 | status>>8 == (SIGTRAP | (PTRACE_EVENT_FORK<<8)) | |
410 | .fi | |
411 | ||
412 | The PID of the new process can be retrieved with | |
413 | .BR PTRACE_GETEVENTMSG . | |
414 | ||
415 | .TP | |
416 | .BR PTRACE_O_TRACESYSGOOD " (since Linux 2.4.6)" | |
417 | When delivering system call traps, set bit 7 in the signal number | |
418 | (i.e., deliver | |
419 | .IR "SIGTRAP|0x80" ). | |
420 | This makes it easy for the tracer to distinguish | |
421 | normal traps from those caused by a system call. | |
422 | .RB ( PTRACE_O_TRACESYSGOOD | |
423 | may not work on all architectures.) | |
424 | .TP | |
425 | .BR PTRACE_O_TRACEVFORK " (since Linux 2.5.46)" | |
426 | Stop the tracee at the next | |
427 | .BR vfork (2) | |
428 | and automatically start tracing the newly vforked process, | |
429 | which will start with a | |
430 | .BR SIGSTOP . | |
431 | A | |
432 | .BR waitpid (2) | |
433 | by the tracer will return a | |
434 | .I status | |
435 | value such that | |
436 | ||
437 | .nf | |
438 | status>>8 == (SIGTRAP | (PTRACE_EVENT_VFORK<<8)) | |
439 | .fi | |
440 | ||
441 | The PID of the new process can be retrieved with | |
442 | .BR PTRACE_GETEVENTMSG . | |
443 | .TP | |
444 | .BR PTRACE_O_TRACEVFORKDONE " (since Linux 2.5.60)" | |
445 | Stop the tracee at the completion of the next | |
446 | .BR vfork (2). | |
447 | A | |
448 | .BR waitpid (2) | |
449 | by the tracer will return a | |
450 | .I status | |
451 | value such that | |
452 | ||
453 | .nf | |
454 | status>>8 == (SIGTRAP | (PTRACE_EVENT_VFORK_DONE<<8)) | |
455 | .fi | |
456 | ||
457 | The PID of the new process can (since Linux 2.6.18) be retrieved with | |
458 | .BR PTRACE_GETEVENTMSG . | |
459 | ||
44b35ee0 | 460 | .RE |
cc7d99c8 | 461 | |
44b35ee0 | 462 | .TP |
8bd58774 | 463 | .BR PTRACE_GETEVENTMSG " (since Linux 2.5.46)" |
c13182ef MK |
464 | Retrieve a message (as an |
465 | .IR "unsigned long" ) | |
44b35ee0 | 466 | about the ptrace event |
181f997f MK |
467 | that just happened, placing it at the address |
468 | .I data | |
469 | in the tracer. | |
8bd58774 | 470 | For |
181f997f | 471 | .BR PTRACE_EVENT_EXIT , |
4d12a715 | 472 | this is the tracee's exit status. |
8bd58774 MK |
473 | For |
474 | .BR PTRACE_EVENT_FORK , | |
181f997f MK |
475 | .BR PTRACE_EVENT_VFORK , |
476 | .BR PTRACE_EVENT_VFORK_DONE , | |
8bd58774 | 477 | and |
181f997f MK |
478 | .BR PTRACE_EVENT_CLONE , |
479 | this is the PID of the new process. | |
480 | .RI ( addr | |
481 | is ignored.) | |
44b35ee0 | 482 | .TP |
8bd58774 | 483 | .B PTRACE_CONT |
181f997f MK |
484 | Restart the stopped tracee process. |
485 | If | |
486 | .I data | |
487 | is nonzero, | |
488 | it is interpreted as the number of a signal to be delivered to the tracee; | |
c13182ef | 489 | otherwise, no signal is delivered. |
4d12a715 DV |
490 | Thus, for example, the tracer can control |
491 | whether a signal sent to the tracee is delivered or not. | |
181f997f MK |
492 | .RI ( addr |
493 | is ignored.) | |
fea681da | 494 | .TP |
8bd58774 | 495 | .BR PTRACE_SYSCALL ", " PTRACE_SINGLESTEP |
181f997f | 496 | Restart the stopped tracee as for |
8bd58774 | 497 | .BR PTRACE_CONT , |
181f997f MK |
498 | but arrange for the tracee to be stopped at |
499 | the next entry to or exit from a system call, | |
c13182ef | 500 | or after execution of a single instruction, respectively. |
4d12a715 DV |
501 | (The tracee will also, as usual, be stopped upon receipt of a signal.) |
502 | From the tracer's perspective, the tracee will appear to have been | |
8bd58774 MK |
503 | stopped by receipt of a |
504 | .BR SIGTRAP . | |
505 | So, for | |
506 | .BR PTRACE_SYSCALL , | |
507 | for example, the idea is to inspect | |
c13182ef | 508 | the arguments to the system call at the first stop, |
8bd58774 MK |
509 | then do another |
510 | .B PTRACE_SYSCALL | |
181f997f | 511 | and inspect the return value of the system call at the second stop. |
94cffcd7 MK |
512 | The |
513 | .I data | |
514 | argument is treated as for | |
515 | .BR PTRACE_CONT . | |
a5c725cf | 516 | .RI ( addr |
181f997f | 517 | is ignored.) |
fea681da | 518 | .TP |
6beb1671 | 519 | .BR PTRACE_SYSEMU ", " PTRACE_SYSEMU_SINGLESTEP " (since Linux 2.6.14)" |
8bd58774 MK |
520 | For |
521 | .BR PTRACE_SYSEMU , | |
181f997f | 522 | continue and stop on entry to the next system call, |
c13182ef | 523 | which will not be executed. |
8bd58774 MK |
524 | For |
525 | .BR PTRACE_SYSEMU_SINGLESTEP , | |
181f997f | 526 | do the same but also singlestep if not a system call. |
c13182ef | 527 | This call is used by programs like |
4d12a715 | 528 | User Mode Linux that want to emulate all the tracee's system calls. |
94cffcd7 MK |
529 | The |
530 | .I data | |
531 | argument is treated as for | |
532 | .BR PTRACE_CONT . | |
34709982 MK |
533 | The |
534 | .I addr | |
535 | argument is ignored. | |
536 | These requests are currently | |
537 | .\" As at 3.7 | |
d2ea1bd4 | 538 | supported only on x86. |
44b35ee0 | 539 | .TP |
8bd58774 | 540 | .B PTRACE_KILL |
181f997f | 541 | Send the tracee a |
8bd58774 MK |
542 | .B SIGKILL |
543 | to terminate it. | |
181f997f MK |
544 | .RI ( addr |
545 | and | |
546 | .I data | |
547 | are ignored.) | |
548 | .IP | |
549 | .I This operation is deprecated; do not use it! | |
550 | Instead, send a | |
551 | .BR SIGKILL | |
552 | directly using | |
553 | .BR kill (2) | |
554 | or | |
555 | .BR tgkill (2). | |
556 | The problem with | |
557 | .B PTRACE_KILL | |
558 | is that it requires the tracee to be in signal-delivery-stop, | |
559 | otherwise it may not work | |
560 | (i.e., may complete successfully but won't kill the tracee). | |
561 | By contrast, sending a | |
562 | .B SIGKILL | |
563 | directly has no such limitation. | |
8898a252 MK |
564 | .\" [Note from Denys Vlasenko: |
565 | .\" deprecation suggested by Oleg Nesterov. He prefers to deprecate it | |
566 | .\" instead of describing (and needing to support) PTRACE_KILL's quirks.] | |
fea681da | 567 | .TP |
8bd58774 | 568 | .B PTRACE_ATTACH |
181f997f | 569 | Attach to the process specified in |
fea681da | 570 | .IR pid , |
4d12a715 | 571 | making it a tracee of the calling process. |
8898a252 MK |
572 | .\" No longer true (removed by Denys Vlasenko, 2011, who remarks: |
573 | .\" "I think it isn't true in non-ancient 2.4 and in 2.6/3.x. | |
574 | .\" Basically, it's not true for any Linux in practical use. | |
4d12a715 DV |
575 | .\" ; the behavior of the tracee is as if it had done a |
576 | .\" .BR PTRACE_TRACEME . | |
577 | .\" The calling process actually becomes the parent of the tracee | |
578 | .\" process for most purposes (e.g., it will receive | |
579 | .\" notification of tracee events and appears in | |
580 | .\" .BR ps (1) | |
581 | .\" output as the tracee's parent), but a | |
582 | .\" .BR getppid (2) | |
583 | .\" by the tracee will still return the PID of the original parent. | |
584 | The tracee is sent a | |
8bd58774 MK |
585 | .BR SIGSTOP , |
586 | but will not necessarily have stopped | |
e63ad01d | 587 | by the completion of this call; use |
181f997f | 588 | .BR waitpid (2) |
8b20acd1 | 589 | to wait for the tracee to stop. |
181f997f MK |
590 | See the "Attaching and detaching" subsection for additional information. |
591 | .RI ( addr | |
592 | and | |
593 | .I data | |
594 | are ignored.) | |
fea681da | 595 | .TP |
8bd58774 | 596 | .B PTRACE_DETACH |
181f997f | 597 | Restart the stopped tracee as for |
8bd58774 | 598 | .BR PTRACE_CONT , |
181f997f MK |
599 | but first detach from it. |
600 | Under Linux, a tracee can be detached in this way regardless | |
601 | of which method was used to initiate tracing. | |
602 | .RI ( addr | |
603 | is ignored.) | |
4d12a715 | 604 | .SS Death under ptrace |
181f997f MK |
605 | When a (possibly multithreaded) process receives a killing signal |
606 | (one whose disposition is set to | |
607 | .B SIG_DFL | |
608 | and whose default action is to kill the process), | |
8b20acd1 MK |
609 | all threads exit. |
610 | Tracees report their death to their tracer(s). | |
181f997f MK |
611 | Notification of this event is delivered via |
612 | .BR waitpid (2). | |
613 | .LP | |
614 | Note that the killing signal will first cause signal-delivery-stop | |
615 | (on one tracee only), | |
616 | and only after it is injected by the tracer | |
617 | (or after it was dispatched to a thread which isn't traced), | |
618 | will death from the signal happen on | |
619 | .I all | |
620 | tracees within a multithreaded process. | |
621 | (The term "signal-delivery-stop" is explained below.) | |
4d12a715 | 622 | .LP |
181f997f | 623 | .B SIGKILL |
ca302d0e DV |
624 | does not generate signal-delivery-stop and |
625 | therefore the tracer can't suppress it. | |
181f997f MK |
626 | .B SIGKILL |
627 | kills even within system calls | |
628 | (syscall-exit-stop is not generated prior to death by | |
629 | .BR SIGKILL ). | |
630 | The net effect is that | |
631 | .B SIGKILL | |
632 | always kills the process (all its threads), | |
633 | even if some threads of the process are ptraced. | |
634 | .LP | |
635 | When the tracee calls | |
636 | .BR _exit (2), | |
637 | it reports its death to its tracer. | |
4d12a715 DV |
638 | Other threads are not affected. |
639 | .LP | |
181f997f MK |
640 | When any thread executes |
641 | .BR exit_group (2), | |
642 | every tracee in its thread group reports its death to its tracer. | |
4d12a715 | 643 | .LP |
181f997f MK |
644 | If the |
645 | .B PTRACE_O_TRACEEXIT | |
646 | option is on, | |
647 | .B PTRACE_EVENT_EXIT | |
648 | will happen before actual death. | |
649 | This applies to exits via | |
650 | .BR exit (2), | |
651 | .BR exit_group (2), | |
652 | and signal deaths (except | |
653 | .BR SIGKILL ), | |
654 | and when threads are torn down on | |
655 | .BR execve (2) | |
656 | in a multithreaded process. | |
657 | .LP | |
658 | The tracer cannot assume that the ptrace-stopped tracee exists. | |
659 | There are many scenarios when the tracee may die while stopped (such as | |
660 | .BR SIGKILL ). | |
d6e37473 | 661 | Therefore, the tracer must be prepared to handle an |
181f997f MK |
662 | .B ESRCH |
663 | error on any ptrace operation. | |
664 | Unfortunately, the same error is returned if the tracee | |
665 | exists but is not ptrace-stopped | |
666 | (for commands which require a stopped tracee), | |
667 | or if it is not traced by the process which issued the ptrace call. | |
668 | The tracer needs to keep track of the stopped/running state of the tracee, | |
669 | and interpret | |
670 | .B ESRCH | |
671 | as "tracee died unexpectedly" only if it knows that the tracee has | |
672 | been observed to enter ptrace-stop. | |
673 | Note that there is no guarantee that | |
674 | .I waitpid(WNOHANG) | |
675 | will reliably report the tracee's death status if a | |
676 | ptrace operation returned | |
677 | .BR ESRCH . | |
678 | .I waitpid(WNOHANG) | |
679 | may return 0 instead. | |
680 | In other words, the tracee may be "not yet fully dead", | |
681 | but already refusing ptrace requests. | |
682 | .LP | |
683 | The tracer can't assume that the tracee | |
684 | .I always | |
685 | ends its life by reporting | |
686 | .I WIFEXITED(status) | |
687 | or | |
8898a252 MK |
688 | .IR WIFSIGNALED(status) ; |
689 | there are cases where this does not occur. | |
690 | For example, if a thread other than thread group leader does an | |
691 | .BR execve (2), | |
692 | it disappears; | |
693 | its PID will never be seen again, | |
694 | and any subsequent ptrace stops will be reported under | |
695 | the thread group leader's PID. | |
4d12a715 DV |
696 | .SS Stopped states |
697 | A tracee can be in two states: running or stopped. | |
698 | .LP | |
181f997f | 699 | There are many kinds of states when the tracee is stopped, and in ptrace |
8b20acd1 | 700 | discussions they are often conflated. |
181f997f | 701 | Therefore, it is important to use precise terms. |
4d12a715 | 702 | .LP |
181f997f MK |
703 | In this manual page, any stopped state in which the tracee is ready |
704 | to accept ptrace commands from the tracer is called | |
705 | .IR ptrace-stop . | |
8b20acd1 | 706 | Ptrace-stops can |
181f997f MK |
707 | be further subdivided into |
708 | .IR signal-delivery-stop , | |
709 | .IR group-stop , | |
710 | .IR syscall-stop , | |
711 | and so on. | |
712 | These stopped states are described in detail below. | |
713 | .LP | |
714 | When the running tracee enters ptrace-stop, it notifies its tracer using | |
715 | .BR waitpid (2) | |
716 | (or one of the other "wait" system calls). | |
717 | Most of this manual page assumes that the tracer waits with: | |
718 | .LP | |
719 | pid = waitpid(pid_or_minus_1, &status, __WALL); | |
720 | .LP | |
721 | Ptrace-stopped tracees are reported as returns with | |
722 | .I pid | |
723 | greater than 0 and | |
724 | .I WIFSTOPPED(status) | |
725 | true. | |
8898a252 MK |
726 | .\" Denys Vlasenko: |
727 | .\" Do we require __WALL usage, or will just using 0 be ok? (With 0, | |
728 | .\" I am not 100% sure there aren't ugly corner cases.) Are the | |
181f997f MK |
729 | .\" rules different if user wants to use waitid? Will waitid require |
730 | .\" WEXITED? | |
731 | .\" | |
4d12a715 | 732 | .LP |
181f997f MK |
733 | The |
734 | .B __WALL | |
735 | flag does not include the | |
736 | .B WSTOPPED | |
737 | and | |
738 | .B WEXITED | |
739 | flags, but implies their functionality. | |
740 | .LP | |
741 | Setting the | |
742 | .B WCONTINUED | |
743 | flag when calling | |
744 | .BR waitpid (2) | |
745 | is not recommended: the "continued" state is per-process and | |
746 | consuming it can confuse the real parent of the tracee. | |
747 | .LP | |
748 | Use of the | |
749 | .B WNOHANG | |
750 | flag may cause | |
751 | .BR waitpid (2) | |
752 | to return 0 ("no wait results available yet") | |
753 | even if the tracer knows there should be a notification. | |
754 | Example: | |
755 | .nf | |
756 | ||
ca302d0e DV |
757 | errno = 0; |
758 | ptrace(PTRACE_CONT, pid, 0L, 0L); | |
759 | if (errno == ESRCH) { | |
760 | /* tracee is dead */ | |
761 | r = waitpid(tracee, &status, __WALL | WNOHANG); | |
762 | /* r can still be 0 here! */ | |
763 | } | |
181f997f | 764 | .fi |
b8d02d56 | 765 | .\" FIXME: |
181f997f MK |
766 | .\" waitid usage? WNOWAIT? |
767 | .\" describe how wait notifications queue (or not queue) | |
4d12a715 DV |
768 | .LP |
769 | The following kinds of ptrace-stops exist: signal-delivery-stops, | |
a5c725cf DP |
770 | group-stops, |
771 | .B PTRACE_EVENT | |
772 | stops, syscall-stops. | |
181f997f MK |
773 | They all are reported by |
774 | .BR waitpid (2) | |
775 | with | |
776 | .I WIFSTOPPED(status) | |
777 | true. | |
778 | They may be differentiated by examining the value | |
779 | .IR status>>8 , | |
780 | and if there is ambiguity in that value, by querying | |
781 | .BR PTRACE_GETSIGINFO . | |
181f997f MK |
782 | (Note: the |
783 | .I WSTOPSIG(status) | |
dc85ba7c | 784 | macro can't be used to perform this examination, |
8898a252 | 785 | because it returns the value |
0ce81ab5 | 786 | .IR "(status>>8)\ &\ 0xff" .) |
4d12a715 | 787 | .SS Signal-delivery-stop |
181f997f MK |
788 | When a (possibly multithreaded) process receives any signal except |
789 | .BR SIGKILL , | |
790 | the kernel selects an arbitrary thread which handles the signal. | |
791 | (If the signal is generated with | |
792 | .BR tgkill (2), | |
793 | the target thread can be explicitly selected by the caller.) | |
794 | If the selected thread is traced, it enters signal-delivery-stop. | |
795 | At this point, the signal is not yet delivered to the process, | |
796 | and can be suppressed by the tracer. | |
797 | If the tracer doesn't suppress the signal, | |
181f997f | 798 | it passes the signal to the tracee in the next ptrace restart request. |
8b20acd1 | 799 | This second step of signal delivery is called |
181f997f MK |
800 | .I "signal injection" |
801 | in this manual page. | |
802 | Note that if the signal is blocked, | |
803 | signal-delivery-stop doesn't happen until the signal is unblocked, | |
804 | with the usual exception that | |
805 | .B SIGSTOP | |
806 | can't be blocked. | |
807 | .LP | |
808 | Signal-delivery-stop is observed by the tracer as | |
809 | .BR waitpid (2) | |
810 | returning with | |
811 | .I WIFSTOPPED(status) | |
f098951d | 812 | true, with the signal returned by |
181f997f | 813 | .IR WSTOPSIG(status) . |
f098951d | 814 | If the signal is |
181f997f MK |
815 | .BR SIGTRAP , |
816 | this may be a different kind of ptrace-stop; | |
817 | see the "Syscall-stops" and "execve" sections below for details. | |
8b20acd1 | 818 | If |
181f997f MK |
819 | .I WSTOPSIG(status) |
820 | returns a stopping signal, this may be a group-stop; see below. | |
4d12a715 | 821 | .SS Signal injection and suppression |
181f997f MK |
822 | After signal-delivery-stop is observed by the tracer, |
823 | the tracer should restart the tracee with the call | |
4d12a715 | 824 | .LP |
181f997f | 825 | ptrace(PTRACE_restart, pid, 0, sig) |
4d12a715 | 826 | .LP |
181f997f MK |
827 | where |
828 | .B PTRACE_restart | |
829 | is one of the restarting ptrace requests. | |
830 | If | |
831 | .I sig | |
832 | is 0, then a signal is not delivered. | |
833 | Otherwise, the signal | |
834 | .I sig | |
835 | is delivered. | |
836 | This operation is called | |
837 | .I "signal injection" | |
838 | in this manual page, to distinguish it from signal-delivery-stop. | |
839 | .LP | |
8898a252 | 840 | The |
181f997f MK |
841 | .I sig |
842 | value may be different from the | |
843 | .I WSTOPSIG(status) | |
844 | value: the tracer can cause a different signal to be injected. | |
845 | .LP | |
846 | Note that a suppressed signal still causes system calls to return | |
8b20acd1 | 847 | prematurely. |
f098951d | 848 | In this case system calls will be restarted: the tracer will |
a17e05c5 | 849 | observe the tracee to reexecute the interrupted system call (or |
a5c725cf | 850 | .BR restart_syscall (2) |
f098951d DV |
851 | system call for a few syscalls which use a different mechanism |
852 | for restarting) if the tracer uses | |
853 | .BR PTRACE_SYSCALL . | |
854 | Even system calls (such as | |
a5c725cf | 855 | .BR poll (2)) |
f098951d | 856 | which are not restartable after signal are restarted after |
a17e05c5 MK |
857 | signal is suppressed; |
858 | however, kernel bugs exist which cause some syscalls to fail with | |
181f997f MK |
859 | .B EINTR |
860 | even though no observable signal is injected to the tracee. | |
4d12a715 | 861 | .LP |
8898a252 | 862 | Restarting ptrace commands issued in ptrace-stops other than |
181f997f MK |
863 | signal-delivery-stop are not guaranteed to inject a signal, even if |
864 | .I sig | |
8b20acd1 | 865 | is nonzero. |
181f997f MK |
866 | No error is reported; a nonzero |
867 | .I sig | |
868 | may simply be ignored. | |
869 | Ptrace users should not try to "create a new signal" this way: use | |
870 | .BR tgkill (2) | |
871 | instead. | |
4d12a715 | 872 | .LP |
8898a252 MK |
873 | The fact that signal injection requests may be ignored |
874 | when restarting the tracee after | |
875 | ptrace stops that are not signal-delivery-stops | |
876 | is a cause of confusion among ptrace users. | |
181f997f MK |
877 | One typical scenario is that the tracer observes group-stop, |
878 | mistakes it for signal-delivery-stop, restarts the tracee with | |
879 | ||
880 | ptrace(PTRACE_rest, pid, 0, stopsig) | |
881 | ||
882 | with the intention of injecting | |
883 | .IR stopsig , | |
884 | but | |
885 | .I stopsig | |
886 | gets ignored and the tracee continues to run. | |
887 | .LP | |
888 | The | |
889 | .B SIGCONT | |
890 | signal has a side effect of waking up (all threads of) | |
891 | a group-stopped process. | |
892 | This side effect happens before signal-delivery-stop. | |
a5c725cf | 893 | The tracer can't suppress this side effect (it can |
181f997f MK |
894 | only suppress signal injection, which only causes the |
895 | .BR SIGCONT | |
896 | handler to not be executed in the tracee, if such a handler is installed). | |
897 | In fact, waking up from group-stop may be followed by | |
898 | signal-delivery-stop for signal(s) | |
899 | .I other than | |
900 | .BR SIGCONT , | |
901 | if they were pending when | |
902 | .B SIGCONT | |
903 | was delivered. | |
904 | In other words, | |
905 | .B SIGCONT | |
906 | may be not the first signal observed by the tracee after it was sent. | |
907 | .LP | |
908 | Stopping signals cause (all threads of) a process to enter group-stop. | |
4d12a715 | 909 | This side effect happens after signal injection, and therefore can be |
181f997f MK |
910 | suppressed by the tracer. |
911 | .LP | |
dc85ba7c MK |
912 | In Linux 2.4 and earlier, the |
913 | .B SIGSTOP | |
914 | signal can't be injected. | |
915 | .\" In the Linux 2.4 sources, in arch/i386/kernel/signal.c::do_signal(), | |
916 | .\" there is: | |
d6e37473 | 917 | .\" |
dc85ba7c MK |
918 | .\" /* The debugger continued. Ignore SIGSTOP. */ |
919 | .\" if (signr == SIGSTOP) | |
920 | .\" continue; | |
921 | .LP | |
181f997f MK |
922 | .B PTRACE_GETSIGINFO |
923 | can be used to retrieve a | |
924 | .I siginfo_t | |
925 | structure which corresponds to the delivered signal. | |
926 | .B PTRACE_SETSIGINFO | |
927 | may be used to modify it. | |
928 | If | |
929 | .B PTRACE_SETSIGINFO | |
930 | has been used to alter | |
931 | .IR siginfo_t , | |
932 | the | |
933 | .I si_signo | |
934 | field and the | |
935 | .I sig | |
936 | parameter in the restarting command must match, | |
4d12a715 DV |
937 | otherwise the result is undefined. |
938 | .SS Group-stop | |
181f997f | 939 | When a (possibly multithreaded) process receives a stopping signal, |
8b20acd1 MK |
940 | all threads stop. |
941 | If some threads are traced, they enter a group-stop. | |
181f997f MK |
942 | Note that the stopping signal will first cause signal-delivery-stop |
943 | (on one tracee only), and only after it is injected by the tracer | |
944 | (or after it was dispatched to a thread which isn't traced), | |
945 | will group-stop be initiated on | |
946 | .I all | |
947 | tracees within the multithreaded process. | |
948 | As usual, every tracee reports its group-stop separately | |
949 | to the corresponding tracer. | |
950 | .LP | |
951 | Group-stop is observed by the tracer as | |
952 | .BR waitpid (2) | |
953 | returning with | |
954 | .I WIFSTOPPED(status) | |
955 | true, with the stopping signal available via | |
956 | .IR WSTOPSIG(status) . | |
957 | The same result is returned by some other classes of ptrace-stops, | |
958 | therefore the recommended practice is to perform the call | |
959 | .LP | |
960 | ptrace(PTRACE_GETSIGINFO, pid, 0, &siginfo) | |
961 | .LP | |
962 | The call can be avoided if the signal is not | |
963 | .BR SIGSTOP , | |
964 | .BR SIGTSTP , | |
965 | .BR SIGTTIN , | |
966 | or | |
967 | .BR SIGTTOU ; | |
968 | only these four signals are stopping signals. | |
969 | If the tracer sees something else, it can't be a group-stop. | |
970 | Otherwise, the tracer needs to call | |
971 | .BR PTRACE_GETSIGINFO . | |
972 | If | |
973 | .B PTRACE_GETSIGINFO | |
974 | fails with | |
975 | .BR EINVAL , | |
976 | then it is definitely a group-stop. | |
977 | (Other failure codes are possible, such as | |
978 | .B ESRCH | |
979 | ("no such process") if a | |
980 | .B SIGKILL | |
981 | killed the tracee.) | |
4d12a715 | 982 | .LP |
181f997f MK |
983 | As of kernel 2.6.38, |
984 | after the tracer sees the tracee ptrace-stop and until it | |
985 | restarts or kills it, the tracee will not run, | |
986 | and will not send notifications (except | |
987 | .B SIGKILL | |
988 | death) to the tracer, even if the tracer enters into another | |
989 | .BR waitpid (2) | |
8b20acd1 | 990 | call. |
4d12a715 | 991 | .LP |
b8d02d56 MK |
992 | The kernel behavior described in the previous paragraph |
993 | causes a problem with transparent handling of stopping signals. | |
994 | If the tracer restarts the tracee after group-stop, | |
dc85ba7c | 995 | the stopping signal |
8898a252 | 996 | is effectively ignored\(emthe tracee doesn't remain stopped, it runs. |
181f997f MK |
997 | If the tracer doesn't restart the tracee before entering into the next |
998 | .BR waitpid (2), | |
999 | future | |
1000 | .B SIGCONT | |
b8d02d56 MK |
1001 | signals will not be reported to the tracer; |
1002 | this would cause the | |
181f997f | 1003 | .B SIGCONT |
b8d02d56 | 1004 | signals to have no effect on the tracee. |
4d12a715 | 1005 | .SS PTRACE_EVENT stops |
181f997f MK |
1006 | If the tracer sets |
1007 | .B PTRACE_O_TRACE_* | |
1008 | options, the tracee will enter ptrace-stops called | |
1009 | .B PTRACE_EVENT | |
1010 | stops. | |
1011 | .LP | |
1012 | .B PTRACE_EVENT | |
1013 | stops are observed by the tracer as | |
1014 | .BR waitpid (2) | |
1015 | returning with | |
1016 | .IR WIFSTOPPED(status) , | |
1017 | and | |
1018 | .I WSTOPSIG(status) | |
1019 | returns | |
1020 | .BR SIGTRAP . | |
1021 | An additional bit is set in the higher byte of the status word: | |
1022 | the value | |
1023 | .I status>>8 | |
1024 | will be | |
1025 | ||
1026 | (SIGTRAP | PTRACE_EVENT_foo << 8). | |
1027 | ||
8b20acd1 | 1028 | The following events exist: |
181f997f MK |
1029 | .TP |
1030 | .B PTRACE_EVENT_VFORK | |
1031 | Stop before return from | |
1032 | .BR vfork (2) | |
1033 | or | |
1034 | .BR clone (2) | |
1035 | with the | |
1036 | .B CLONE_VFORK | |
1037 | flag. | |
1038 | When the tracee is continued after this stop, it will wait for child to | |
1039 | exit/exec before continuing its execution | |
1040 | (in other words, the usual behavior on | |
1041 | .BR vfork (2)). | |
1042 | .TP | |
1043 | .B PTRACE_EVENT_FORK | |
1044 | Stop before return from | |
1045 | .BR fork (2) | |
1046 | or | |
1047 | .BR clone (2) | |
1048 | with the exit signal set to | |
1049 | .BR SIGCHLD . | |
1050 | .TP | |
1051 | .B PTRACE_EVENT_CLONE | |
1052 | Stop before return from | |
a5c725cf | 1053 | .BR clone (2). |
181f997f MK |
1054 | .TP |
1055 | .B PTRACE_EVENT_VFORK_DONE | |
1056 | Stop before return from | |
1057 | .BR vfork (2) | |
1058 | or | |
1059 | .BR clone (2) | |
1060 | with the | |
1061 | .B CLONE_VFORK | |
1062 | flag, | |
1063 | but after the child unblocked this tracee by exiting or execing. | |
4d12a715 | 1064 | .LP |
181f997f MK |
1065 | For all four stops described above, |
1066 | the stop occurs in the parent (i.e., the tracee), | |
1067 | not in the newly created thread. | |
1068 | .BR PTRACE_GETEVENTMSG | |
1069 | can be used to retrieve the new thread's ID. | |
1070 | .TP | |
1071 | .B PTRACE_EVENT_EXEC | |
1072 | Stop before return from | |
1073 | .BR execve (2). | |
b16d33ef DV |
1074 | Since Linux 3.0, |
1075 | .BR PTRACE_GETEVENTMSG | |
1076 | returns the former thread ID. | |
181f997f MK |
1077 | .TP |
1078 | .B PTRACE_EVENT_EXIT | |
1079 | Stop before exit (including death from | |
1080 | .BR exit_group (2)), | |
1081 | signal death, or exit caused by | |
1082 | .BR execve (2) | |
1083 | in a multithreaded process. | |
1084 | .B PTRACE_GETEVENTMSG | |
1085 | returns the exit status. | |
8b20acd1 MK |
1086 | Registers can be examined |
1087 | (unlike when "real" exit happens). | |
181f997f MK |
1088 | The tracee is still alive; it needs to be |
1089 | .BR PTRACE_CONT ed | |
1090 | or | |
1091 | .BR PTRACE_DETACH ed | |
1092 | to finish exiting. | |
1093 | .LP | |
1094 | .B PTRACE_GETSIGINFO | |
1095 | on | |
1096 | .B PTRACE_EVENT | |
1097 | stops returns | |
b16d33ef DV |
1098 | .B SIGTRAP |
1099 | in | |
181f997f MK |
1100 | .IR si_signo , |
1101 | with | |
1102 | .I si_code | |
1103 | set to | |
1104 | .IR "(event<<8)\ |\ SIGTRAP" . | |
4d12a715 | 1105 | .SS Syscall-stops |
181f997f MK |
1106 | If the tracee was restarted by |
1107 | .BR PTRACE_SYSCALL , | |
1108 | the tracee enters | |
1109 | syscall-enter-stop just prior to entering any system call. | |
1110 | If the tracer restarts the tracee with | |
1111 | .BR PTRACE_SYSCALL , | |
1112 | the tracee enters syscall-exit-stop when the system call is finished, | |
1113 | or if it is interrupted by a signal. | |
1114 | (That is, signal-delivery-stop never happens between syscall-enter-stop | |
1115 | and syscall-exit-stop; it happens | |
1116 | .I after | |
1117 | syscall-exit-stop.) | |
1118 | .LP | |
1119 | Other possibilities are that the tracee may stop in a | |
1120 | .B PTRACE_EVENT | |
1121 | stop, exit (if it entered | |
1122 | .BR _exit (2) | |
1123 | or | |
1124 | .BR exit_group (2)), | |
1125 | be killed by | |
1126 | .BR SIGKILL , | |
1127 | or die silently (if it is a thread group leader, the | |
1128 | .BR execve (2) | |
1129 | happened in another thread, | |
1130 | and that thread is not traced by the same tracer; | |
1131 | this situation is discussed later). | |
1132 | .LP | |
1133 | Syscall-enter-stop and syscall-exit-stop are observed by the tracer as | |
1134 | .BR waitpid (2) | |
1135 | returning with | |
1136 | .I WIFSTOPPED(status) | |
1137 | true, and | |
1138 | .I WSTOPSIG(status) | |
1139 | giving | |
1140 | .BR SIGTRAP . | |
1141 | If the | |
1142 | .B PTRACE_O_TRACESYSGOOD | |
1143 | option was set by the tracer, then | |
1144 | .I WSTOPSIG(status) | |
1145 | will give the value | |
1146 | .IR "(SIGTRAP\ |\ 0x80)" . | |
4d12a715 DV |
1147 | .LP |
1148 | Syscall-stops can be distinguished from signal-delivery-stop with | |
181f997f MK |
1149 | .B SIGTRAP |
1150 | by querying | |
1151 | .BR PTRACE_GETSIGINFO | |
1152 | for the following cases: | |
1153 | .TP | |
1154 | .IR si_code " <= 0" | |
1155 | .B SIGTRAP | |
7fac88a9 | 1156 | was delivered as a result of a user-space action, |
8898a252 | 1157 | for example, a system call |
181f997f | 1158 | .RB ( tgkill (2), |
8898a252 | 1159 | .BR kill (2), |
181f997f | 1160 | .BR sigqueue (3), |
8898a252 MK |
1161 | etc.), |
1162 | expiration of a POSIX timer, | |
1163 | change of state on a POSIX message queue, | |
1164 | or completion of an asynchronous I/O request. | |
181f997f MK |
1165 | .TP |
1166 | .IR si_code " == SI_KERNEL (0x80)" | |
1167 | .B SIGTRAP | |
1168 | was sent by the kernel. | |
1169 | .TP | |
1170 | .IR si_code " == SIGTRAP or " si_code " == (SIGTRAP|0x80)" | |
1171 | This is a syscall-stop. | |
1172 | .LP | |
1173 | However, syscall-stops happen very often (twice per system call), | |
1174 | and performing | |
1175 | .B PTRACE_GETSIGINFO | |
1176 | for every syscall-stop may be somewhat expensive. | |
1177 | .LP | |
181f997f MK |
1178 | Some architectures allow the cases to be distinguished |
1179 | by examining registers. | |
1180 | For example, on x86, | |
1181 | .I rax | |
1182 | == | |
1183 | .RB - ENOSYS | |
1184 | in syscall-enter-stop. | |
1185 | Since | |
1186 | .B SIGTRAP | |
1187 | (like any other signal) always happens | |
1188 | .I after | |
1189 | syscall-exit-stop, | |
1190 | and at this point | |
1191 | .I rax | |
1192 | almost never contains | |
1193 | .RB - ENOSYS , | |
1194 | the | |
1195 | .B SIGTRAP | |
1196 | looks like "syscall-stop which is not syscall-enter-stop"; | |
1197 | in other words, it looks like a | |
8b20acd1 | 1198 | "stray syscall-exit-stop" and can be detected this way. |
181f997f | 1199 | But such detection is fragile and is best avoided. |
4d12a715 | 1200 | .LP |
181f997f MK |
1201 | Using the |
1202 | .B PTRACE_O_TRACESYSGOOD | |
a17e05c5 | 1203 | option is the recommended method to distinguish syscall-stops |
b8d02d56 | 1204 | from other kinds of ptrace-stops, |
181f997f | 1205 | since it is reliable and does not incur a performance penalty. |
4d12a715 | 1206 | .LP |
181f997f MK |
1207 | Syscall-enter-stop and syscall-exit-stop are |
1208 | indistinguishable from each other by the tracer. | |
1209 | The tracer needs to keep track of the sequence of | |
4d12a715 | 1210 | ptrace-stops in order to not misinterpret syscall-enter-stop as |
8b20acd1 MK |
1211 | syscall-exit-stop or vice versa. |
1212 | The rule is that syscall-enter-stop is | |
181f997f MK |
1213 | always followed by syscall-exit-stop, |
1214 | .B PTRACE_EVENT | |
1215 | stop or the tracee's death; | |
1216 | no other kinds of ptrace-stop can occur in between. | |
4d12a715 | 1217 | .LP |
181f997f MK |
1218 | If after syscall-enter-stop, |
1219 | the tracer uses a restarting command other than | |
1220 | .BR PTRACE_SYSCALL , | |
1221 | syscall-exit-stop is not generated. | |
4d12a715 | 1222 | .LP |
181f997f MK |
1223 | .B PTRACE_GETSIGINFO |
1224 | on syscall-stops returns | |
1225 | .B SIGTRAP | |
1226 | in | |
1227 | .IR si_signo , | |
1228 | with | |
1229 | .I si_code | |
1230 | set to | |
1231 | .B SIGTRAP | |
1232 | or | |
1233 | .IR (SIGTRAP|0x80) . | |
1234 | .SS PTRACE_SINGLESTEP, PTRACE_SYSEMU, PTRACE_SYSEMU_SINGLESTEP stops | |
b8d02d56 | 1235 | [Details of these kinds of stops are yet to be documented.] |
181f997f | 1236 | .\" |
d6e37473 | 1237 | .\" FIXME |
b8d02d56 MK |
1238 | .\" document stops occurring with PTRACE_SINGLESTEP, PTRACE_SYSEMU, |
1239 | .\" PTRACE_SYSEMU_SINGLESTEP | |
4d12a715 | 1240 | .SS Informational and restarting ptrace commands |
181f997f MK |
1241 | Most ptrace commands (all except |
1242 | .BR PTRACE_ATTACH , | |
1243 | .BR PTRACE_TRACEME , | |
1244 | and | |
1245 | .BR PTRACE_KILL ) | |
1246 | require the tracee to be in a ptrace-stop, otherwise they fail with | |
1247 | .BR ESRCH . | |
4d12a715 | 1248 | .LP |
181f997f MK |
1249 | When the tracee is in ptrace-stop, |
1250 | the tracer can read and write data to | |
1251 | the tracee using informational commands. | |
1252 | These commands leave the tracee in ptrace-stopped state: | |
4d12a715 DV |
1253 | .LP |
1254 | .nf | |
181f997f MK |
1255 | ptrace(PTRACE_PEEKTEXT/PEEKDATA/PEEKUSER, pid, addr, 0); |
1256 | ptrace(PTRACE_POKETEXT/POKEDATA/POKEUSER, pid, addr, long_val); | |
1257 | ptrace(PTRACE_GETREGS/GETFPREGS, pid, 0, &struct); | |
1258 | ptrace(PTRACE_SETREGS/SETFPREGS, pid, 0, &struct); | |
1259 | ptrace(PTRACE_GETSIGINFO, pid, 0, &siginfo); | |
1260 | ptrace(PTRACE_SETSIGINFO, pid, 0, &siginfo); | |
1261 | ptrace(PTRACE_GETEVENTMSG, pid, 0, &long_var); | |
1262 | ptrace(PTRACE_SETOPTIONS, pid, 0, PTRACE_O_flags); | |
4d12a715 DV |
1263 | .fi |
1264 | .LP | |
8b20acd1 | 1265 | Note that some errors are not reported. |
181f997f MK |
1266 | For example, setting signal information |
1267 | .RI ( siginfo ) | |
4d12a715 | 1268 | may have no effect in some ptrace-stops, yet the call may succeed |
181f997f MK |
1269 | (return 0 and not set |
1270 | .IR errno ); | |
1271 | querying | |
1272 | .B PTRACE_GETEVENTMSG | |
1273 | may succeed and return some random value if current ptrace-stop | |
1274 | is not documented as returning a meaningful event message. | |
1275 | .LP | |
1276 | The call | |
1277 | ||
1278 | ptrace(PTRACE_SETOPTIONS, pid, 0, PTRACE_O_flags); | |
d6e37473 | 1279 | |
181f997f MK |
1280 | affects one tracee. |
1281 | The tracee's current flags are replaced. | |
1282 | Flags are inherited by new tracees created and "auto-attached" via active | |
1283 | .BR PTRACE_O_TRACEFORK , | |
1284 | .BR PTRACE_O_TRACEVFORK , | |
1285 | or | |
1286 | .BR PTRACE_O_TRACECLONE | |
1287 | options. | |
1288 | .LP | |
1289 | Another group of commands makes the ptrace-stopped tracee run. | |
1290 | They have the form: | |
1291 | .LP | |
8898a252 | 1292 | ptrace(cmd, pid, 0, sig); |
181f997f MK |
1293 | .LP |
1294 | where | |
1295 | .I cmd | |
1296 | is | |
1297 | .BR PTRACE_CONT , | |
1298 | .BR PTRACE_DETACH , | |
1299 | .BR PTRACE_SYSCALL , | |
1300 | .BR PTRACE_SINGLESTEP , | |
1301 | .BR PTRACE_SYSEMU , | |
1302 | or | |
a5c725cf | 1303 | .BR PTRACE_SYSEMU_SINGLESTEP . |
181f997f MK |
1304 | If the tracee is in signal-delivery-stop, |
1305 | .I sig | |
1306 | is the signal to be injected (if it is nonzero). | |
1307 | Otherwise, | |
1308 | .I sig | |
1309 | may be ignored. | |
8898a252 MK |
1310 | (When restarting a tracee from a ptrace-stop other than signal-delivery-stop, |
1311 | recommended practice is to always pass 0 in | |
a5c725cf | 1312 | .IR sig .) |
4d12a715 | 1313 | .SS Attaching and detaching |
181f997f MK |
1314 | A thread can be attached to the tracer using the call |
1315 | ||
1316 | ptrace(PTRACE_ATTACH, pid, 0, 0); | |
1317 | ||
1318 | This also sends | |
1319 | .B SIGSTOP | |
1320 | to this thread. | |
1321 | If the tracer wants this | |
1322 | .B SIGSTOP | |
1323 | to have no effect, it needs to suppress it. | |
1324 | Note that if other signals are concurrently sent to | |
1325 | this thread during attach, | |
1326 | the tracer may see the tracee enter signal-delivery-stop | |
1327 | with other signal(s) first! | |
1328 | The usual practice is to reinject these signals until | |
1329 | .B SIGSTOP | |
1330 | is seen, then suppress | |
1331 | .B SIGSTOP | |
1332 | injection. | |
181f997f MK |
1333 | The design bug here is that a ptrace attach and a concurrently delivered |
1334 | .B SIGSTOP | |
1335 | may race and the concurrent | |
1336 | .B SIGSTOP | |
1337 | may be lost. | |
1338 | .\" | |
b8d02d56 MK |
1339 | .\" FIXME: Describe how to attach to a thread which is already |
1340 | .\" group-stopped. | |
181f997f MK |
1341 | .LP |
1342 | Since attaching sends | |
1343 | .B SIGSTOP | |
1344 | and the tracer usually suppresses it, this may cause a stray | |
a5c725cf | 1345 | .B EINTR |
181f997f | 1346 | return from the currently executing system call in the tracee, |
a5c725cf | 1347 | as described in the "Signal injection and suppression" section. |
181f997f MK |
1348 | .LP |
1349 | The request | |
1350 | ||
1351 | ptrace(PTRACE_TRACEME, 0, 0, 0); | |
1352 | ||
1353 | turns the calling thread into a tracee. | |
1354 | The thread continues to run (doesn't enter ptrace-stop). | |
1355 | A common practice is to follow the | |
1356 | .B PTRACE_TRACEME | |
1357 | with | |
1358 | ||
1359 | raise(SIGSTOP); | |
1360 | ||
1361 | and allow the parent (which is our tracer now) to observe our | |
4d12a715 DV |
1362 | signal-delivery-stop. |
1363 | .LP | |
d6e37473 | 1364 | If the |
181f997f MK |
1365 | .BR PTRACE_O_TRACEFORK , |
1366 | .BR PTRACE_O_TRACEVFORK , | |
1367 | or | |
1368 | .BR PTRACE_O_TRACECLONE | |
1369 | options are in effect, then children created by, respectively, | |
1370 | .BR vfork (2) | |
1371 | or | |
1372 | .BR clone (2) | |
1373 | with the | |
1374 | .B CLONE_VFORK | |
1375 | flag, | |
1376 | .BR fork (2) | |
1377 | or | |
1378 | .BR clone (2) | |
1379 | with the exit signal set to | |
1380 | .BR SIGCHLD , | |
1381 | and other kinds of | |
1382 | .BR clone (2), | |
1383 | are automatically attached to the same tracer which traced their parent. | |
1384 | .B SIGSTOP | |
1385 | is delivered to the children, causing them to enter | |
1386 | signal-delivery-stop after they exit the system call which created them. | |
1387 | .LP | |
1388 | Detaching of the tracee is performed by: | |
1389 | ||
1390 | ptrace(PTRACE_DETACH, pid, 0, sig); | |
1391 | ||
1392 | .B PTRACE_DETACH | |
1393 | is a restarting operation; | |
1394 | therefore it requires the tracee to be in ptrace-stop. | |
1395 | If the tracee is in signal-delivery-stop, a signal can be injected. | |
1396 | Otherwise, the | |
1397 | .I sig | |
1398 | parameter may be silently ignored. | |
1399 | .LP | |
1400 | If the tracee is running when the tracer wants to detach it, | |
1401 | the usual solution is to send | |
1402 | .B SIGSTOP | |
1403 | (using | |
1404 | .BR tgkill (2), | |
1405 | to make sure it goes to the correct thread), | |
1406 | wait for the tracee to stop in signal-delivery-stop for | |
1407 | .B SIGSTOP | |
1408 | and then detach it (suppressing | |
1409 | .B SIGSTOP | |
1410 | injection). | |
1411 | A design bug is that this can race with concurrent | |
1412 | .BR SIGSTOP s. | |
1413 | Another complication is that the tracee may enter other ptrace-stops | |
1414 | and needs to be restarted and waited for again, until | |
1415 | .B SIGSTOP | |
1416 | is seen. | |
1417 | Yet another complication is to be sure that | |
1418 | the tracee is not already ptrace-stopped, | |
1419 | because no signal delivery happens while it is\(emnot even | |
1420 | .BR SIGSTOP . | |
b8d02d56 MK |
1421 | .\" FIXME: Describe how to detach from a group-stopped tracee so that it |
1422 | .\" doesn't run, but continues to wait for SIGCONT. | |
181f997f MK |
1423 | .LP |
1424 | If the tracer dies, all tracees are automatically detached and restarted, | |
8b20acd1 | 1425 | unless they were in group-stop. |
b8d02d56 MK |
1426 | Handling of restart from group-stop is currently buggy, |
1427 | but the "as planned" behavior is to leave tracee stopped and waiting for | |
181f997f MK |
1428 | .BR SIGCONT . |
1429 | If the tracee is restarted from signal-delivery-stop, | |
1430 | the pending signal is injected. | |
1431 | .SS execve(2) under ptrace | |
cb729171 | 1432 | .\" clone(2) CLONE_THREAD says: |
181f997f MK |
1433 | .\" If any of the threads in a thread group performs an execve(2), |
1434 | .\" then all threads other than the thread group leader are terminated, | |
d6e37473 | 1435 | .\" and the new program is executed in the thread group leader. |
181f997f | 1436 | .\" |
8898a252 | 1437 | When one thread in a multithreaded process calls |
181f997f MK |
1438 | .BR execve (2), |
1439 | the kernel destroys all other threads in the process, | |
1440 | .\" In kernel 3.1 sources, see fs/exec.c::de_thread() | |
1441 | and resets the thread ID of the execing thread to the | |
1442 | thread group ID (process ID). | |
181f997f MK |
1443 | (Or, to put things another way, when a multithreaded process does an |
1444 | .BR execve (2), | |
8898a252 | 1445 | at completion of the call, it appears as though the |
181f997f MK |
1446 | .BR execve (2) |
1447 | occurred in the thread group leader, regardless of which thread did the | |
1448 | .BR execve (2).) | |
181f997f MK |
1449 | This resetting of the thread ID looks very confusing to tracers: |
1450 | .IP * 3 | |
1451 | All other threads stop in | |
8898a252 | 1452 | .B PTRACE_EVENT_EXIT |
b8d02d56 | 1453 | stop, if the |
8898a252 MK |
1454 | .BR PTRACE_O_TRACEEXIT |
1455 | option was turned on. | |
181f997f MK |
1456 | Then all other threads except the thread group leader report |
1457 | death as if they exited via | |
1458 | .BR _exit (2) | |
1459 | with exit code 0. | |
b8d02d56 | 1460 | .IP * |
181f997f MK |
1461 | The execing tracee changes its thread ID while it is in the |
1462 | .BR execve (2). | |
1463 | (Remember, under ptrace, the "pid" returned from | |
1464 | .BR waitpid (2), | |
1465 | or fed into ptrace calls, is the tracee's thread ID.) | |
1466 | That is, the tracee's thread ID is reset to be the same as its process ID, | |
1467 | which is the same as the thread group leader's thread ID. | |
1468 | .IP * | |
f098951d DV |
1469 | Then a |
1470 | .B PTRACE_EVENT_EXEC | |
1471 | stop happens, if the | |
1472 | .BR PTRACE_O_TRACEEXEC | |
1473 | option was turned on. | |
1474 | .IP * | |
1475 | If the thread group leader has reported its | |
1476 | .B PTRACE_EVENT_EXIT | |
1477 | stop by this time, | |
181f997f MK |
1478 | it appears to the tracer that |
1479 | the dead thread leader "reappears from nowhere". | |
a17e05c5 | 1480 | (Note: the thread group leader does not report death via |
f098951d DV |
1481 | .I WIFEXITED(status) |
1482 | until there is at least one other live thread. | |
a17e05c5 | 1483 | This eliminates the possibility that the tracer will see |
f098951d | 1484 | it dying and then reappearing.) |
181f997f MK |
1485 | If the thread group leader was still alive, |
1486 | for the tracer this may look as if thread group leader | |
1487 | returns from a different system call than it entered, | |
1488 | or even "returned from a system call even though | |
1489 | it was not in any system call". | |
1490 | If the thread group leader was not traced | |
1491 | (or was traced by a different tracer), then during | |
1492 | .BR execve (2) | |
1493 | it will appear as if it has become a tracee of | |
1494 | the tracer of the execing tracee. | |
4d12a715 | 1495 | .LP |
181f997f MK |
1496 | All of the above effects are the artifacts of |
1497 | the thread ID change in the tracee. | |
4d12a715 | 1498 | .LP |
181f997f MK |
1499 | The |
1500 | .B PTRACE_O_TRACEEXEC | |
1501 | option is the recommended tool for dealing with this situation. | |
b8d02d56 | 1502 | First, it enables |
a5c725cf DP |
1503 | .BR PTRACE_EVENT_EXEC |
1504 | stop, | |
b8d02d56 | 1505 | which occurs before |
a5c725cf | 1506 | .BR execve (2) |
b8d02d56 MK |
1507 | returns. |
1508 | In this stop, the tracer can use | |
1509 | .B PTRACE_GETEVENTMSG | |
1510 | to retrieve the tracee's former thread ID. | |
1511 | (This feature was introduced in Linux 3.0). | |
1512 | Second, the | |
1513 | .B PTRACE_O_TRACEEXEC | |
1514 | option disables legacy | |
1515 | .B SIGTRAP | |
1516 | generation on | |
1517 | .BR execve (2). | |
181f997f MK |
1518 | .LP |
1519 | When the tracer receives | |
1520 | .B PTRACE_EVENT_EXEC | |
1521 | stop notification, | |
1522 | it is guaranteed that except this tracee and the thread group leader, | |
1523 | no other threads from the process are alive. | |
1524 | .LP | |
1525 | On receiving the | |
1526 | .B PTRACE_EVENT_EXEC | |
1527 | stop notification, | |
1528 | the tracer should clean up all its internal | |
1529 | data structures describing the threads of this process, | |
1530 | and retain only one data structure\(emone which | |
1531 | describes the single still running tracee, with | |
1532 | ||
f098951d | 1533 | thread ID == thread group ID == process ID. |
181f997f MK |
1534 | .LP |
1535 | Example: two threads call | |
1536 | .BR execve (2) | |
1537 | at the same time: | |
4d12a715 DV |
1538 | .LP |
1539 | .nf | |
a5c725cf | 1540 | *** we get syscall-enter-stop in thread 1: ** |
4d12a715 DV |
1541 | PID1 execve("/bin/foo", "foo" <unfinished ...> |
1542 | *** we issue PTRACE_SYSCALL for thread 1 ** | |
a5c725cf | 1543 | *** we get syscall-enter-stop in thread 2: ** |
4d12a715 DV |
1544 | PID2 execve("/bin/bar", "bar" <unfinished ...> |
1545 | *** we issue PTRACE_SYSCALL for thread 2 ** | |
1546 | *** we get PTRACE_EVENT_EXEC for PID0, we issue PTRACE_SYSCALL ** | |
1547 | *** we get syscall-exit-stop for PID0: ** | |
1548 | PID0 <... execve resumed> ) = 0 | |
1549 | .fi | |
1550 | .LP | |
181f997f MK |
1551 | If the |
1552 | .B PTRACE_O_TRACEEXEC | |
1553 | option is | |
1554 | .I not | |
1555 | in effect for the execing tracee, the kernel delivers an extra | |
1556 | .B SIGTRAP | |
1557 | to the tracee after | |
1558 | .BR execve (2) | |
8b20acd1 MK |
1559 | returns. |
1560 | This is an ordinary signal (similar to one which can be | |
181f997f MK |
1561 | generated by |
1562 | .IR "kill -TRAP" ), | |
1563 | not a special kind of ptrace-stop. | |
1564 | Employing | |
1565 | .B PTRACE_GETSIGINFO | |
1566 | for this signal returns | |
1567 | .I si_code | |
1568 | set to 0 | |
1569 | .RI ( SI_USER ). | |
1570 | This signal may be blocked by signal mask, | |
1571 | and thus may be delivered (much) later. | |
1572 | .LP | |
1573 | Usually, the tracer (for example, | |
1574 | .BR strace (1)) | |
1575 | would not want to show this extra post-execve | |
1576 | .B SIGTRAP | |
1577 | signal to the user, and would suppress its delivery to the tracee (if | |
1578 | .B SIGTRAP | |
1579 | is set to | |
1580 | .BR SIG_DFL , | |
1581 | it is a killing signal). | |
d6e37473 | 1582 | However, determining |
181f997f MK |
1583 | .I which |
1584 | .B SIGTRAP | |
1585 | to suppress is not easy. | |
1586 | Setting the | |
1587 | .B PTRACE_O_TRACEEXEC | |
1588 | option and thus suppressing this extra | |
1589 | .B SIGTRAP | |
1590 | is the recommended approach. | |
4d12a715 | 1591 | .SS Real parent |
181f997f MK |
1592 | The ptrace API (ab)uses the standard UNIX parent/child signaling over |
1593 | .BR waitpid (2). | |
1594 | This used to cause the real parent of the process to stop receiving | |
1595 | several kinds of | |
1596 | .BR waitpid (2) | |
1597 | notifications when the child process is traced by some other process. | |
1598 | .LP | |
1599 | Many of these bugs have been fixed, but as of Linux 2.6.38 several still | |
1600 | exist; see BUGS below. | |
1601 | .LP | |
1602 | As of Linux 2.6.38, the following is believed to work correctly: | |
1603 | .IP * 3 | |
dc85ba7c MK |
1604 | exit/death by signal is reported first to the tracer, then, |
1605 | when the tracer consumes the | |
181f997f MK |
1606 | .BR waitpid (2) |
1607 | result, to the real parent (to the real parent only when the | |
1608 | whole multithreaded process exits). | |
181f997f MK |
1609 | If the tracer and the real parent are the same process, |
1610 | the report is sent only once. | |
2b2581ee | 1611 | .SH "RETURN VALUE" |
988db661 | 1612 | On success, |
0daa9e92 | 1613 | .B PTRACE_PEEK* |
8bd58774 | 1614 | requests return the requested data, |
2b2581ee MK |
1615 | while other requests return zero. |
1616 | On error, all requests return \-1, and | |
1617 | .I errno | |
1618 | is set appropriately. | |
8bd58774 | 1619 | Since the value returned by a successful |
0daa9e92 | 1620 | .B PTRACE_PEEK* |
181f997f | 1621 | request may be \-1, the caller must clear |
2b2581ee | 1622 | .I errno |
181f997f MK |
1623 | before the call, and then check it afterward |
1624 | to determine whether or not an error occurred. | |
2b2581ee MK |
1625 | .SH ERRORS |
1626 | .TP | |
1627 | .B EBUSY | |
181f997f | 1628 | (i386 only) There was an error with allocating or freeing a debug register. |
2b2581ee MK |
1629 | .TP |
1630 | .B EFAULT | |
1631 | There was an attempt to read from or write to an invalid area in | |
181f997f | 1632 | the tracer's or the tracee's memory, |
2b2581ee MK |
1633 | probably because the area wasn't mapped or accessible. |
1634 | Unfortunately, under Linux, different variations of this fault | |
2f0af33b MK |
1635 | will return |
1636 | .B EIO | |
1637 | or | |
1638 | .B EFAULT | |
1639 | more or less arbitrarily. | |
2b2581ee MK |
1640 | .TP |
1641 | .B EINVAL | |
1642 | An attempt was made to set an invalid option. | |
1643 | .TP | |
1644 | .B EIO | |
181f997f MK |
1645 | .I request |
1646 | is invalid, or an attempt was made to read from or | |
1647 | write to an invalid area in the tracer's or the tracee's memory, | |
2b2581ee MK |
1648 | or there was a word-alignment violation, |
1649 | or an invalid signal was specified during a restart request. | |
1650 | .TP | |
1651 | .B EPERM | |
1652 | The specified process cannot be traced. | |
1653 | This could be because the | |
4d12a715 | 1654 | tracer has insufficient privileges (the required capability is |
2b2581ee | 1655 | .BR CAP_SYS_PTRACE ); |
00b08db3 | 1656 | unprivileged processes cannot trace processes that they |
2b2581ee MK |
1657 | cannot send signals to or those running |
1658 | set-user-ID/set-group-ID programs, for obvious reasons. | |
181f997f MK |
1659 | Alternatively, the process may already be being traced, |
1660 | or (on kernels before 2.6.26) be | |
66ee0c7e | 1661 | .BR init (8) |
2b2581ee MK |
1662 | (PID 1). |
1663 | .TP | |
1664 | .B ESRCH | |
1665 | The specified process does not exist, or is not currently being traced | |
181f997f MK |
1666 | by the caller, or is not stopped |
1667 | (for requests that require a stopped tracee). | |
2b2581ee | 1668 | .SH "CONFORMING TO" |
44a2c328 | 1669 | SVr4, 4.3BSD. |
fea681da MK |
1670 | .SH NOTES |
1671 | Although arguments to | |
e511ffb6 | 1672 | .BR ptrace () |
c13182ef | 1673 | are interpreted according to the prototype given, |
5260fe08 | 1674 | glibc currently declares |
e511ffb6 | 1675 | .BR ptrace () |
181f997f MK |
1676 | as a variadic function with only the |
1677 | .I request | |
1678 | argument fixed. | |
ca302d0e DV |
1679 | It is recommended to always supply four arguments, |
1680 | even if the requested operation does not use them, | |
1681 | setting unused/ignored arguments to | |
1682 | .I 0L | |
1683 | or | |
1684 | .IR "(void\ *)\ 0". | |
181f997f MK |
1685 | .LP |
1686 | In Linux kernels before 2.6.26, | |
1687 | .\" See commit 00cd5c37afd5f431ac186dd131705048c0a11fdb | |
1688 | .BR init (8), | |
1689 | the process with PID 1, may not be traced. | |
1690 | .LP | |
1691 | The layout of the contents of memory and the USER area are | |
1692 | quite operating-system- and architecture-specific. | |
8660aec0 MK |
1693 | The offset supplied, and the data returned, |
1694 | might not entirely match with the definition of | |
1695 | .IR "struct user" . | |
1696 | .\" See http://lkml.org/lkml/2008/5/8/375 | |
fea681da | 1697 | .LP |
181f997f | 1698 | The size of a "word" is determined by the operating-system variant |
3e18f289 | 1699 | (e.g., for 32-bit Linux it is 32 bits). |
b8d02d56 | 1700 | .LP |
fea681da | 1701 | This page documents the way the |
e511ffb6 | 1702 | .BR ptrace () |
c13182ef | 1703 | call works currently in Linux. |
008f1ecc | 1704 | Its behavior differs noticeably on other flavors of UNIX. |
e63ad01d | 1705 | In any case, use of |
e511ffb6 | 1706 | .BR ptrace () |
181f997f | 1707 | is highly specific to the operating system and architecture. |
a1d5f77c | 1708 | .SH BUGS |
8bd58774 | 1709 | On hosts with 2.6 kernel headers, |
0daa9e92 | 1710 | .B PTRACE_SETOPTIONS |
181f997f MK |
1711 | is declared with a different value than the one for 2.4. |
1712 | This leads to applications compiled with 2.6 kernel | |
a1d5f77c | 1713 | headers failing when run on 2.4 kernels. |
8bd58774 | 1714 | This can be worked around by redefining |
0daa9e92 | 1715 | .B PTRACE_SETOPTIONS |
8bd58774 MK |
1716 | to |
1717 | .BR PTRACE_OLDSETOPTIONS , | |
1718 | if that is defined. | |
4d12a715 | 1719 | .LP |
181f997f | 1720 | Group-stop notifications are sent to the tracer, but not to real parent. |
4d12a715 DV |
1721 | Last confirmed on 2.6.38.6. |
1722 | .LP | |
181f997f MK |
1723 | If a thread group leader is traced and exits by calling |
1724 | .BR _exit (2), | |
8898a252 MK |
1725 | .\" Note from Denys Vlasenko: |
1726 | .\" Here "exits" means any kind of death - _exit, exit_group, | |
1727 | .\" signal death. Signal death and exit_group cases are trivial, | |
1728 | .\" though: since signal death and exit_group kill all other threads | |
1729 | .\" too, "until all other threads exit" thing happens rather soon | |
1730 | .\" in these cases. Therefore, only _exit presents observably | |
1731 | .\" puzzling behavior to ptrace users: thread leader _exit's, | |
1732 | .\" but WIFEXITED isn't reported! We are trying to explain here | |
1733 | .\" why it is so. | |
181f997f MK |
1734 | a |
1735 | .B PTRACE_EVENT_EXIT | |
1736 | stop will happen for it (if requested), but the subsequent | |
1737 | .B WIFEXITED | |
1738 | notification will not be delivered until all other threads exit. | |
1739 | As explained above, if one of other threads calls | |
1740 | .BR execve (2), | |
1741 | the death of the thread group leader will | |
1742 | .I never | |
1743 | be reported. | |
1744 | If the execed thread is not traced by this tracer, | |
1745 | the tracer will never know that | |
1746 | .BR execve (2) | |
4d12a715 | 1747 | happened. |
181f997f MK |
1748 | One possible workaround is to |
1749 | .B PTRACE_DETACH | |
1750 | the thread group leader instead of restarting it in this case. | |
1751 | Last confirmed on 2.6.38.6. | |
b8d02d56 | 1752 | .\" FIXME: ^^^ need to test/verify this scenario |
181f997f MK |
1753 | .LP |
1754 | A | |
1755 | .B SIGKILL | |
1756 | signal may still cause a | |
1757 | .B PTRACE_EVENT_EXIT | |
1758 | stop before actual signal death. | |
1759 | This may be changed in the future; | |
1760 | .B SIGKILL | |
1761 | is meant to always immediately kill tasks even under ptrace. | |
8b20acd1 | 1762 | Last confirmed on 2.6.38.6. |
f098951d | 1763 | .LP |
a17e05c5 | 1764 | Some system calls return with |
f098951d | 1765 | .B EINTR |
a17e05c5 MK |
1766 | if a signal was sent to a tracee, but delivery was suppressed by the tracer. |
1767 | (This is very typical operation: it is usually | |
f098951d | 1768 | done by debuggers on every attach, in order to not introduce |
a17e05c5 MK |
1769 | a bogus |
1770 | .BR SIGSTOP ). | |
1771 | As of Linux 3.2.9, the following system calls are affected | |
1772 | (this list is likely incomplete): | |
f098951d | 1773 | .BR epoll_wait (2), |
a17e05c5 | 1774 | and |
f098951d | 1775 | .BR read (2) |
a17e05c5 MK |
1776 | from an |
1777 | .BR inotify (7) | |
1778 | file descriptor. | |
ca302d0e DV |
1779 | The usual symptom of this bug is that when you attach to |
1780 | a quiescent process with the command | |
11c85ed8 | 1781 | |
ca302d0e DV |
1782 | strace -p <process-ID> |
1783 | ||
1784 | then, instead of the usual | |
1785 | and expected one-line output such as | |
1786 | .nf | |
1787 | ||
1788 | restart_syscall(<... resuming interrupted call ...>_ | |
1789 | ||
1790 | .fi | |
1791 | or | |
1792 | .nf | |
1793 | ||
1794 | select(6, [5], NULL, [5], NULL_ | |
1795 | ||
1796 | .fi | |
1797 | ('_' denotes the cursor position), you observe more than one line. | |
1798 | For example: | |
1799 | .nf | |
1800 | ||
1801 | clock_gettime(CLOCK_MONOTONIC, {15370, 690928118}) = 0 | |
1802 | epoll_wait(4,_ | |
1803 | ||
1804 | .fi | |
1805 | What is not visible here is that the process was blocked in | |
1806 | .BR epoll_wait (2) | |
1807 | before | |
1808 | .BR strace (1) | |
1809 | has attached to it. | |
1810 | Attaching caused | |
1811 | .BR epoll_wait (2) | |
7fac88a9 | 1812 | to return to user space with the error |
ca302d0e DV |
1813 | .BR EINTR . |
1814 | In this particular case, the program reacted to | |
1815 | .B EINTR | |
b0b1d9b5 | 1816 | by checking the current time, and then executing |
ca302d0e DV |
1817 | .BR epoll_wait (2) |
1818 | again. | |
1819 | (Programs which do not expect such "stray" | |
1820 | .BR EINTR | |
1821 | errors may behave in an unintended way upon an | |
1822 | .BR strace (1) | |
1823 | attach.) | |
fea681da MK |
1824 | .SH "SEE ALSO" |
1825 | .BR gdb (1), | |
1826 | .BR strace (1), | |
181f997f | 1827 | .BR clone (2), |
fea681da MK |
1828 | .BR execve (2), |
1829 | .BR fork (2), | |
181f997f MK |
1830 | .BR gettid (2), |
1831 | .BR sigaction (2), | |
1832 | .BR tgkill (2), | |
1833 | .BR vfork (2), | |
1834 | .BR waitpid (2), | |
fea681da | 1835 | .BR exec (3), |
181f997f MK |
1836 | .BR capabilities (7), |
1837 | .BR signal (7) |