]>
Commit | Line | Data |
---|---|---|
181f997f | 1 | .\" Copyright (c) 1993 Michael Haardt <michael@moria.de> |
fea681da MK |
2 | .\" Fri Apr 2 11:32:09 MET DST 1993 |
3 | .\" | |
181f997f | 4 | .\" and changes Copyright (C) 1999 Mike Coleman (mkc@acm.org) |
fea681da | 5 | .\" -- major revision to fully document ptrace semantics per recent Linux |
c13182ef | 6 | .\" kernel (2.2.10) and glibc (2.1.2) |
fea681da MK |
7 | .\" Sun Nov 7 03:18:35 CST 1999 |
8 | .\" | |
181f997f | 9 | .\" and Copyright (c) 2011, Denys Vlasenko <vda.linux@googlemail.com> |
b0459842 | 10 | .\" and Copyright (c) 2015, 2016, Michael Kerrisk <mtk.manpages@gmail.com> |
181f997f | 11 | .\" |
e4a74ca8 | 12 | .\" SPDX-License-Identifier: GPL-2.0-or-later |
fea681da MK |
13 | .\" |
14 | .\" Modified Fri Jul 23 23:47:18 1993 by Rik Faith <faith@cs.unc.edu> | |
15 | .\" Modified Fri Jan 31 16:46:30 1997 by Eric S. Raymond <esr@thyrsus.com> | |
16 | .\" Modified Thu Oct 7 17:28:49 1999 by Andries Brouwer <aeb@cwi.nl> | |
c11b1abf | 17 | .\" Modified, 27 May 2004, Michael Kerrisk <mtk.manpages@gmail.com> |
fea681da MK |
18 | .\" Added notes on capability requirements |
19 | .\" | |
44b35ee0 MK |
20 | .\" 2006-03-24, Chuck Ebbert <76306.1226@compuserve.com> |
21 | .\" Added PTRACE_SETOPTIONS, PTRACE_GETEVENTMSG, PTRACE_GETSIGINFO, | |
22 | .\" PTRACE_SETSIGINFO, PTRACE_SYSEMU, PTRACE_SYSEMU_SINGLESTEP | |
23 | .\" (Thanks to Blaisorblade, Daniel Jacobowitz and others who helped.) | |
181f997f | 24 | .\" 2011-09, major update by Denys Vlasenko <vda.linux@googlemail.com> |
3b4a59c4 KC |
25 | .\" 2015-01, Kees Cook <keescook@chromium.org> |
26 | .\" Added PTRACE_O_TRACESECCOMP, PTRACE_EVENT_SECCOMP | |
44b35ee0 | 27 | .\" |
65ba6523 MK |
28 | .\" FIXME The following are undocumented: |
29 | .\" | |
02418dd0 | 30 | .\" PTRACE_GETWMMXREGS |
65ba6523 MK |
31 | .\" PTRACE_SETWMMXREGS |
32 | .\" ARM | |
33 | .\" Linux 2.6.12 | |
34 | .\" | |
35 | .\" PTRACE_SET_SYSCALL | |
36 | .\" ARM and ARM64 | |
37 | .\" Linux 2.6.16 | |
38 | .\" commit 3f471126ee53feb5e9b210ea2f525ed3bb9b7a7f | |
39 | .\" Author: Nicolas Pitre <nico@cam.org> | |
40 | .\" Date: Sat Jan 14 19:30:04 2006 +0000 | |
41 | .\" | |
42 | .\" PTRACE_GETCRUNCHREGS | |
43 | .\" PTRACE_SETCRUNCHREGS | |
44 | .\" ARM | |
45 | .\" Linux 2.6.18 | |
46 | .\" commit 3bec6ded282b331552587267d67a06ed7fd95ddd | |
47 | .\" Author: Lennert Buytenhek <buytenh@wantstofly.org> | |
48 | .\" Date: Tue Jun 27 22:56:18 2006 +0100 | |
49 | .\" | |
50 | .\" PTRACE_GETVFPREGS | |
51 | .\" PTRACE_SETVFPREGS | |
52 | .\" ARM and ARM64 | |
53 | .\" Linux 2.6.30 | |
54 | .\" commit 3d1228ead618b88e8606015cbabc49019981805d | |
55 | .\" Author: Catalin Marinas <catalin.marinas@arm.com> | |
56 | .\" Date: Wed Feb 11 13:12:56 2009 +0100 | |
57 | .\" | |
58 | .\" PTRACE_GETHBPREGS | |
59 | .\" PTRACE_SETHBPREGS | |
60 | .\" ARM and ARM64 | |
61 | .\" Linux 2.6.37 | |
62 | .\" commit 864232fa1a2f8dfe003438ef0851a56722740f3e | |
63 | .\" Author: Will Deacon <will.deacon@arm.com> | |
64 | .\" Date: Fri Sep 3 10:42:55 2010 +0100 | |
65 | .\" | |
66 | .\" PTRACE_SINGLEBLOCK | |
c7391615 | 67 | .\" Since at least Linux 2.4.0 on various architectures |
65ba6523 MK |
68 | .\" Since Linux 2.6.25 on x86 (and others?) |
69 | .\" commit 5b88abbf770a0e1975c668743100f42934f385e8 | |
70 | .\" Author: Roland McGrath <roland@redhat.com> | |
71 | .\" Date: Wed Jan 30 13:30:53 2008 +0100 | |
72 | .\" ptrace: generic PTRACE_SINGLEBLOCK | |
73 | .\" | |
74 | .\" PTRACE_GETFPXREGS | |
75 | .\" PTRACE_SETFPXREGS | |
c7391615 | 76 | .\" Since at least Linux 2.4.0 on various architectures |
65ba6523 | 77 | .\" |
65ba6523 MK |
78 | .\" PTRACE_GETFDPIC |
79 | .\" PTRACE_GETFDPIC_EXEC | |
80 | .\" PTRACE_GETFDPIC_INTERP | |
81 | .\" blackfin, c6x, frv, sh | |
82 | .\" First appearance in Linux 2.6.11 on frv | |
3b1fdaf3 | 83 | .\" |
a47c1f44 MK |
84 | .\" and others that can be found in the arch/*/include/uapi/asm/ptrace files |
85 | .\" | |
45186a5d | 86 | .TH PTRACE 2 2021-03-22 "Linux man-pages (unreleased)" |
fea681da MK |
87 | .SH NAME |
88 | ptrace \- process trace | |
cd9edf03 AC |
89 | .SH LIBRARY |
90 | Standard C library | |
8fc3b2cf | 91 | .RI ( libc ", " \-lc ) |
fea681da | 92 | .SH SYNOPSIS |
44b35ee0 | 93 | .nf |
fea681da | 94 | .B #include <sys/ptrace.h> |
68e4db0a | 95 | .PP |
77ca5b1d | 96 | .BI "long ptrace(enum __ptrace_request " request ", pid_t " pid , |
44b35ee0 MK |
97 | .BI " void *" addr ", void *" data ); |
98 | .fi | |
fea681da MK |
99 | .SH DESCRIPTION |
100 | The | |
e511ffb6 | 101 | .BR ptrace () |
181f997f MK |
102 | system call provides a means by which one process (the "tracer") |
103 | may observe and control the execution of another process (the "tracee"), | |
104 | and examine and change the tracee's memory and registers. | |
e63ad01d | 105 | It is primarily used to implement breakpoint debugging and system |
fea681da | 106 | call tracing. |
dd3568a1 | 107 | .PP |
8898a252 | 108 | A tracee first needs to be attached to the tracer. |
181f997f MK |
109 | Attachment and subsequent commands are per thread: |
110 | in a multithreaded process, | |
111 | every thread can be individually attached to a | |
112 | (potentially different) tracer, | |
113 | or left not attached and thus not debugged. | |
114 | Therefore, "tracee" always means "(one) thread", | |
115 | never "a (possibly multithreaded) process". | |
8b20acd1 | 116 | Ptrace commands are always sent to |
181f997f | 117 | a specific tracee using a call of the form |
efeece04 | 118 | .PP |
1ae6b2c7 AC |
119 | .in +4n |
120 | .EX | |
121 | ptrace(PTRACE_foo, pid, ...) | |
122 | .EE | |
123 | .in | |
efeece04 | 124 | .PP |
181f997f MK |
125 | where |
126 | .I pid | |
127 | is the thread ID of the corresponding Linux thread. | |
dd3568a1 | 128 | .PP |
8898a252 MK |
129 | (Note that in this page, a "multithreaded process" |
130 | means a thread group consisting of threads created using the | |
131 | .BR clone (2) | |
132 | .B CLONE_THREAD | |
133 | flag.) | |
dd3568a1 | 134 | .PP |
181f997f | 135 | A process can initiate a trace by calling |
c13182ef | 136 | .BR fork (2) |
8bd58774 MK |
137 | and having the resulting child do a |
138 | .BR PTRACE_TRACEME , | |
e63ad01d | 139 | followed (typically) by an |
4d12a715 | 140 | .BR execve (2). |
181f997f | 141 | Alternatively, one process may commence tracing another process using |
ba8f446e DV |
142 | .B PTRACE_ATTACH |
143 | or | |
144 | .BR PTRACE_SEIZE . | |
dd3568a1 | 145 | .PP |
4d12a715 | 146 | While being traced, the tracee will stop each time a signal is delivered, |
c13182ef | 147 | even if the signal is being ignored. |
181f997f | 148 | (An exception is |
8bd58774 MK |
149 | .BR SIGKILL , |
150 | which has its usual effect.) | |
181f997f MK |
151 | The tracer will be notified at its next call to |
152 | .BR waitpid (2) | |
8898a252 MK |
153 | (or one of the related "wait" system calls); that call will return a |
154 | .I status | |
155 | value containing information that indicates | |
156 | the cause of the stop in the tracee. | |
157 | While the tracee is stopped, | |
158 | the tracer can use various ptrace requests to inspect and modify the tracee. | |
4d12a715 | 159 | The tracer then causes the tracee to continue, |
e63ad01d | 160 | optionally ignoring the delivered signal |
fea681da | 161 | (or even delivering a different signal instead). |
dd3568a1 | 162 | .PP |
d39a9b98 | 163 | If the |
b16ecdae DV |
164 | .B PTRACE_O_TRACEEXEC |
165 | option is not in effect, all successful calls to | |
166 | .BR execve (2) | |
d39a9b98 | 167 | by the traced process will cause it to be sent a |
b16ecdae | 168 | .B SIGTRAP |
d39a9b98 | 169 | signal, |
b16ecdae DV |
170 | giving the parent a chance to gain control before the new program |
171 | begins execution. | |
dd3568a1 | 172 | .PP |
181f997f | 173 | When the tracer is finished tracing, it can cause the tracee to continue |
4d12a715 | 174 | executing in a normal, untraced mode via |
8bd58774 | 175 | .BR PTRACE_DETACH . |
dd3568a1 | 176 | .PP |
181f997f MK |
177 | The value of |
178 | .I request | |
179 | determines the action to be performed: | |
fea681da | 180 | .TP |
8bd58774 | 181 | .B PTRACE_TRACEME |
181f997f | 182 | Indicate that this process is to be traced by its parent. |
c13182ef MK |
183 | A process probably shouldn't make this request if its parent |
184 | isn't expecting to trace it. | |
181f997f MK |
185 | .RI ( pid , |
186 | .IR addr , | |
187 | and | |
1ae6b2c7 | 188 | .I data |
181f997f | 189 | are ignored.) |
a71b27f8 | 190 | .IP |
181f997f MK |
191 | The |
192 | .B PTRACE_TRACEME | |
193 | request is used only by the tracee; | |
194 | the remaining requests are used only by the tracer. | |
195 | In the following requests, | |
196 | .I pid | |
197 | specifies the thread ID of the tracee to be acted on. | |
8bd58774 | 198 | For requests other than |
ba8f446e DV |
199 | .BR PTRACE_ATTACH , |
200 | .BR PTRACE_SEIZE , | |
a797afac | 201 | .BR PTRACE_INTERRUPT , |
b16ecdae | 202 | and |
8bd58774 | 203 | .BR PTRACE_KILL , |
4d12a715 | 204 | the tracee must be stopped. |
fea681da | 205 | .TP |
8bd58774 | 206 | .BR PTRACE_PEEKTEXT ", " PTRACE_PEEKDATA |
181f997f | 207 | Read a word at the address |
0daa9e92 | 208 | .I addr |
4d12a715 | 209 | in the tracee's memory, returning the word as the result of the |
e511ffb6 | 210 | .BR ptrace () |
c13182ef | 211 | call. |
181f997f MK |
212 | Linux does not have separate text and data address spaces, |
213 | so these two requests are currently equivalent. | |
214 | .RI ( data | |
051ec121 | 215 | is ignored; but see NOTES.) |
fea681da | 216 | .TP |
428d3520 | 217 | .B PTRACE_PEEKUSER |
254255af MK |
218 | .\" PTRACE_PEEKUSR in kernel source, but glibc uses PTRACE_PEEKUSER, |
219 | .\" and that is the name that seems common on other systems. | |
181f997f | 220 | Read a word at offset |
fea681da | 221 | .I addr |
4d12a715 | 222 | in the tracee's USER area, |
8bd58774 | 223 | which holds the registers and other information about the process |
181f997f MK |
224 | (see |
225 | .IR <sys/user.h> ). | |
e63ad01d | 226 | The word is returned as the result of the |
e511ffb6 | 227 | .BR ptrace () |
c13182ef | 228 | call. |
181f997f | 229 | Typically, the offset must be word-aligned, though this might vary by |
8660aec0 MK |
230 | architecture. |
231 | See NOTES. | |
181f997f | 232 | .RI ( data |
051ec121 | 233 | is ignored; but see NOTES.) |
fea681da | 234 | .TP |
8bd58774 | 235 | .BR PTRACE_POKETEXT ", " PTRACE_POKEDATA |
181f997f | 236 | Copy the word |
0daa9e92 | 237 | .I data |
181f997f | 238 | to the address |
0daa9e92 | 239 | .I addr |
4d12a715 | 240 | in the tracee's memory. |
181f997f | 241 | As for |
1ae6b2c7 | 242 | .B PTRACE_PEEKTEXT |
181f997f MK |
243 | and |
244 | .BR PTRACE_PEEKDATA , | |
245 | these two requests are currently equivalent. | |
fea681da | 246 | .TP |
428d3520 | 247 | .B PTRACE_POKEUSER |
254255af MK |
248 | .\" PTRACE_POKEUSR in kernel source, but glibc uses PTRACE_POKEUSER, |
249 | .\" and that is the name that seems common on other systems. | |
181f997f | 250 | Copy the word |
0daa9e92 | 251 | .I data |
fea681da MK |
252 | to offset |
253 | .I addr | |
4d12a715 | 254 | in the tracee's USER area. |
181f997f MK |
255 | As for |
256 | .BR PTRACE_PEEKUSER , | |
257 | the offset must typically be word-aligned. | |
c13182ef | 258 | In order to maintain the integrity of the kernel, |
8bd58774 | 259 | some modifications to the USER area are disallowed. |
181f997f | 260 | .\" FIXME In the preceding sentence, which modifications are disallowed, |
7fac88a9 | 261 | .\" and when they are disallowed, how does user space discover that fact? |
fea681da | 262 | .TP |
8bd58774 | 263 | .BR PTRACE_GETREGS ", " PTRACE_GETFPREGS |
92f9c09b | 264 | Copy the tracee's general-purpose or floating-point registers, |
181f997f MK |
265 | respectively, to the address |
266 | .I data | |
267 | in the tracer. | |
268 | See | |
269 | .I <sys/user.h> | |
270 | for information on the format of this data. | |
271 | .RI ( addr | |
272 | is ignored.) | |
50fe8d53 MK |
273 | Note that SPARC systems have the meaning of |
274 | .I data | |
275 | and | |
276 | .I addr | |
277 | reversed; that is, | |
278 | .I data | |
279 | is ignored and the registers are copied to the address | |
280 | .IR addr . | |
34709982 MK |
281 | .B PTRACE_GETREGS |
282 | and | |
283 | .B PTRACE_GETFPREGS | |
284 | are not present on all architectures. | |
fea681da | 285 | .TP |
ba8f446e DV |
286 | .BR PTRACE_GETREGSET " (since Linux 2.6.34)" |
287 | Read the tracee's registers. | |
288 | .I addr | |
f04ba477 | 289 | specifies, in an architecture-dependent way, the type of registers to be read. |
ba8f446e DV |
290 | .B NT_PRSTATUS |
291 | (with numerical value 1) | |
f04ba477 MK |
292 | usually results in reading of general-purpose registers. |
293 | If the CPU has, for example, | |
ba8f446e DV |
294 | floating-point and/or vector registers, they can be retrieved by setting |
295 | .I addr | |
f04ba477 | 296 | to the corresponding |
ba8f446e DV |
297 | .B NT_foo |
298 | constant. | |
299 | .I data | |
300 | points to a | |
301 | .BR "struct iovec" , | |
f42ce0a5 | 302 | which describes the destination buffer's location and length. |
f04ba477 | 303 | On return, the kernel modifies |
ba8f446e | 304 | .B iov.len |
f04ba477 | 305 | to indicate the actual number of bytes returned. |
ba8f446e | 306 | .TP |
6beb1671 | 307 | .BR PTRACE_SETREGS ", " PTRACE_SETFPREGS |
ba8f446e | 308 | Modify the tracee's general-purpose or floating-point registers, |
181f997f MK |
309 | respectively, from the address |
310 | .I data | |
311 | in the tracer. | |
8bd58774 MK |
312 | As for |
313 | .BR PTRACE_POKEUSER , | |
a42c0c5a | 314 | some general-purpose register modifications may be disallowed. |
bea08fec | 315 | .\" FIXME . In the preceding sentence, which modifications are disallowed, |
7fac88a9 | 316 | .\" and when they are disallowed, how does user space discover that fact? |
181f997f MK |
317 | .RI ( addr |
318 | is ignored.) | |
50fe8d53 MK |
319 | Note that SPARC systems have the meaning of |
320 | .I data | |
321 | and | |
322 | .I addr | |
323 | reversed; that is, | |
324 | .I data | |
325 | is ignored and the registers are copied from the address | |
326 | .IR addr . | |
34709982 MK |
327 | .B PTRACE_SETREGS |
328 | and | |
329 | .B PTRACE_SETFPREGS | |
330 | are not present on all architectures. | |
fea681da | 331 | .TP |
ba8f446e | 332 | .BR PTRACE_SETREGSET " (since Linux 2.6.34)" |
f04ba477 MK |
333 | Modify the tracee's registers. |
334 | The meaning of | |
ba8f446e DV |
335 | .I addr |
336 | and | |
337 | .I data | |
338 | is analogous to | |
339 | .BR PTRACE_GETREGSET . | |
340 | .TP | |
ff01b232 AV |
341 | .BR PTRACE_GETSIGINFO " (since Linux 2.3.99-pre6)" |
342 | Retrieve information about the signal that caused the stop. | |
343 | Copy a | |
344 | .I siginfo_t | |
345 | structure (see | |
346 | .BR sigaction (2)) | |
347 | from the tracee to the address | |
348 | .I data | |
349 | in the tracer. | |
350 | .RI ( addr | |
351 | is ignored.) | |
352 | .TP | |
8bd58774 | 353 | .BR PTRACE_SETSIGINFO " (since Linux 2.3.99-pre6)" |
181f997f MK |
354 | Set signal information: |
355 | copy a | |
356 | .I siginfo_t | |
357 | structure from the address | |
358 | .I data | |
359 | in the tracer to the tracee. | |
360 | This will affect only signals that would normally be delivered to | |
4d12a715 | 361 | the tracee and were caught by the tracer. |
c13182ef | 362 | It may be difficult to tell |
44b35ee0 MK |
363 | these normal signals from synthetic signals generated by |
364 | .BR ptrace () | |
8660aec0 | 365 | itself. |
181f997f MK |
366 | .RI ( addr |
367 | is ignored.) | |
44b35ee0 | 368 | .TP |
7a535f54 AV |
369 | .BR PTRACE_PEEKSIGINFO " (since Linux 3.10)" |
370 | .\" commit 84c751bd4aebbaae995fe32279d3dba48327bad4 | |
371 | Retrieve | |
372 | .I siginfo_t | |
373 | structures without removing signals from a queue. | |
374 | .I addr | |
375 | points to a | |
376 | .I ptrace_peeksiginfo_args | |
83894d15 MK |
377 | structure that specifies the ordinal position from which |
378 | copying of signals should start, | |
379 | and the number of signals to copy. | |
7a535f54 | 380 | .I siginfo_t |
83894d15 MK |
381 | structures are copied into the buffer pointed to by |
382 | .IR data . | |
383 | The return value contains the number of copied signals (zero indicates | |
384 | that there is no signal corresponding to the specified ordinal position). | |
385 | Within the returned | |
7a535f54 | 386 | .I siginfo |
83894d15 MK |
387 | structures, |
388 | the | |
1ae6b2c7 | 389 | .I si_code |
83894d15 MK |
390 | field includes information |
391 | .RB ( __SI_CHLD , | |
392 | .BR __SI_FAULT , | |
8abd92fc | 393 | etc.) that are not otherwise exposed to user space. |
7a535f54 | 394 | .PP |
408731d4 MK |
395 | .in +4n |
396 | .EX | |
7a535f54 | 397 | struct ptrace_peeksiginfo_args { |
83894d15 MK |
398 | u64 off; /* Ordinal position in queue at which |
399 | to start copying signals */ | |
400 | u32 flags; /* PTRACE_PEEKSIGINFO_SHARED or 0 */ | |
401 | s32 nr; /* Number of signals to copy */ | |
7a535f54 | 402 | }; |
b8302363 | 403 | .EE |
a6865065 | 404 | .in |
b8854bae | 405 | .IP |
83894d15 MK |
406 | Currently, there is only one flag, |
407 | .BR PTRACE_PEEKSIGINFO_SHARED , | |
408 | for dumping signals from the process-wide signal queue. | |
409 | If this flag is not set, | |
410 | signals are read from the per-thread queue of the specified thread. | |
7a535f54 | 411 | .in |
7a535f54 | 412 | .TP |
9a36b8fc AV |
413 | .BR PTRACE_GETSIGMASK " (since Linux 3.11)" |
414 | .\" commit 29000caecbe87b6b66f144f72111f0d02fbbf0c1 | |
222475b0 MK |
415 | Place a copy of the mask of blocked signals (see |
416 | .BR sigprocmask (2)) | |
417 | in the buffer pointed to by | |
418 | .IR data , | |
419 | which should be a pointer to a buffer of type | |
420 | .IR sigset_t . | |
9a36b8fc AV |
421 | The |
422 | .I addr | |
222475b0 | 423 | argument contains the size of the buffer pointed to by |
1ae6b2c7 | 424 | .I data |
222475b0 MK |
425 | (i.e., |
426 | .IR sizeof(sigset_t) ). | |
9a36b8fc AV |
427 | .TP |
428 | .BR PTRACE_SETSIGMASK " (since Linux 3.11)" | |
222475b0 MK |
429 | Change the mask of blocked signals (see |
430 | .BR sigprocmask (2)) | |
431 | to the value specified in the buffer pointed to by | |
432 | .IR data , | |
433 | which should be a pointer to a buffer of type | |
434 | .IR sigset_t . | |
9a36b8fc AV |
435 | The |
436 | .I addr | |
222475b0 | 437 | argument contains the size of the buffer pointed to by |
1ae6b2c7 | 438 | .I data |
222475b0 MK |
439 | (i.e., |
440 | .IR sizeof(sigset_t) ). | |
9a36b8fc | 441 | .TP |
8bd58774 | 442 | .BR PTRACE_SETOPTIONS " (since Linux 2.4.6; see BUGS for caveats)" |
181f997f MK |
443 | Set ptrace options from |
444 | .IR data . | |
445 | .RI ( addr | |
446 | is ignored.) | |
1ae6b2c7 | 447 | .I data |
181f997f MK |
448 | is interpreted as a bit mask of options, |
449 | which are specified by the following flags: | |
cc7d99c8 | 450 | .RS |
b89e39ef MK |
451 | .TP |
452 | .BR PTRACE_O_EXITKILL " (since Linux 3.8)" | |
453 | .\" commit 992fb6e170639b0849bace8e49bf31bd37c4123 | |
14d6e62f | 454 | Send a |
b89e39ef | 455 | .B SIGKILL |
14d6e62f | 456 | signal to the tracee if the tracer exits. |
9f1b9726 | 457 | This option is useful for ptrace jailers that |
c2b54496 | 458 | want to ensure that tracees can never escape the tracer's control. |
44b35ee0 | 459 | .TP |
8bd58774 | 460 | .BR PTRACE_O_TRACECLONE " (since Linux 2.5.46)" |
4d12a715 | 461 | Stop the tracee at the next |
0bfa087b | 462 | .BR clone (2) |
181f997f MK |
463 | and automatically start tracing the newly cloned process, |
464 | which will start with a | |
29f9b8fb DV |
465 | .BR SIGSTOP , |
466 | or | |
467 | .B PTRACE_EVENT_STOP | |
468 | if | |
469 | .B PTRACE_SEIZE | |
470 | was used. | |
8898a252 MK |
471 | A |
472 | .BR waitpid (2) | |
dc85ba7c | 473 | by the tracer will return a |
8898a252 | 474 | .I status |
dc85ba7c | 475 | value such that |
efeece04 | 476 | .IP |
dc85ba7c MK |
477 | .nf |
478 | status>>8 == (SIGTRAP | (PTRACE_EVENT_CLONE<<8)) | |
479 | .fi | |
efeece04 | 480 | .IP |
181f997f | 481 | The PID of the new process can be retrieved with |
8bd58774 | 482 | .BR PTRACE_GETEVENTMSG . |
181f997f | 483 | .IP |
44b35ee0 | 484 | This option may not catch |
0bfa087b | 485 | .BR clone (2) |
c13182ef | 486 | calls in all cases. |
4d12a715 | 487 | If the tracee calls |
0bfa087b | 488 | .BR clone (2) |
8bd58774 | 489 | with the |
0daa9e92 | 490 | .B CLONE_VFORK |
8bd58774 MK |
491 | flag, |
492 | .B PTRACE_EVENT_VFORK | |
493 | will be delivered instead | |
494 | if | |
495 | .B PTRACE_O_TRACEVFORK | |
4d12a715 | 496 | is set; otherwise if the tracee calls |
0bfa087b | 497 | .BR clone (2) |
8bd58774 MK |
498 | with the exit signal set to |
499 | .BR SIGCHLD , | |
500 | .B PTRACE_EVENT_FORK | |
181f997f | 501 | will be delivered if |
8bd58774 MK |
502 | .B PTRACE_O_TRACEFORK |
503 | is set. | |
44b35ee0 | 504 | .TP |
8bd58774 | 505 | .BR PTRACE_O_TRACEEXEC " (since Linux 2.5.46)" |
4d12a715 | 506 | Stop the tracee at the next |
181f997f | 507 | .BR execve (2). |
8898a252 MK |
508 | A |
509 | .BR waitpid (2) | |
dc85ba7c | 510 | by the tracer will return a |
8898a252 | 511 | .I status |
dc85ba7c | 512 | value such that |
efeece04 | 513 | .IP |
dc85ba7c MK |
514 | .nf |
515 | status>>8 == (SIGTRAP | (PTRACE_EVENT_EXEC<<8)) | |
516 | .fi | |
efeece04 | 517 | .IP |
8f318249 MK |
518 | If the execing thread is not a thread group leader, |
519 | the thread ID is reset to thread group leader's ID before this stop. | |
b16d33ef DV |
520 | Since Linux 3.0, the former thread ID can be retrieved with |
521 | .BR PTRACE_GETEVENTMSG . | |
44b35ee0 | 522 | .TP |
8bd58774 | 523 | .BR PTRACE_O_TRACEEXIT " (since Linux 2.5.60)" |
181f997f | 524 | Stop the tracee at exit. |
8898a252 MK |
525 | A |
526 | .BR waitpid (2) | |
dc85ba7c | 527 | by the tracer will return a |
8898a252 | 528 | .I status |
dc85ba7c | 529 | value such that |
efeece04 | 530 | .IP |
dc85ba7c MK |
531 | .nf |
532 | status>>8 == (SIGTRAP | (PTRACE_EVENT_EXIT<<8)) | |
533 | .fi | |
efeece04 | 534 | .IP |
4d12a715 | 535 | The tracee's exit status can be retrieved with |
8bd58774 | 536 | .BR PTRACE_GETEVENTMSG . |
181f997f MK |
537 | .IP |
538 | The tracee is stopped early during process exit, | |
539 | when registers are still available, | |
540 | allowing the tracer to see where the exit occurred, | |
c13182ef | 541 | whereas the normal exit notification is done after the process |
e63ad01d | 542 | is finished exiting. |
181f997f MK |
543 | Even though context is available, |
544 | the tracer cannot prevent the exit from happening at this point. | |
cc7d99c8 MK |
545 | .TP |
546 | .BR PTRACE_O_TRACEFORK " (since Linux 2.5.46)" | |
547 | Stop the tracee at the next | |
548 | .BR fork (2) | |
549 | and automatically start tracing the newly forked process, | |
550 | which will start with a | |
29f9b8fb DV |
551 | .BR SIGSTOP , |
552 | or | |
553 | .B PTRACE_EVENT_STOP | |
554 | if | |
555 | .B PTRACE_SEIZE | |
556 | was used. | |
cc7d99c8 MK |
557 | A |
558 | .BR waitpid (2) | |
559 | by the tracer will return a | |
560 | .I status | |
561 | value such that | |
efeece04 | 562 | .IP |
cc7d99c8 MK |
563 | .nf |
564 | status>>8 == (SIGTRAP | (PTRACE_EVENT_FORK<<8)) | |
565 | .fi | |
efeece04 | 566 | .IP |
cc7d99c8 MK |
567 | The PID of the new process can be retrieved with |
568 | .BR PTRACE_GETEVENTMSG . | |
cc7d99c8 MK |
569 | .TP |
570 | .BR PTRACE_O_TRACESYSGOOD " (since Linux 2.4.6)" | |
571 | When delivering system call traps, set bit 7 in the signal number | |
572 | (i.e., deliver | |
573 | .IR "SIGTRAP|0x80" ). | |
574 | This makes it easy for the tracer to distinguish | |
575 | normal traps from those caused by a system call. | |
cc7d99c8 MK |
576 | .TP |
577 | .BR PTRACE_O_TRACEVFORK " (since Linux 2.5.46)" | |
578 | Stop the tracee at the next | |
579 | .BR vfork (2) | |
580 | and automatically start tracing the newly vforked process, | |
581 | which will start with a | |
29f9b8fb DV |
582 | .BR SIGSTOP , |
583 | or | |
584 | .B PTRACE_EVENT_STOP | |
585 | if | |
586 | .B PTRACE_SEIZE | |
587 | was used. | |
cc7d99c8 MK |
588 | A |
589 | .BR waitpid (2) | |
590 | by the tracer will return a | |
591 | .I status | |
592 | value such that | |
efeece04 | 593 | .IP |
cc7d99c8 MK |
594 | .nf |
595 | status>>8 == (SIGTRAP | (PTRACE_EVENT_VFORK<<8)) | |
596 | .fi | |
efeece04 | 597 | .IP |
cc7d99c8 MK |
598 | The PID of the new process can be retrieved with |
599 | .BR PTRACE_GETEVENTMSG . | |
600 | .TP | |
601 | .BR PTRACE_O_TRACEVFORKDONE " (since Linux 2.5.60)" | |
602 | Stop the tracee at the completion of the next | |
603 | .BR vfork (2). | |
604 | A | |
605 | .BR waitpid (2) | |
606 | by the tracer will return a | |
607 | .I status | |
608 | value such that | |
efeece04 | 609 | .IP |
cc7d99c8 MK |
610 | .nf |
611 | status>>8 == (SIGTRAP | (PTRACE_EVENT_VFORK_DONE<<8)) | |
612 | .fi | |
efeece04 | 613 | .IP |
cc7d99c8 MK |
614 | The PID of the new process can (since Linux 2.6.18) be retrieved with |
615 | .BR PTRACE_GETEVENTMSG . | |
3b4a59c4 KC |
616 | .TP |
617 | .BR PTRACE_O_TRACESECCOMP " (since Linux 3.5)" | |
618 | Stop the tracee when a | |
619 | .BR seccomp (2) | |
1ae6b2c7 | 620 | .B SECCOMP_RET_TRACE |
81c5080b MK |
621 | rule is triggered. |
622 | A | |
3b4a59c4 KC |
623 | .BR waitpid (2) |
624 | by the tracer will return a | |
625 | .I status | |
626 | value such that | |
efeece04 | 627 | .IP |
3b4a59c4 KC |
628 | .nf |
629 | status>>8 == (SIGTRAP | (PTRACE_EVENT_SECCOMP<<8)) | |
630 | .fi | |
efeece04 | 631 | .IP |
3b4a59c4 | 632 | While this triggers a |
1ae6b2c7 | 633 | .B PTRACE_EVENT |
ff20e9ca MK |
634 | stop, it is similar to a syscall-enter-stop. |
635 | For details, see the note on | |
636 | .B PTRACE_EVENT_SECCOMP | |
637 | below. | |
81c5080b | 638 | The seccomp event message data (from the |
1ae6b2c7 | 639 | .B SECCOMP_RET_DATA |
81c5080b | 640 | portion of the seccomp filter rule) can be retrieved with |
3b4a59c4 | 641 | .BR PTRACE_GETEVENTMSG . |
e3cfeba2 | 642 | .TP |
b4b436ad MK |
643 | .BR PTRACE_O_SUSPEND_SECCOMP " (since Linux 4.3)" |
644 | .\" commit 13c4a90119d28cfcb6b5bdd820c233b86c2b0237 | |
645 | Suspend the tracee's seccomp protections. | |
646 | This applies regardless of mode, and | |
647 | can be used when the tracee has not yet installed seccomp filters. | |
648 | That is, a valid use case is to suspend a tracee's seccomp protections | |
649 | before they are installed by the tracee, | |
650 | let the tracee install the filters, | |
651 | and then clear this flag when the filters should be resumed. | |
652 | Setting this option requires that the tracer have the | |
1ae6b2c7 | 653 | .B CAP_SYS_ADMIN |
b4b436ad | 654 | capability, |
e3cfeba2 | 655 | not have any seccomp protections installed, and not have |
1ae6b2c7 | 656 | .B PTRACE_O_SUSPEND_SECCOMP |
e3cfeba2 | 657 | set on itself. |
44b35ee0 MK |
658 | .RE |
659 | .TP | |
8bd58774 | 660 | .BR PTRACE_GETEVENTMSG " (since Linux 2.5.46)" |
c13182ef MK |
661 | Retrieve a message (as an |
662 | .IR "unsigned long" ) | |
44b35ee0 | 663 | about the ptrace event |
181f997f MK |
664 | that just happened, placing it at the address |
665 | .I data | |
666 | in the tracer. | |
8bd58774 | 667 | For |
181f997f | 668 | .BR PTRACE_EVENT_EXIT , |
4d12a715 | 669 | this is the tracee's exit status. |
8bd58774 MK |
670 | For |
671 | .BR PTRACE_EVENT_FORK , | |
181f997f MK |
672 | .BR PTRACE_EVENT_VFORK , |
673 | .BR PTRACE_EVENT_VFORK_DONE , | |
8bd58774 | 674 | and |
181f997f MK |
675 | .BR PTRACE_EVENT_CLONE , |
676 | this is the PID of the new process. | |
3b4a59c4 KC |
677 | For |
678 | .BR PTRACE_EVENT_SECCOMP , | |
679 | this is the | |
680 | .BR seccomp (2) | |
681 | filter's | |
1ae6b2c7 | 682 | .B SECCOMP_RET_DATA |
3b4a59c4 | 683 | associated with the triggered rule. |
36f5dd10 | 684 | .RI ( addr |
181f997f | 685 | is ignored.) |
44b35ee0 | 686 | .TP |
8bd58774 | 687 | .B PTRACE_CONT |
181f997f MK |
688 | Restart the stopped tracee process. |
689 | If | |
690 | .I data | |
691 | is nonzero, | |
692 | it is interpreted as the number of a signal to be delivered to the tracee; | |
c13182ef | 693 | otherwise, no signal is delivered. |
4d12a715 DV |
694 | Thus, for example, the tracer can control |
695 | whether a signal sent to the tracee is delivered or not. | |
181f997f MK |
696 | .RI ( addr |
697 | is ignored.) | |
fea681da | 698 | .TP |
8bd58774 | 699 | .BR PTRACE_SYSCALL ", " PTRACE_SINGLESTEP |
181f997f | 700 | Restart the stopped tracee as for |
8bd58774 | 701 | .BR PTRACE_CONT , |
181f997f MK |
702 | but arrange for the tracee to be stopped at |
703 | the next entry to or exit from a system call, | |
c13182ef | 704 | or after execution of a single instruction, respectively. |
4d12a715 DV |
705 | (The tracee will also, as usual, be stopped upon receipt of a signal.) |
706 | From the tracer's perspective, the tracee will appear to have been | |
8bd58774 MK |
707 | stopped by receipt of a |
708 | .BR SIGTRAP . | |
709 | So, for | |
710 | .BR PTRACE_SYSCALL , | |
711 | for example, the idea is to inspect | |
c13182ef | 712 | the arguments to the system call at the first stop, |
8bd58774 MK |
713 | then do another |
714 | .B PTRACE_SYSCALL | |
181f997f | 715 | and inspect the return value of the system call at the second stop. |
94cffcd7 MK |
716 | The |
717 | .I data | |
718 | argument is treated as for | |
719 | .BR PTRACE_CONT . | |
a5c725cf | 720 | .RI ( addr |
181f997f | 721 | is ignored.) |
fea681da | 722 | .TP |
c2254484 JS |
723 | .BR PTRACE_SET_SYSCALL " (since Linux 2.6.16)" |
724 | .\" commit 3f471126ee53feb5e9b210ea2f525ed3bb9b7a7f | |
cbda5fc9 MK |
725 | When in syscall-enter-stop, |
726 | change the number of the system call that is about to | |
c2254484 JS |
727 | be executed to the number specified in the |
728 | .I data | |
cbda5fc9 MK |
729 | argument. |
730 | The | |
c2254484 | 731 | .I addr |
cbda5fc9 MK |
732 | argument is ignored. |
733 | This request is currently | |
c2254484 JS |
734 | .\" As of 4.19-rc2 |
735 | supported only on arm (and arm64, though only for backwards compatibility), | |
736 | .\" commit 27aa55c5e5123fa8b8ad0156559d34d7edff58ca | |
737 | but most other architectures have other means of accomplishing this | |
738 | (usually by changing the register that the userland code passed the | |
cbda5fc9 | 739 | system call number in). |
c2254484 | 740 | .\" see change_syscall in tools/testing/selftests/seccomp/seccomp_bpf.c |
731192be | 741 | .\" and also strace's linux/*/set_scno.c files. |
c2254484 | 742 | .TP |
6beb1671 | 743 | .BR PTRACE_SYSEMU ", " PTRACE_SYSEMU_SINGLESTEP " (since Linux 2.6.14)" |
8bd58774 MK |
744 | For |
745 | .BR PTRACE_SYSEMU , | |
181f997f | 746 | continue and stop on entry to the next system call, |
ff20e9ca MK |
747 | which will not be executed. |
748 | See the documentation on syscall-stops below. | |
8bd58774 MK |
749 | For |
750 | .BR PTRACE_SYSEMU_SINGLESTEP , | |
181f997f | 751 | do the same but also singlestep if not a system call. |
c13182ef | 752 | This call is used by programs like |
4d12a715 | 753 | User Mode Linux that want to emulate all the tracee's system calls. |
94cffcd7 MK |
754 | The |
755 | .I data | |
756 | argument is treated as for | |
757 | .BR PTRACE_CONT . | |
34709982 MK |
758 | The |
759 | .I addr | |
760 | argument is ignored. | |
761 | These requests are currently | |
762 | .\" As at 3.7 | |
d2ea1bd4 | 763 | supported only on x86. |
44b35ee0 | 764 | .TP |
ba8f446e DV |
765 | .BR PTRACE_LISTEN " (since Linux 3.4)" |
766 | Restart the stopped tracee, but prevent it from executing. | |
767 | The resulting state of the tracee is similar to a process which | |
f04ba477 MK |
768 | has been stopped by a |
769 | .B SIGSTOP | |
770 | (or other stopping signal). | |
ba8f446e DV |
771 | See the "group-stop" subsection for additional information. |
772 | .B PTRACE_LISTEN | |
33a0ccb2 | 773 | works only on tracees attached by |
ba8f446e DV |
774 | .BR PTRACE_SEIZE . |
775 | .TP | |
8bd58774 | 776 | .B PTRACE_KILL |
181f997f | 777 | Send the tracee a |
8bd58774 MK |
778 | .B SIGKILL |
779 | to terminate it. | |
181f997f MK |
780 | .RI ( addr |
781 | and | |
782 | .I data | |
783 | are ignored.) | |
784 | .IP | |
785 | .I This operation is deprecated; do not use it! | |
786 | Instead, send a | |
1ae6b2c7 | 787 | .B SIGKILL |
181f997f MK |
788 | directly using |
789 | .BR kill (2) | |
790 | or | |
791 | .BR tgkill (2). | |
792 | The problem with | |
793 | .B PTRACE_KILL | |
794 | is that it requires the tracee to be in signal-delivery-stop, | |
795 | otherwise it may not work | |
796 | (i.e., may complete successfully but won't kill the tracee). | |
797 | By contrast, sending a | |
798 | .B SIGKILL | |
799 | directly has no such limitation. | |
8898a252 MK |
800 | .\" [Note from Denys Vlasenko: |
801 | .\" deprecation suggested by Oleg Nesterov. He prefers to deprecate it | |
802 | .\" instead of describing (and needing to support) PTRACE_KILL's quirks.] | |
fea681da | 803 | .TP |
ba8f446e | 804 | .BR PTRACE_INTERRUPT " (since Linux 3.4)" |
f04ba477 | 805 | Stop a tracee. |
8da59274 DV |
806 | If the tracee is running or sleeping in kernel space and |
807 | .B PTRACE_SYSCALL | |
808 | is in effect, | |
809 | the system call is interrupted and syscall-exit-stop is reported. | |
810 | (The interrupted system call is restarted when the tracee is restarted.) | |
811 | If the tracee was already stopped by a signal and | |
812 | .B PTRACE_LISTEN | |
813 | was sent to it, | |
814 | the tracee stops with | |
815 | .B PTRACE_EVENT_STOP | |
ad84c543 | 816 | and |
8da59274 | 817 | .I WSTOPSIG(status) |
ad84c543 | 818 | returns the stop signal. |
8da59274 DV |
819 | If any other ptrace-stop is generated at the same time (for example, |
820 | if a signal is sent to the tracee), this ptrace-stop happens. | |
a9deb5e0 MF |
821 | If none of the above applies (for example, if the tracee is running in user |
822 | space), it stops with | |
8da59274 DV |
823 | .B PTRACE_EVENT_STOP |
824 | with | |
825 | .I WSTOPSIG(status) | |
826 | == | |
827 | .BR SIGTRAP . | |
ba8f446e DV |
828 | .B PTRACE_INTERRUPT |
829 | only works on tracees attached by | |
830 | .BR PTRACE_SEIZE . | |
831 | .TP | |
8bd58774 | 832 | .B PTRACE_ATTACH |
181f997f | 833 | Attach to the process specified in |
fea681da | 834 | .IR pid , |
4d12a715 | 835 | making it a tracee of the calling process. |
8898a252 MK |
836 | .\" No longer true (removed by Denys Vlasenko, 2011, who remarks: |
837 | .\" "I think it isn't true in non-ancient 2.4 and in 2.6/3.x. | |
838 | .\" Basically, it's not true for any Linux in practical use. | |
4d12a715 DV |
839 | .\" ; the behavior of the tracee is as if it had done a |
840 | .\" .BR PTRACE_TRACEME . | |
841 | .\" The calling process actually becomes the parent of the tracee | |
842 | .\" process for most purposes (e.g., it will receive | |
843 | .\" notification of tracee events and appears in | |
844 | .\" .BR ps (1) | |
845 | .\" output as the tracee's parent), but a | |
846 | .\" .BR getppid (2) | |
847 | .\" by the tracee will still return the PID of the original parent. | |
848 | The tracee is sent a | |
8bd58774 MK |
849 | .BR SIGSTOP , |
850 | but will not necessarily have stopped | |
e63ad01d | 851 | by the completion of this call; use |
181f997f | 852 | .BR waitpid (2) |
8b20acd1 | 853 | to wait for the tracee to stop. |
181f997f MK |
854 | See the "Attaching and detaching" subsection for additional information. |
855 | .RI ( addr | |
856 | and | |
857 | .I data | |
858 | are ignored.) | |
efeece04 | 859 | .IP |
d4c976d8 | 860 | Permission to perform a |
1ae6b2c7 | 861 | .B PTRACE_ATTACH |
d4c976d8 MK |
862 | is governed by a ptrace access mode |
863 | .B PTRACE_MODE_ATTACH_REALCREDS | |
864 | check; see below. | |
fea681da | 865 | .TP |
ba8f446e | 866 | .BR PTRACE_SEIZE " (since Linux 3.4)" |
fec74bb1 MK |
867 | .\" |
868 | .\" Noted by Dmitry Levin: | |
869 | .\" | |
870 | .\" PTRACE_SEIZE was introduced by commit v3.1-rc1~308^2~28, but | |
871 | .\" it had to be used along with a temporary flag PTRACE_SEIZE_DEVEL, | |
872 | .\" which was removed later by commit v3.4-rc1~109^2~20. | |
873 | .\" | |
874 | .\" That is, [before] v3.4 we had a test mode of PTRACE_SEIZE API, | |
875 | .\" which was not compatible with the current PTRACE_SEIZE API introduced | |
876 | .\" in Linux 3.4. | |
877 | .\" | |
ba8f446e DV |
878 | Attach to the process specified in |
879 | .IR pid , | |
880 | making it a tracee of the calling process. | |
881 | Unlike | |
882 | .BR PTRACE_ATTACH , | |
883 | .B PTRACE_SEIZE | |
f04ba477 | 884 | does not stop the process. |
28e2ca57 DV |
885 | Group-stops are reported as |
886 | .B PTRACE_EVENT_STOP | |
53cdec41 | 887 | and |
28e2ca57 | 888 | .I WSTOPSIG(status) |
53cdec41 | 889 | returns the stop signal. |
28e2ca57 DV |
890 | Automatically attached children stop with |
891 | .B PTRACE_EVENT_STOP | |
53cdec41 | 892 | and |
28e2ca57 | 893 | .I WSTOPSIG(status) |
53cdec41 | 894 | returns |
28e2ca57 DV |
895 | .B SIGTRAP |
896 | instead of having | |
897 | .B SIGSTOP | |
898 | signal delivered to them. | |
cc3407d1 | 899 | .BR execve (2) |
28e2ca57 | 900 | does not deliver an extra |
53cdec41 | 901 | .BR SIGTRAP . |
f04ba477 | 902 | Only a |
ba8f446e DV |
903 | .BR PTRACE_SEIZE d |
904 | process can accept | |
905 | .B PTRACE_INTERRUPT | |
906 | and | |
907 | .B PTRACE_LISTEN | |
908 | commands. | |
28e2ca57 DV |
909 | The "seized" behavior just described is inherited by |
910 | children that are automatically attached using | |
911 | .BR PTRACE_O_TRACEFORK , | |
912 | .BR PTRACE_O_TRACEVFORK , | |
913 | and | |
914 | .BR PTRACE_O_TRACECLONE . | |
ba8f446e DV |
915 | .I addr |
916 | must be zero. | |
917 | .I data | |
918 | contains a bit mask of ptrace options to activate immediately. | |
efeece04 | 919 | .IP |
c33e8aff | 920 | Permission to perform a |
1ae6b2c7 | 921 | .B PTRACE_SEIZE |
c33e8aff MK |
922 | is governed by a ptrace access mode |
923 | .B PTRACE_MODE_ATTACH_REALCREDS | |
924 | check; see below. | |
baf11d5c MK |
925 | .\" |
926 | .TP | |
927 | .BR PTRACE_SECCOMP_GET_FILTER " (since Linux 4.4)" | |
928 | .\" commit f8e529ed941ba2bbcbf310b575d968159ce7e895 | |
929 | This operation allows the tracer to dump the tracee's | |
930 | classic BPF filters. | |
efeece04 | 931 | .IP |
baf11d5c MK |
932 | .I addr |
933 | is an integer specifying the index of the filter to be dumped. | |
934 | The most recently installed filter has the index 0. | |
935 | If | |
936 | .I addr | |
937 | is greater than the number of installed filters, | |
938 | the operation fails with the error | |
939 | .BR ENOENT . | |
efeece04 | 940 | .IP |
baf11d5c MK |
941 | .I data |
942 | is either a pointer to a | |
1ae6b2c7 | 943 | .I struct sock_filter |
baf11d5c MK |
944 | array that is large enough to store the BPF program, |
945 | or NULL if the program is not to be stored. | |
efeece04 | 946 | .IP |
baf11d5c MK |
947 | Upon success, |
948 | the return value is the number of instructions in the BPF program. | |
949 | If | |
950 | .I data | |
951 | was NULL, then this return value can be used to correctly size the | |
1ae6b2c7 | 952 | .I struct sock_filter |
baf11d5c | 953 | array passed in a subsequent call. |
efeece04 | 954 | .IP |
baf11d5c | 955 | This operation fails with the error |
7b10f505 | 956 | .B EACCES |
baf11d5c MK |
957 | if the caller does not have the |
958 | .B CAP_SYS_ADMIN | |
959 | capability or if the caller is in strict or filter seccomp mode. | |
960 | If the filter referred to by | |
961 | .I addr | |
962 | is not a classic BPF filter, the operation fails with the error | |
963 | .BR EMEDIUMTYPE . | |
efeece04 | 964 | .IP |
baf11d5c MK |
965 | This operation is available if the kernel was configured with both the |
966 | .B CONFIG_SECCOMP_FILTER | |
967 | and the | |
968 | .B CONFIG_CHECKPOINT_RESTORE | |
969 | options. | |
ba8f446e | 970 | .TP |
8bd58774 | 971 | .B PTRACE_DETACH |
181f997f | 972 | Restart the stopped tracee as for |
8bd58774 | 973 | .BR PTRACE_CONT , |
181f997f MK |
974 | but first detach from it. |
975 | Under Linux, a tracee can be detached in this way regardless | |
976 | of which method was used to initiate tracing. | |
977 | .RI ( addr | |
978 | is ignored.) | |
baf11d5c | 979 | .\" |
bc8bfd8a MK |
980 | .TP |
981 | .BR PTRACE_GET_THREAD_AREA " (since Linux 2.6.0)" | |
982 | This operation performs a similar task to | |
983 | .BR get_thread_area (2). | |
984 | It reads the TLS entry in the GDT whose index is given in | |
985 | .IR addr , | |
986 | placing a copy of the entry into the | |
1ae6b2c7 | 987 | .I struct user_desc |
bc8bfd8a MK |
988 | pointed to by |
989 | .IR data . | |
990 | (By contrast with | |
991 | .BR get_thread_area (2), | |
992 | the | |
993 | .I entry_number | |
994 | of the | |
1ae6b2c7 | 995 | .I struct user_desc |
bc8bfd8a MK |
996 | is ignored.) |
997 | .TP | |
998 | .BR PTRACE_SET_THREAD_AREA " (since Linux 2.6.0)" | |
999 | This operation performs a similar task to | |
1000 | .BR set_thread_area (2). | |
1001 | It sets the TLS entry in the GDT whose index is given in | |
1002 | .IR addr , | |
1003 | assigning it the data supplied in the | |
1ae6b2c7 | 1004 | .I struct user_desc |
bc8bfd8a MK |
1005 | pointed to by |
1006 | .IR data . | |
1007 | (By contrast with | |
1008 | .BR set_thread_area (2), | |
1009 | the | |
1010 | .I entry_number | |
1011 | of the | |
1ae6b2c7 | 1012 | .I struct user_desc |
bc8bfd8a MK |
1013 | is ignored; in other words, |
1014 | this ptrace operation can't be used to allocate a free TLS entry.) | |
fc91449c DL |
1015 | .TP |
1016 | .BR PTRACE_GET_SYSCALL_INFO " (since Linux 5.3)" | |
1017 | .\" commit 201766a20e30f982ccfe36bebfad9602c3ff574a | |
c3543fab MK |
1018 | Retrieve information about the system call that caused the stop. |
1019 | The information is placed into the buffer pointed by the | |
fc91449c DL |
1020 | .I data |
1021 | argument, which should be a pointer to a buffer of type | |
1022 | .IR "struct ptrace_syscall_info" . | |
1023 | The | |
1024 | .I addr | |
1025 | argument contains the size of the buffer pointed to | |
c3543fab | 1026 | by the |
fc91449c DL |
1027 | .I data |
1028 | argument (i.e., | |
1029 | .IR "sizeof(struct ptrace_syscall_info)" ). | |
1030 | The return value contains the number of bytes available | |
1031 | to be written by the kernel. | |
c3543fab MK |
1032 | If the size of the data to be written by the kernel exceeds the size |
1033 | specified by the | |
fc91449c | 1034 | .I addr |
c3543fab | 1035 | argument, the output data is truncated. |
a60e8f1b DL |
1036 | .IP |
1037 | The | |
1038 | .I ptrace_syscall_info | |
1039 | structure contains the following fields: | |
1040 | .IP | |
9f5f1b5b | 1041 | .in +4n |
a60e8f1b | 1042 | .EX |
d089fdec | 1043 | struct ptrace_syscall_info { |
9f5f1b5b MK |
1044 | __u8 op; /* Type of system call stop */ |
1045 | __u32 arch; /* AUDIT_ARCH_* value; see seccomp(2) */ | |
f04534d2 | 1046 | __u64 instruction_pointer; /* CPU instruction pointer */ |
9f5f1b5b | 1047 | __u64 stack_pointer; /* CPU stack pointer */ |
a60e8f1b | 1048 | union { |
9f5f1b5b MK |
1049 | struct { /* op == PTRACE_SYSCALL_INFO_ENTRY */ |
1050 | __u64 nr; /* System call number */ | |
1051 | __u64 args[6]; /* System call arguments */ | |
f04534d2 | 1052 | } entry; |
9f5f1b5b MK |
1053 | struct { /* op == PTRACE_SYSCALL_INFO_EXIT */ |
1054 | __s64 rval; /* System call return value */ | |
1055 | __u8 is_error; /* System call error flag; | |
1056 | Boolean: does rval contain | |
1057 | an error value (\-ERRCODE) or | |
1058 | a nonerror return value? */ | |
f04534d2 | 1059 | } exit; |
9f5f1b5b MK |
1060 | struct { /* op == PTRACE_SYSCALL_INFO_SECCOMP */ |
1061 | __u64 nr; /* System call number */ | |
1062 | __u64 args[6]; /* System call arguments */ | |
1063 | __u32 ret_data; /* SECCOMP_RET_DATA portion | |
1064 | of SECCOMP_RET_TRACE | |
1065 | return value */ | |
f04534d2 | 1066 | } seccomp; |
a60e8f1b DL |
1067 | }; |
1068 | }; | |
1069 | .EE | |
1070 | .in | |
1071 | .IP | |
1c0955b1 | 1072 | The |
a60e8f1b DL |
1073 | .IR op , |
1074 | .IR arch , | |
1075 | .IR instruction_pointer , | |
1076 | and | |
1077 | .I stack_pointer | |
1078 | fields are defined for all kinds of ptrace system call stops. | |
1c0955b1 | 1079 | The rest of the structure is a union; one should read only those fields |
a60e8f1b | 1080 | that are meaningful for the kind of system call stop specified by the |
1ae6b2c7 | 1081 | .I op |
a60e8f1b | 1082 | field. |
f04534d2 MK |
1083 | .IP |
1084 | The | |
1085 | .I op | |
1086 | field has one of the following values (defined in | |
1ae6b2c7 | 1087 | .IR <linux/ptrace.h> ) |
f04534d2 MK |
1088 | indicating what type of stop occurred and |
1089 | which part of the union is filled: | |
1090 | .RS | |
1091 | .TP | |
1ae6b2c7 | 1092 | .B PTRACE_SYSCALL_INFO_ENTRY |
f04534d2 MK |
1093 | The |
1094 | .I entry | |
1095 | component of the union contains information relating to a | |
1096 | system call entry stop. | |
1097 | .TP | |
1ae6b2c7 | 1098 | .B PTRACE_SYSCALL_INFO_EXIT |
f04534d2 MK |
1099 | The |
1100 | .I exit | |
1101 | component of the union contains information relating to a | |
1102 | system call exit stop. | |
1103 | .TP | |
1ae6b2c7 | 1104 | .B PTRACE_SYSCALL_INFO_SECCOMP |
f04534d2 | 1105 | The |
302c512c | 1106 | .I seccomp |
f04534d2 MK |
1107 | component of the union contains information relating to a |
1108 | .B PTRACE_EVENT_SECCOMP | |
1109 | stop. | |
1110 | .TP | |
1ae6b2c7 | 1111 | .B PTRACE_SYSCALL_INFO_NONE |
f04534d2 MK |
1112 | No component of the union contains relevant information. |
1113 | .RE | |
bc8bfd8a | 1114 | .\" |
4d12a715 | 1115 | .SS Death under ptrace |
181f997f MK |
1116 | When a (possibly multithreaded) process receives a killing signal |
1117 | (one whose disposition is set to | |
1118 | .B SIG_DFL | |
1119 | and whose default action is to kill the process), | |
8b20acd1 MK |
1120 | all threads exit. |
1121 | Tracees report their death to their tracer(s). | |
181f997f MK |
1122 | Notification of this event is delivered via |
1123 | .BR waitpid (2). | |
dd3568a1 | 1124 | .PP |
181f997f MK |
1125 | Note that the killing signal will first cause signal-delivery-stop |
1126 | (on one tracee only), | |
1127 | and only after it is injected by the tracer | |
1128 | (or after it was dispatched to a thread which isn't traced), | |
1129 | will death from the signal happen on | |
1130 | .I all | |
1131 | tracees within a multithreaded process. | |
1132 | (The term "signal-delivery-stop" is explained below.) | |
dd3568a1 | 1133 | .PP |
181f997f | 1134 | .B SIGKILL |
ca302d0e DV |
1135 | does not generate signal-delivery-stop and |
1136 | therefore the tracer can't suppress it. | |
181f997f MK |
1137 | .B SIGKILL |
1138 | kills even within system calls | |
1139 | (syscall-exit-stop is not generated prior to death by | |
1140 | .BR SIGKILL ). | |
1141 | The net effect is that | |
1142 | .B SIGKILL | |
1143 | always kills the process (all its threads), | |
1144 | even if some threads of the process are ptraced. | |
dd3568a1 | 1145 | .PP |
181f997f MK |
1146 | When the tracee calls |
1147 | .BR _exit (2), | |
1148 | it reports its death to its tracer. | |
4d12a715 | 1149 | Other threads are not affected. |
dd3568a1 | 1150 | .PP |
181f997f MK |
1151 | When any thread executes |
1152 | .BR exit_group (2), | |
1153 | every tracee in its thread group reports its death to its tracer. | |
dd3568a1 | 1154 | .PP |
181f997f MK |
1155 | If the |
1156 | .B PTRACE_O_TRACEEXIT | |
1157 | option is on, | |
1158 | .B PTRACE_EVENT_EXIT | |
1159 | will happen before actual death. | |
1160 | This applies to exits via | |
1161 | .BR exit (2), | |
1162 | .BR exit_group (2), | |
1163 | and signal deaths (except | |
55bd9495 MK |
1164 | .BR SIGKILL , |
1165 | depending on the kernel version; see BUGS below), | |
181f997f MK |
1166 | and when threads are torn down on |
1167 | .BR execve (2) | |
1168 | in a multithreaded process. | |
dd3568a1 | 1169 | .PP |
181f997f MK |
1170 | The tracer cannot assume that the ptrace-stopped tracee exists. |
1171 | There are many scenarios when the tracee may die while stopped (such as | |
1172 | .BR SIGKILL ). | |
d6e37473 | 1173 | Therefore, the tracer must be prepared to handle an |
181f997f MK |
1174 | .B ESRCH |
1175 | error on any ptrace operation. | |
1176 | Unfortunately, the same error is returned if the tracee | |
1177 | exists but is not ptrace-stopped | |
1178 | (for commands which require a stopped tracee), | |
1179 | or if it is not traced by the process which issued the ptrace call. | |
1180 | The tracer needs to keep track of the stopped/running state of the tracee, | |
1181 | and interpret | |
1182 | .B ESRCH | |
1183 | as "tracee died unexpectedly" only if it knows that the tracee has | |
1184 | been observed to enter ptrace-stop. | |
1185 | Note that there is no guarantee that | |
1186 | .I waitpid(WNOHANG) | |
1187 | will reliably report the tracee's death status if a | |
1188 | ptrace operation returned | |
1189 | .BR ESRCH . | |
1190 | .I waitpid(WNOHANG) | |
1191 | may return 0 instead. | |
1192 | In other words, the tracee may be "not yet fully dead", | |
1193 | but already refusing ptrace requests. | |
dd3568a1 | 1194 | .PP |
181f997f MK |
1195 | The tracer can't assume that the tracee |
1196 | .I always | |
1197 | ends its life by reporting | |
1198 | .I WIFEXITED(status) | |
1199 | or | |
8898a252 MK |
1200 | .IR WIFSIGNALED(status) ; |
1201 | there are cases where this does not occur. | |
1202 | For example, if a thread other than thread group leader does an | |
1203 | .BR execve (2), | |
1204 | it disappears; | |
1205 | its PID will never be seen again, | |
1206 | and any subsequent ptrace stops will be reported under | |
1207 | the thread group leader's PID. | |
4d12a715 DV |
1208 | .SS Stopped states |
1209 | A tracee can be in two states: running or stopped. | |
ad84c543 | 1210 | For the purposes of ptrace, a tracee which is blocked in a system call |
8da59274 DV |
1211 | (such as |
1212 | .BR read (2), | |
ad84c543 MK |
1213 | .BR pause (2), |
1214 | etc.) | |
1215 | is nevertheless considered to be running, even if the tracee is blocked | |
8da59274 DV |
1216 | for a long time. |
1217 | The state of the tracee after | |
1ae6b2c7 | 1218 | .B PTRACE_LISTEN |
8da59274 | 1219 | is somewhat of a gray area: it is not in any ptrace-stop (ptrace commands |
ad84c543 MK |
1220 | won't work on it, and it will deliver |
1221 | .BR waitpid (2) | |
1222 | notifications), | |
8da59274 DV |
1223 | but it also may be considered "stopped" because |
1224 | it is not executing instructions (is not scheduled), and if it was | |
1225 | in group-stop before | |
1226 | .BR PTRACE_LISTEN , | |
ad84c543 MK |
1227 | it will not respond to signals until |
1228 | .B SIGCONT | |
1229 | is received. | |
dd3568a1 | 1230 | .PP |
181f997f | 1231 | There are many kinds of states when the tracee is stopped, and in ptrace |
8b20acd1 | 1232 | discussions they are often conflated. |
181f997f | 1233 | Therefore, it is important to use precise terms. |
dd3568a1 | 1234 | .PP |
181f997f MK |
1235 | In this manual page, any stopped state in which the tracee is ready |
1236 | to accept ptrace commands from the tracer is called | |
1237 | .IR ptrace-stop . | |
8b20acd1 | 1238 | Ptrace-stops can |
181f997f MK |
1239 | be further subdivided into |
1240 | .IR signal-delivery-stop , | |
1241 | .IR group-stop , | |
1242 | .IR syscall-stop , | |
20e64af8 | 1243 | .IR "PTRACE_EVENT stops" , |
181f997f MK |
1244 | and so on. |
1245 | These stopped states are described in detail below. | |
dd3568a1 | 1246 | .PP |
181f997f MK |
1247 | When the running tracee enters ptrace-stop, it notifies its tracer using |
1248 | .BR waitpid (2) | |
1249 | (or one of the other "wait" system calls). | |
1250 | Most of this manual page assumes that the tracer waits with: | |
dd3568a1 | 1251 | .PP |
1ae6b2c7 AC |
1252 | .in +4n |
1253 | .EX | |
1254 | pid = waitpid(pid_or_minus_1, &status, __WALL); | |
1255 | .EE | |
1256 | .in | |
dd3568a1 | 1257 | .PP |
181f997f MK |
1258 | Ptrace-stopped tracees are reported as returns with |
1259 | .I pid | |
1260 | greater than 0 and | |
1261 | .I WIFSTOPPED(status) | |
1262 | true. | |
8898a252 MK |
1263 | .\" Denys Vlasenko: |
1264 | .\" Do we require __WALL usage, or will just using 0 be ok? (With 0, | |
1265 | .\" I am not 100% sure there aren't ugly corner cases.) Are the | |
181f997f MK |
1266 | .\" rules different if user wants to use waitid? Will waitid require |
1267 | .\" WEXITED? | |
1268 | .\" | |
dd3568a1 | 1269 | .PP |
181f997f MK |
1270 | The |
1271 | .B __WALL | |
1272 | flag does not include the | |
1273 | .B WSTOPPED | |
1274 | and | |
1275 | .B WEXITED | |
1276 | flags, but implies their functionality. | |
dd3568a1 | 1277 | .PP |
181f997f MK |
1278 | Setting the |
1279 | .B WCONTINUED | |
1280 | flag when calling | |
1281 | .BR waitpid (2) | |
1282 | is not recommended: the "continued" state is per-process and | |
1283 | consuming it can confuse the real parent of the tracee. | |
dd3568a1 | 1284 | .PP |
181f997f MK |
1285 | Use of the |
1286 | .B WNOHANG | |
1287 | flag may cause | |
1288 | .BR waitpid (2) | |
1289 | to return 0 ("no wait results available yet") | |
1290 | even if the tracer knows there should be a notification. | |
1291 | Example: | |
408731d4 MK |
1292 | .PP |
1293 | .in +4n | |
1294 | .EX | |
1295 | errno = 0; | |
1296 | ptrace(PTRACE_CONT, pid, 0L, 0L); | |
1297 | if (errno == ESRCH) { | |
1298 | /* tracee is dead */ | |
1299 | r = waitpid(tracee, &status, __WALL | WNOHANG); | |
1300 | /* r can still be 0 here! */ | |
1301 | } | |
1302 | .EE | |
1303 | .in | |
bea08fec | 1304 | .\" FIXME . |
181f997f MK |
1305 | .\" waitid usage? WNOWAIT? |
1306 | .\" describe how wait notifications queue (or not queue) | |
dd3568a1 | 1307 | .PP |
4d12a715 | 1308 | The following kinds of ptrace-stops exist: signal-delivery-stops, |
a5c725cf DP |
1309 | group-stops, |
1310 | .B PTRACE_EVENT | |
1311 | stops, syscall-stops. | |
181f997f MK |
1312 | They all are reported by |
1313 | .BR waitpid (2) | |
1314 | with | |
1315 | .I WIFSTOPPED(status) | |
1316 | true. | |
1317 | They may be differentiated by examining the value | |
1318 | .IR status>>8 , | |
1319 | and if there is ambiguity in that value, by querying | |
1320 | .BR PTRACE_GETSIGINFO . | |
181f997f MK |
1321 | (Note: the |
1322 | .I WSTOPSIG(status) | |
dc85ba7c | 1323 | macro can't be used to perform this examination, |
8898a252 | 1324 | because it returns the value |
0ce81ab5 | 1325 | .IR "(status>>8)\ &\ 0xff" .) |
4d12a715 | 1326 | .SS Signal-delivery-stop |
181f997f MK |
1327 | When a (possibly multithreaded) process receives any signal except |
1328 | .BR SIGKILL , | |
1329 | the kernel selects an arbitrary thread which handles the signal. | |
1330 | (If the signal is generated with | |
1331 | .BR tgkill (2), | |
1332 | the target thread can be explicitly selected by the caller.) | |
1333 | If the selected thread is traced, it enters signal-delivery-stop. | |
1334 | At this point, the signal is not yet delivered to the process, | |
1335 | and can be suppressed by the tracer. | |
1336 | If the tracer doesn't suppress the signal, | |
181f997f | 1337 | it passes the signal to the tracee in the next ptrace restart request. |
8b20acd1 | 1338 | This second step of signal delivery is called |
181f997f MK |
1339 | .I "signal injection" |
1340 | in this manual page. | |
1341 | Note that if the signal is blocked, | |
1342 | signal-delivery-stop doesn't happen until the signal is unblocked, | |
1343 | with the usual exception that | |
1344 | .B SIGSTOP | |
1345 | can't be blocked. | |
dd3568a1 | 1346 | .PP |
181f997f MK |
1347 | Signal-delivery-stop is observed by the tracer as |
1348 | .BR waitpid (2) | |
1349 | returning with | |
1350 | .I WIFSTOPPED(status) | |
f098951d | 1351 | true, with the signal returned by |
181f997f | 1352 | .IR WSTOPSIG(status) . |
f098951d | 1353 | If the signal is |
181f997f MK |
1354 | .BR SIGTRAP , |
1355 | this may be a different kind of ptrace-stop; | |
1356 | see the "Syscall-stops" and "execve" sections below for details. | |
8b20acd1 | 1357 | If |
181f997f MK |
1358 | .I WSTOPSIG(status) |
1359 | returns a stopping signal, this may be a group-stop; see below. | |
4d12a715 | 1360 | .SS Signal injection and suppression |
181f997f MK |
1361 | After signal-delivery-stop is observed by the tracer, |
1362 | the tracer should restart the tracee with the call | |
dd3568a1 | 1363 | .PP |
1ae6b2c7 AC |
1364 | .in +4n |
1365 | .EX | |
1366 | ptrace(PTRACE_restart, pid, 0, sig) | |
1367 | .EE | |
1368 | .in | |
dd3568a1 | 1369 | .PP |
181f997f MK |
1370 | where |
1371 | .B PTRACE_restart | |
1372 | is one of the restarting ptrace requests. | |
1373 | If | |
1374 | .I sig | |
1375 | is 0, then a signal is not delivered. | |
1376 | Otherwise, the signal | |
1377 | .I sig | |
1378 | is delivered. | |
1379 | This operation is called | |
1380 | .I "signal injection" | |
1381 | in this manual page, to distinguish it from signal-delivery-stop. | |
dd3568a1 | 1382 | .PP |
8898a252 | 1383 | The |
181f997f MK |
1384 | .I sig |
1385 | value may be different from the | |
1386 | .I WSTOPSIG(status) | |
1387 | value: the tracer can cause a different signal to be injected. | |
dd3568a1 | 1388 | .PP |
181f997f | 1389 | Note that a suppressed signal still causes system calls to return |
8b20acd1 | 1390 | prematurely. |
15d33661 | 1391 | In this case, system calls will be restarted: the tracer will |
a17e05c5 | 1392 | observe the tracee to reexecute the interrupted system call (or |
a5c725cf | 1393 | .BR restart_syscall (2) |
177660fa | 1394 | system call for a few system calls which use a different mechanism |
f098951d DV |
1395 | for restarting) if the tracer uses |
1396 | .BR PTRACE_SYSCALL . | |
1397 | Even system calls (such as | |
a5c725cf | 1398 | .BR poll (2)) |
f098951d | 1399 | which are not restartable after signal are restarted after |
a17e05c5 | 1400 | signal is suppressed; |
177660fa | 1401 | however, kernel bugs exist which cause some system calls to fail with |
181f997f MK |
1402 | .B EINTR |
1403 | even though no observable signal is injected to the tracee. | |
dd3568a1 | 1404 | .PP |
8898a252 | 1405 | Restarting ptrace commands issued in ptrace-stops other than |
181f997f MK |
1406 | signal-delivery-stop are not guaranteed to inject a signal, even if |
1407 | .I sig | |
8b20acd1 | 1408 | is nonzero. |
181f997f MK |
1409 | No error is reported; a nonzero |
1410 | .I sig | |
1411 | may simply be ignored. | |
1412 | Ptrace users should not try to "create a new signal" this way: use | |
1413 | .BR tgkill (2) | |
1414 | instead. | |
dd3568a1 | 1415 | .PP |
8898a252 MK |
1416 | The fact that signal injection requests may be ignored |
1417 | when restarting the tracee after | |
1418 | ptrace stops that are not signal-delivery-stops | |
1419 | is a cause of confusion among ptrace users. | |
181f997f MK |
1420 | One typical scenario is that the tracer observes group-stop, |
1421 | mistakes it for signal-delivery-stop, restarts the tracee with | |
efeece04 | 1422 | .PP |
1ae6b2c7 AC |
1423 | .in +4n |
1424 | .EX | |
1425 | ptrace(PTRACE_restart, pid, 0, stopsig) | |
1426 | .EE | |
1427 | .in | |
efeece04 | 1428 | .PP |
181f997f MK |
1429 | with the intention of injecting |
1430 | .IR stopsig , | |
1431 | but | |
1432 | .I stopsig | |
1433 | gets ignored and the tracee continues to run. | |
dd3568a1 | 1434 | .PP |
181f997f MK |
1435 | The |
1436 | .B SIGCONT | |
1437 | signal has a side effect of waking up (all threads of) | |
1438 | a group-stopped process. | |
1439 | This side effect happens before signal-delivery-stop. | |
a5c725cf | 1440 | The tracer can't suppress this side effect (it can |
181f997f | 1441 | only suppress signal injection, which only causes the |
1ae6b2c7 | 1442 | .B SIGCONT |
181f997f MK |
1443 | handler to not be executed in the tracee, if such a handler is installed). |
1444 | In fact, waking up from group-stop may be followed by | |
1445 | signal-delivery-stop for signal(s) | |
1446 | .I other than | |
1447 | .BR SIGCONT , | |
1448 | if they were pending when | |
1449 | .B SIGCONT | |
1450 | was delivered. | |
1451 | In other words, | |
1452 | .B SIGCONT | |
1453 | may be not the first signal observed by the tracee after it was sent. | |
dd3568a1 | 1454 | .PP |
181f997f | 1455 | Stopping signals cause (all threads of) a process to enter group-stop. |
4d12a715 | 1456 | This side effect happens after signal injection, and therefore can be |
181f997f | 1457 | suppressed by the tracer. |
dd3568a1 | 1458 | .PP |
dc85ba7c MK |
1459 | In Linux 2.4 and earlier, the |
1460 | .B SIGSTOP | |
1461 | signal can't be injected. | |
1462 | .\" In the Linux 2.4 sources, in arch/i386/kernel/signal.c::do_signal(), | |
1463 | .\" there is: | |
d6e37473 | 1464 | .\" |
dc85ba7c MK |
1465 | .\" /* The debugger continued. Ignore SIGSTOP. */ |
1466 | .\" if (signr == SIGSTOP) | |
1467 | .\" continue; | |
dd3568a1 | 1468 | .PP |
181f997f MK |
1469 | .B PTRACE_GETSIGINFO |
1470 | can be used to retrieve a | |
1471 | .I siginfo_t | |
1472 | structure which corresponds to the delivered signal. | |
1473 | .B PTRACE_SETSIGINFO | |
1474 | may be used to modify it. | |
1475 | If | |
1476 | .B PTRACE_SETSIGINFO | |
1477 | has been used to alter | |
1478 | .IR siginfo_t , | |
1479 | the | |
1480 | .I si_signo | |
1481 | field and the | |
1482 | .I sig | |
1483 | parameter in the restarting command must match, | |
4d12a715 DV |
1484 | otherwise the result is undefined. |
1485 | .SS Group-stop | |
181f997f | 1486 | When a (possibly multithreaded) process receives a stopping signal, |
8b20acd1 MK |
1487 | all threads stop. |
1488 | If some threads are traced, they enter a group-stop. | |
181f997f MK |
1489 | Note that the stopping signal will first cause signal-delivery-stop |
1490 | (on one tracee only), and only after it is injected by the tracer | |
1491 | (or after it was dispatched to a thread which isn't traced), | |
1492 | will group-stop be initiated on | |
1493 | .I all | |
1494 | tracees within the multithreaded process. | |
1495 | As usual, every tracee reports its group-stop separately | |
1496 | to the corresponding tracer. | |
dd3568a1 | 1497 | .PP |
181f997f MK |
1498 | Group-stop is observed by the tracer as |
1499 | .BR waitpid (2) | |
1500 | returning with | |
1501 | .I WIFSTOPPED(status) | |
1502 | true, with the stopping signal available via | |
1503 | .IR WSTOPSIG(status) . | |
1504 | The same result is returned by some other classes of ptrace-stops, | |
1505 | therefore the recommended practice is to perform the call | |
dd3568a1 | 1506 | .PP |
1ae6b2c7 AC |
1507 | .in +4n |
1508 | .EX | |
1509 | ptrace(PTRACE_GETSIGINFO, pid, 0, &siginfo) | |
1510 | .EE | |
1511 | .in | |
dd3568a1 | 1512 | .PP |
181f997f MK |
1513 | The call can be avoided if the signal is not |
1514 | .BR SIGSTOP , | |
1515 | .BR SIGTSTP , | |
1516 | .BR SIGTTIN , | |
1517 | or | |
1518 | .BR SIGTTOU ; | |
1519 | only these four signals are stopping signals. | |
1520 | If the tracer sees something else, it can't be a group-stop. | |
1521 | Otherwise, the tracer needs to call | |
1522 | .BR PTRACE_GETSIGINFO . | |
1523 | If | |
1524 | .B PTRACE_GETSIGINFO | |
1525 | fails with | |
1526 | .BR EINVAL , | |
1527 | then it is definitely a group-stop. | |
1528 | (Other failure codes are possible, such as | |
1529 | .B ESRCH | |
1530 | ("no such process") if a | |
1531 | .B SIGKILL | |
1532 | killed the tracee.) | |
dd3568a1 | 1533 | .PP |
ad84c543 | 1534 | If tracee was attached using |
72906215 | 1535 | .BR PTRACE_SEIZE , |
ad84c543 | 1536 | group-stop is indicated by |
8da59274 | 1537 | .BR PTRACE_EVENT_STOP : |
ad84c543 MK |
1538 | .IR "status>>16 == PTRACE_EVENT_STOP" . |
1539 | This allows detection of group-stops | |
1540 | without requiring an extra | |
8da59274 DV |
1541 | .B PTRACE_GETSIGINFO |
1542 | call. | |
dd3568a1 | 1543 | .PP |
f04ba477 | 1544 | As of Linux 2.6.38, |
181f997f MK |
1545 | after the tracer sees the tracee ptrace-stop and until it |
1546 | restarts or kills it, the tracee will not run, | |
1547 | and will not send notifications (except | |
1548 | .B SIGKILL | |
1549 | death) to the tracer, even if the tracer enters into another | |
1550 | .BR waitpid (2) | |
8b20acd1 | 1551 | call. |
dd3568a1 | 1552 | .PP |
b8d02d56 MK |
1553 | The kernel behavior described in the previous paragraph |
1554 | causes a problem with transparent handling of stopping signals. | |
1555 | If the tracer restarts the tracee after group-stop, | |
dc85ba7c | 1556 | the stopping signal |
8898a252 | 1557 | is effectively ignored\(emthe tracee doesn't remain stopped, it runs. |
181f997f MK |
1558 | If the tracer doesn't restart the tracee before entering into the next |
1559 | .BR waitpid (2), | |
1560 | future | |
1561 | .B SIGCONT | |
b8d02d56 MK |
1562 | signals will not be reported to the tracer; |
1563 | this would cause the | |
181f997f | 1564 | .B SIGCONT |
b8d02d56 | 1565 | signals to have no effect on the tracee. |
dd3568a1 | 1566 | .PP |
f04ba477 | 1567 | Since Linux 3.4, there is a method to overcome this problem: instead of |
ba8f446e DV |
1568 | .BR PTRACE_CONT , |
1569 | a | |
1570 | .B PTRACE_LISTEN | |
1571 | command can be used to restart a tracee in a way where it does not execute, | |
f04ba477 MK |
1572 | but waits for a new event which it can report via |
1573 | .BR waitpid (2) | |
1574 | (such as when | |
ba8f446e DV |
1575 | it is restarted by a |
1576 | .BR SIGCONT ). | |
4d12a715 | 1577 | .SS PTRACE_EVENT stops |
181f997f MK |
1578 | If the tracer sets |
1579 | .B PTRACE_O_TRACE_* | |
1580 | options, the tracee will enter ptrace-stops called | |
1581 | .B PTRACE_EVENT | |
1582 | stops. | |
dd3568a1 | 1583 | .PP |
181f997f MK |
1584 | .B PTRACE_EVENT |
1585 | stops are observed by the tracer as | |
1586 | .BR waitpid (2) | |
1587 | returning with | |
1588 | .IR WIFSTOPPED(status) , | |
1589 | and | |
1590 | .I WSTOPSIG(status) | |
1591 | returns | |
1ae6b2c7 | 1592 | .B SIGTRAP |
302c512c DV |
1593 | (or for |
1594 | .BR PTRACE_EVENT_STOP , | |
1595 | returns the stopping signal if tracee is in a group-stop). | |
181f997f MK |
1596 | An additional bit is set in the higher byte of the status word: |
1597 | the value | |
1598 | .I status>>8 | |
1599 | will be | |
efeece04 | 1600 | .PP |
1ae6b2c7 AC |
1601 | .in +4n |
1602 | .EX | |
1603 | ((PTRACE_EVENT_foo<<8) | SIGTRAP). | |
1604 | .EE | |
1605 | .in | |
efeece04 | 1606 | .PP |
8b20acd1 | 1607 | The following events exist: |
181f997f MK |
1608 | .TP |
1609 | .B PTRACE_EVENT_VFORK | |
1610 | Stop before return from | |
1611 | .BR vfork (2) | |
1612 | or | |
1613 | .BR clone (2) | |
1614 | with the | |
1615 | .B CLONE_VFORK | |
1616 | flag. | |
1617 | When the tracee is continued after this stop, it will wait for child to | |
1618 | exit/exec before continuing its execution | |
1619 | (in other words, the usual behavior on | |
1620 | .BR vfork (2)). | |
1621 | .TP | |
1622 | .B PTRACE_EVENT_FORK | |
1623 | Stop before return from | |
1624 | .BR fork (2) | |
1625 | or | |
1626 | .BR clone (2) | |
1627 | with the exit signal set to | |
1628 | .BR SIGCHLD . | |
1629 | .TP | |
1630 | .B PTRACE_EVENT_CLONE | |
1631 | Stop before return from | |
a5c725cf | 1632 | .BR clone (2). |
181f997f MK |
1633 | .TP |
1634 | .B PTRACE_EVENT_VFORK_DONE | |
1635 | Stop before return from | |
1636 | .BR vfork (2) | |
1637 | or | |
1638 | .BR clone (2) | |
1639 | with the | |
1640 | .B CLONE_VFORK | |
1641 | flag, | |
1642 | but after the child unblocked this tracee by exiting or execing. | |
dd3568a1 | 1643 | .PP |
181f997f MK |
1644 | For all four stops described above, |
1645 | the stop occurs in the parent (i.e., the tracee), | |
1646 | not in the newly created thread. | |
1ae6b2c7 | 1647 | .B PTRACE_GETEVENTMSG |
181f997f MK |
1648 | can be used to retrieve the new thread's ID. |
1649 | .TP | |
1650 | .B PTRACE_EVENT_EXEC | |
1651 | Stop before return from | |
1652 | .BR execve (2). | |
b16d33ef | 1653 | Since Linux 3.0, |
1ae6b2c7 | 1654 | .B PTRACE_GETEVENTMSG |
b16d33ef | 1655 | returns the former thread ID. |
181f997f MK |
1656 | .TP |
1657 | .B PTRACE_EVENT_EXIT | |
1658 | Stop before exit (including death from | |
1659 | .BR exit_group (2)), | |
1660 | signal death, or exit caused by | |
1661 | .BR execve (2) | |
1662 | in a multithreaded process. | |
1663 | .B PTRACE_GETEVENTMSG | |
1664 | returns the exit status. | |
8b20acd1 MK |
1665 | Registers can be examined |
1666 | (unlike when "real" exit happens). | |
181f997f MK |
1667 | The tracee is still alive; it needs to be |
1668 | .BR PTRACE_CONT ed | |
1669 | or | |
1670 | .BR PTRACE_DETACH ed | |
1671 | to finish exiting. | |
ba8f446e DV |
1672 | .TP |
1673 | .B PTRACE_EVENT_STOP | |
1674 | Stop induced by | |
1675 | .B PTRACE_INTERRUPT | |
29f9b8fb DV |
1676 | command, or group-stop, or initial ptrace-stop when a new child is attached |
1677 | (only if attached using | |
28e2ca57 | 1678 | .BR PTRACE_SEIZE ). |
3b4a59c4 KC |
1679 | .TP |
1680 | .B PTRACE_EVENT_SECCOMP | |
1681 | Stop triggered by a | |
1682 | .BR seccomp (2) | |
1683 | rule on tracee syscall entry when | |
1ae6b2c7 | 1684 | .B PTRACE_O_TRACESECCOMP |
81c5080b MK |
1685 | has been set by the tracer. |
1686 | The seccomp event message data (from the | |
1ae6b2c7 | 1687 | .B SECCOMP_RET_DATA |
81c5080b | 1688 | portion of the seccomp filter rule) can be retrieved with |
ff20e9ca MK |
1689 | .BR PTRACE_GETEVENTMSG . |
1690 | The semantics of this stop are described in | |
5419141e | 1691 | detail in a separate section below. |
dd3568a1 | 1692 | .PP |
181f997f MK |
1693 | .B PTRACE_GETSIGINFO |
1694 | on | |
1695 | .B PTRACE_EVENT | |
1696 | stops returns | |
b16d33ef DV |
1697 | .B SIGTRAP |
1698 | in | |
181f997f MK |
1699 | .IR si_signo , |
1700 | with | |
1701 | .I si_code | |
1702 | set to | |
1703 | .IR "(event<<8)\ |\ SIGTRAP" . | |
4d12a715 | 1704 | .SS Syscall-stops |
181f997f | 1705 | If the tracee was restarted by |
1ae6b2c7 | 1706 | .B PTRACE_SYSCALL |
131bcd7a KF |
1707 | or |
1708 | .BR PTRACE_SYSEMU , | |
181f997f | 1709 | the tracee enters |
131bcd7a KF |
1710 | syscall-enter-stop just prior to entering any system call (which |
1711 | will not be executed if the restart was using | |
ff20e9ca | 1712 | .BR PTRACE_SYSEMU , |
131bcd7a KF |
1713 | regardless of any change made to registers at this point or how the |
1714 | tracee is restarted after this stop). | |
1715 | No matter which method caused the syscall-entry-stop, | |
1716 | if the tracer restarts the tracee with | |
181f997f MK |
1717 | .BR PTRACE_SYSCALL , |
1718 | the tracee enters syscall-exit-stop when the system call is finished, | |
1719 | or if it is interrupted by a signal. | |
1720 | (That is, signal-delivery-stop never happens between syscall-enter-stop | |
1721 | and syscall-exit-stop; it happens | |
1722 | .I after | |
ff20e9ca MK |
1723 | syscall-exit-stop.). |
1724 | If the tracee is continued using any other method (including | |
1725 | .BR PTRACE_SYSEMU ), | |
1726 | no syscall-exit-stop occurs. | |
1727 | Note that all mentions | |
1ae6b2c7 | 1728 | .B PTRACE_SYSEMU |
131bcd7a | 1729 | apply equally to |
575bac0f | 1730 | .BR PTRACE_SYSEMU_SINGLESTEP . |
dd3568a1 | 1731 | .PP |
0d5b85ca | 1732 | However, even if the tracee was continued using |
2bb165ec MK |
1733 | .BR PTRACE_SYSCALL , |
1734 | it is not guaranteed that the next stop will be a syscall-exit-stop. | |
181f997f MK |
1735 | Other possibilities are that the tracee may stop in a |
1736 | .B PTRACE_EVENT | |
5419141e | 1737 | stop (including seccomp stops), exit (if it entered |
181f997f MK |
1738 | .BR _exit (2) |
1739 | or | |
1740 | .BR exit_group (2)), | |
1741 | be killed by | |
1742 | .BR SIGKILL , | |
1743 | or die silently (if it is a thread group leader, the | |
1744 | .BR execve (2) | |
1745 | happened in another thread, | |
1746 | and that thread is not traced by the same tracer; | |
1747 | this situation is discussed later). | |
dd3568a1 | 1748 | .PP |
181f997f MK |
1749 | Syscall-enter-stop and syscall-exit-stop are observed by the tracer as |
1750 | .BR waitpid (2) | |
1751 | returning with | |
1752 | .I WIFSTOPPED(status) | |
1753 | true, and | |
1754 | .I WSTOPSIG(status) | |
1755 | giving | |
1756 | .BR SIGTRAP . | |
1757 | If the | |
1758 | .B PTRACE_O_TRACESYSGOOD | |
1759 | option was set by the tracer, then | |
1760 | .I WSTOPSIG(status) | |
1761 | will give the value | |
1762 | .IR "(SIGTRAP\ |\ 0x80)" . | |
dd3568a1 | 1763 | .PP |
4d12a715 | 1764 | Syscall-stops can be distinguished from signal-delivery-stop with |
181f997f MK |
1765 | .B SIGTRAP |
1766 | by querying | |
1ae6b2c7 | 1767 | .B PTRACE_GETSIGINFO |
181f997f MK |
1768 | for the following cases: |
1769 | .TP | |
1770 | .IR si_code " <= 0" | |
1771 | .B SIGTRAP | |
7fac88a9 | 1772 | was delivered as a result of a user-space action, |
8898a252 | 1773 | for example, a system call |
181f997f | 1774 | .RB ( tgkill (2), |
8898a252 | 1775 | .BR kill (2), |
181f997f | 1776 | .BR sigqueue (3), |
8898a252 MK |
1777 | etc.), |
1778 | expiration of a POSIX timer, | |
1779 | change of state on a POSIX message queue, | |
1780 | or completion of an asynchronous I/O request. | |
181f997f MK |
1781 | .TP |
1782 | .IR si_code " == SI_KERNEL (0x80)" | |
1783 | .B SIGTRAP | |
1784 | was sent by the kernel. | |
1785 | .TP | |
1786 | .IR si_code " == SIGTRAP or " si_code " == (SIGTRAP|0x80)" | |
1787 | This is a syscall-stop. | |
dd3568a1 | 1788 | .PP |
181f997f MK |
1789 | However, syscall-stops happen very often (twice per system call), |
1790 | and performing | |
1791 | .B PTRACE_GETSIGINFO | |
1792 | for every syscall-stop may be somewhat expensive. | |
dd3568a1 | 1793 | .PP |
181f997f MK |
1794 | Some architectures allow the cases to be distinguished |
1795 | by examining registers. | |
1796 | For example, on x86, | |
1797 | .I rax | |
1798 | == | |
cd415e73 | 1799 | .RB \- ENOSYS |
181f997f MK |
1800 | in syscall-enter-stop. |
1801 | Since | |
1802 | .B SIGTRAP | |
1803 | (like any other signal) always happens | |
1804 | .I after | |
1805 | syscall-exit-stop, | |
1806 | and at this point | |
1807 | .I rax | |
1808 | almost never contains | |
cd415e73 | 1809 | .RB \- ENOSYS , |
181f997f MK |
1810 | the |
1811 | .B SIGTRAP | |
1812 | looks like "syscall-stop which is not syscall-enter-stop"; | |
1813 | in other words, it looks like a | |
8b20acd1 | 1814 | "stray syscall-exit-stop" and can be detected this way. |
181f997f | 1815 | But such detection is fragile and is best avoided. |
dd3568a1 | 1816 | .PP |
181f997f MK |
1817 | Using the |
1818 | .B PTRACE_O_TRACESYSGOOD | |
a17e05c5 | 1819 | option is the recommended method to distinguish syscall-stops |
b8d02d56 | 1820 | from other kinds of ptrace-stops, |
181f997f | 1821 | since it is reliable and does not incur a performance penalty. |
dd3568a1 | 1822 | .PP |
181f997f MK |
1823 | Syscall-enter-stop and syscall-exit-stop are |
1824 | indistinguishable from each other by the tracer. | |
1825 | The tracer needs to keep track of the sequence of | |
4d12a715 | 1826 | ptrace-stops in order to not misinterpret syscall-enter-stop as |
8b20acd1 | 1827 | syscall-exit-stop or vice versa. |
ff20e9ca | 1828 | In general, a syscall-enter-stop is |
181f997f MK |
1829 | always followed by syscall-exit-stop, |
1830 | .B PTRACE_EVENT | |
ff20e9ca | 1831 | stop, or the tracee's death; |
181f997f | 1832 | no other kinds of ptrace-stop can occur in between. |
5419141e | 1833 | However, note that seccomp stops (see below) can cause syscall-exit-stops, |
0d5b85ca | 1834 | without preceding syscall-entry-stops. |
ff20e9ca MK |
1835 | If seccomp is in use, care needs |
1836 | to be taken not to misinterpret such stops as syscall-entry-stops. | |
dd3568a1 | 1837 | .PP |
181f997f MK |
1838 | If after syscall-enter-stop, |
1839 | the tracer uses a restarting command other than | |
1840 | .BR PTRACE_SYSCALL , | |
1841 | syscall-exit-stop is not generated. | |
dd3568a1 | 1842 | .PP |
181f997f MK |
1843 | .B PTRACE_GETSIGINFO |
1844 | on syscall-stops returns | |
1845 | .B SIGTRAP | |
1846 | in | |
1847 | .IR si_signo , | |
1848 | with | |
1849 | .I si_code | |
1850 | set to | |
1851 | .B SIGTRAP | |
1852 | or | |
1853 | .IR (SIGTRAP|0x80) . | |
ff20e9ca MK |
1854 | .\" |
1855 | .SS PTRACE_EVENT_SECCOMP stops (Linux 3.5 to 4.7) | |
5419141e | 1856 | The behavior of |
1ae6b2c7 | 1857 | .B PTRACE_EVENT_SECCOMP |
5419141e | 1858 | stops and their interaction with other kinds |
ff20e9ca MK |
1859 | of ptrace stops has changed between kernel versions. |
1860 | This documents the behavior | |
1861 | from their introduction until Linux 4.7 (inclusive). | |
1862 | The behavior in later kernel versions is documented in the next section. | |
efeece04 | 1863 | .PP |
5419141e | 1864 | A |
1ae6b2c7 | 1865 | .B PTRACE_EVENT_SECCOMP |
5419141e | 1866 | stop occurs whenever a |
1ae6b2c7 | 1867 | .B SECCOMP_RET_TRACE |
ff20e9ca MK |
1868 | rule is triggered. |
1869 | This is independent of which methods was used to restart the system call. | |
1870 | Notably, seccomp still runs even if the tracee was restarted using | |
1ae6b2c7 | 1871 | .B PTRACE_SYSEMU |
5419141e | 1872 | and this system call is unconditionally skipped. |
efeece04 | 1873 | .PP |
5419141e | 1874 | Restarts from this stop will behave as if the stop had occurred right |
ff20e9ca MK |
1875 | before the system call in question. |
1876 | In particular, both | |
1ae6b2c7 | 1877 | .B PTRACE_SYSCALL |
5419141e | 1878 | and |
1ae6b2c7 | 1879 | .B PTRACE_SYSEMU |
ff20e9ca MK |
1880 | will normally cause a subsequent syscall-entry-stop. |
1881 | However, if after the | |
1ae6b2c7 | 1882 | .B PTRACE_EVENT_SECCOMP |
ff20e9ca MK |
1883 | the system call number is negative, |
1884 | both the syscall-entry-stop and the system call itself will be skipped. | |
1885 | This means that if the system call number is negative after a | |
1ae6b2c7 | 1886 | .B PTRACE_EVENT_SECCOMP |
5419141e | 1887 | and the tracee is restarted using |
f7111396 | 1888 | .BR PTRACE_SYSCALL , |
5419141e | 1889 | the next observed stop will be a syscall-exit-stop, |
ff20e9ca MK |
1890 | rather than the syscall-entry-stop that might have been expected. |
1891 | .\" | |
1892 | .SS PTRACE_EVENT_SECCOMP stops (since Linux 4.8) | |
1893 | Starting with Linux 4.8, | |
1894 | .\" commit 93e35efb8de45393cf61ed07f7b407629bf698ea | |
1895 | the | |
1ae6b2c7 | 1896 | .B PTRACE_EVENT_SECCOMP |
ff20e9ca MK |
1897 | stop was reordered to occur between syscall-entry-stop and |
1898 | syscall-exit-stop. | |
1899 | Note that seccomp no longer runs (and no | |
1900 | .B PTRACE_EVENT_SECCOMP | |
1901 | will be reported) if the system call is skipped due to | |
1902 | .BR PTRACE_SYSEMU . | |
efeece04 | 1903 | .PP |
ff20e9ca MK |
1904 | Functionally, a |
1905 | .B PTRACE_EVENT_SECCOMP | |
1906 | stop functions comparably | |
1907 | to a syscall-entry-stop (i.e., continuations using | |
1ae6b2c7 | 1908 | .B PTRACE_SYSCALL |
ff20e9ca MK |
1909 | will cause syscall-exit-stops, |
1910 | the system call number may be changed and any other modified registers | |
1911 | are visible to the to-be-executed system call as well). | |
1912 | Note that there may be, | |
0d5b85ca | 1913 | but need not have been a preceding syscall-entry-stop. |
efeece04 | 1914 | .PP |
5419141e | 1915 | After a |
1ae6b2c7 | 1916 | .B PTRACE_EVENT_SECCOMP |
ff20e9ca | 1917 | stop, seccomp will be rerun, with a |
1ae6b2c7 | 1918 | .B SECCOMP_RET_TRACE |
5419141e | 1919 | rule now functioning the same as a |
ff20e9ca MK |
1920 | .BR SECCOMP_RET_ALLOW . |
1921 | Specifically, this means that if registers are not modified during the | |
1ae6b2c7 | 1922 | .B PTRACE_EVENT_SECCOMP |
5419141e | 1923 | stop, the system call will then be allowed. |
ff20e9ca | 1924 | .\" |
131bcd7a | 1925 | .SS PTRACE_SINGLESTEP stops |
b8d02d56 | 1926 | [Details of these kinds of stops are yet to be documented.] |
181f997f | 1927 | .\" |
bea08fec | 1928 | .\" FIXME . |
131bcd7a | 1929 | .\" document stops occurring with PTRACE_SINGLESTEP |
ff20e9ca | 1930 | .\" |
4d12a715 | 1931 | .SS Informational and restarting ptrace commands |
181f997f MK |
1932 | Most ptrace commands (all except |
1933 | .BR PTRACE_ATTACH , | |
ba8f446e | 1934 | .BR PTRACE_SEIZE , |
181f997f | 1935 | .BR PTRACE_TRACEME , |
ba8f446e | 1936 | .BR PTRACE_INTERRUPT , |
181f997f MK |
1937 | and |
1938 | .BR PTRACE_KILL ) | |
1939 | require the tracee to be in a ptrace-stop, otherwise they fail with | |
1940 | .BR ESRCH . | |
dd3568a1 | 1941 | .PP |
181f997f MK |
1942 | When the tracee is in ptrace-stop, |
1943 | the tracer can read and write data to | |
1944 | the tracee using informational commands. | |
1945 | These commands leave the tracee in ptrace-stopped state: | |
dd3568a1 | 1946 | .PP |
408731d4 MK |
1947 | .in +4n |
1948 | .EX | |
1949 | ptrace(PTRACE_PEEKTEXT/PEEKDATA/PEEKUSER, pid, addr, 0); | |
1950 | ptrace(PTRACE_POKETEXT/POKEDATA/POKEUSER, pid, addr, long_val); | |
1951 | ptrace(PTRACE_GETREGS/GETFPREGS, pid, 0, &struct); | |
1952 | ptrace(PTRACE_SETREGS/SETFPREGS, pid, 0, &struct); | |
1953 | ptrace(PTRACE_GETREGSET, pid, NT_foo, &iov); | |
1954 | ptrace(PTRACE_SETREGSET, pid, NT_foo, &iov); | |
1955 | ptrace(PTRACE_GETSIGINFO, pid, 0, &siginfo); | |
1956 | ptrace(PTRACE_SETSIGINFO, pid, 0, &siginfo); | |
1957 | ptrace(PTRACE_GETEVENTMSG, pid, 0, &long_var); | |
1958 | ptrace(PTRACE_SETOPTIONS, pid, 0, PTRACE_O_flags); | |
1959 | .EE | |
1960 | .in | |
dd3568a1 | 1961 | .PP |
8b20acd1 | 1962 | Note that some errors are not reported. |
181f997f MK |
1963 | For example, setting signal information |
1964 | .RI ( siginfo ) | |
4d12a715 | 1965 | may have no effect in some ptrace-stops, yet the call may succeed |
181f997f MK |
1966 | (return 0 and not set |
1967 | .IR errno ); | |
1968 | querying | |
1969 | .B PTRACE_GETEVENTMSG | |
1970 | may succeed and return some random value if current ptrace-stop | |
1971 | is not documented as returning a meaningful event message. | |
dd3568a1 | 1972 | .PP |
181f997f | 1973 | The call |
efeece04 | 1974 | .PP |
1ae6b2c7 AC |
1975 | .in +4n |
1976 | .EX | |
1977 | ptrace(PTRACE_SETOPTIONS, pid, 0, PTRACE_O_flags); | |
1978 | .EE | |
1979 | .in | |
efeece04 | 1980 | .PP |
181f997f MK |
1981 | affects one tracee. |
1982 | The tracee's current flags are replaced. | |
1983 | Flags are inherited by new tracees created and "auto-attached" via active | |
1984 | .BR PTRACE_O_TRACEFORK , | |
1985 | .BR PTRACE_O_TRACEVFORK , | |
1986 | or | |
1ae6b2c7 | 1987 | .B PTRACE_O_TRACECLONE |
181f997f | 1988 | options. |
dd3568a1 | 1989 | .PP |
181f997f MK |
1990 | Another group of commands makes the ptrace-stopped tracee run. |
1991 | They have the form: | |
dd3568a1 | 1992 | .PP |
1ae6b2c7 AC |
1993 | .in +4n |
1994 | .EX | |
1995 | ptrace(cmd, pid, 0, sig); | |
1996 | .EE | |
1997 | .in | |
dd3568a1 | 1998 | .PP |
181f997f MK |
1999 | where |
2000 | .I cmd | |
2001 | is | |
2002 | .BR PTRACE_CONT , | |
ba8f446e | 2003 | .BR PTRACE_LISTEN , |
181f997f MK |
2004 | .BR PTRACE_DETACH , |
2005 | .BR PTRACE_SYSCALL , | |
2006 | .BR PTRACE_SINGLESTEP , | |
2007 | .BR PTRACE_SYSEMU , | |
2008 | or | |
a5c725cf | 2009 | .BR PTRACE_SYSEMU_SINGLESTEP . |
181f997f MK |
2010 | If the tracee is in signal-delivery-stop, |
2011 | .I sig | |
2012 | is the signal to be injected (if it is nonzero). | |
2013 | Otherwise, | |
2014 | .I sig | |
2015 | may be ignored. | |
8898a252 MK |
2016 | (When restarting a tracee from a ptrace-stop other than signal-delivery-stop, |
2017 | recommended practice is to always pass 0 in | |
a5c725cf | 2018 | .IR sig .) |
4d12a715 | 2019 | .SS Attaching and detaching |
181f997f | 2020 | A thread can be attached to the tracer using the call |
efeece04 | 2021 | .PP |
1ae6b2c7 AC |
2022 | .in +4n |
2023 | .EX | |
2024 | ptrace(PTRACE_ATTACH, pid, 0, 0); | |
2025 | .EE | |
2026 | .in | |
efeece04 | 2027 | .PP |
ba8f446e | 2028 | or |
efeece04 | 2029 | .PP |
1ae6b2c7 AC |
2030 | .in +4n |
2031 | .EX | |
2032 | ptrace(PTRACE_SEIZE, pid, 0, PTRACE_O_flags); | |
2033 | .EE | |
2034 | .in | |
efeece04 | 2035 | .PP |
ba8f446e DV |
2036 | .B PTRACE_ATTACH |
2037 | sends | |
181f997f MK |
2038 | .B SIGSTOP |
2039 | to this thread. | |
2040 | If the tracer wants this | |
2041 | .B SIGSTOP | |
2042 | to have no effect, it needs to suppress it. | |
2043 | Note that if other signals are concurrently sent to | |
2044 | this thread during attach, | |
2045 | the tracer may see the tracee enter signal-delivery-stop | |
2046 | with other signal(s) first! | |
2047 | The usual practice is to reinject these signals until | |
2048 | .B SIGSTOP | |
2049 | is seen, then suppress | |
2050 | .B SIGSTOP | |
2051 | injection. | |
181f997f MK |
2052 | The design bug here is that a ptrace attach and a concurrently delivered |
2053 | .B SIGSTOP | |
2054 | may race and the concurrent | |
2055 | .B SIGSTOP | |
2056 | may be lost. | |
2057 | .\" | |
3b1fdaf3 | 2058 | .\" FIXME Describe how to attach to a thread which is already group-stopped. |
dd3568a1 | 2059 | .PP |
181f997f MK |
2060 | Since attaching sends |
2061 | .B SIGSTOP | |
2062 | and the tracer usually suppresses it, this may cause a stray | |
a5c725cf | 2063 | .B EINTR |
181f997f | 2064 | return from the currently executing system call in the tracee, |
a5c725cf | 2065 | as described in the "Signal injection and suppression" section. |
dd3568a1 | 2066 | .PP |
f04ba477 | 2067 | Since Linux 3.4, |
ba8f446e DV |
2068 | .B PTRACE_SEIZE |
2069 | can be used instead of | |
2070 | .BR PTRACE_ATTACH . | |
2071 | .B PTRACE_SEIZE | |
e3948c69 MK |
2072 | does not stop the attached process. |
2073 | If you need to stop | |
ba8f446e DV |
2074 | it after attach (or at any other time) without sending it any signals, |
2075 | use | |
2076 | .B PTRACE_INTERRUPT | |
2077 | command. | |
dd3568a1 | 2078 | .PP |
181f997f | 2079 | The request |
efeece04 | 2080 | .PP |
1ae6b2c7 AC |
2081 | .in +4n |
2082 | .EX | |
2083 | ptrace(PTRACE_TRACEME, 0, 0, 0); | |
2084 | .EE | |
2085 | .in | |
efeece04 | 2086 | .PP |
181f997f MK |
2087 | turns the calling thread into a tracee. |
2088 | The thread continues to run (doesn't enter ptrace-stop). | |
2089 | A common practice is to follow the | |
2090 | .B PTRACE_TRACEME | |
2091 | with | |
efeece04 | 2092 | .PP |
1ae6b2c7 AC |
2093 | .in +4n |
2094 | .EX | |
2095 | raise(SIGSTOP); | |
2096 | .EE | |
2097 | .in | |
efeece04 | 2098 | .PP |
181f997f | 2099 | and allow the parent (which is our tracer now) to observe our |
4d12a715 | 2100 | signal-delivery-stop. |
dd3568a1 | 2101 | .PP |
d6e37473 | 2102 | If the |
181f997f MK |
2103 | .BR PTRACE_O_TRACEFORK , |
2104 | .BR PTRACE_O_TRACEVFORK , | |
2105 | or | |
1ae6b2c7 | 2106 | .B PTRACE_O_TRACECLONE |
181f997f MK |
2107 | options are in effect, then children created by, respectively, |
2108 | .BR vfork (2) | |
2109 | or | |
2110 | .BR clone (2) | |
2111 | with the | |
2112 | .B CLONE_VFORK | |
2113 | flag, | |
2114 | .BR fork (2) | |
2115 | or | |
2116 | .BR clone (2) | |
2117 | with the exit signal set to | |
2118 | .BR SIGCHLD , | |
2119 | and other kinds of | |
2120 | .BR clone (2), | |
2121 | are automatically attached to the same tracer which traced their parent. | |
2122 | .B SIGSTOP | |
2123 | is delivered to the children, causing them to enter | |
2124 | signal-delivery-stop after they exit the system call which created them. | |
dd3568a1 | 2125 | .PP |
181f997f | 2126 | Detaching of the tracee is performed by: |
efeece04 | 2127 | .PP |
1ae6b2c7 AC |
2128 | .in +4n |
2129 | .EX | |
2130 | ptrace(PTRACE_DETACH, pid, 0, sig); | |
2131 | .EE | |
2132 | .in | |
efeece04 | 2133 | .PP |
181f997f MK |
2134 | .B PTRACE_DETACH |
2135 | is a restarting operation; | |
2136 | therefore it requires the tracee to be in ptrace-stop. | |
2137 | If the tracee is in signal-delivery-stop, a signal can be injected. | |
2138 | Otherwise, the | |
2139 | .I sig | |
2140 | parameter may be silently ignored. | |
dd3568a1 | 2141 | .PP |
181f997f MK |
2142 | If the tracee is running when the tracer wants to detach it, |
2143 | the usual solution is to send | |
2144 | .B SIGSTOP | |
2145 | (using | |
2146 | .BR tgkill (2), | |
2147 | to make sure it goes to the correct thread), | |
2148 | wait for the tracee to stop in signal-delivery-stop for | |
2149 | .B SIGSTOP | |
2150 | and then detach it (suppressing | |
2151 | .B SIGSTOP | |
2152 | injection). | |
2153 | A design bug is that this can race with concurrent | |
2154 | .BR SIGSTOP s. | |
2155 | Another complication is that the tracee may enter other ptrace-stops | |
2156 | and needs to be restarted and waited for again, until | |
2157 | .B SIGSTOP | |
2158 | is seen. | |
2159 | Yet another complication is to be sure that | |
2160 | the tracee is not already ptrace-stopped, | |
2161 | because no signal delivery happens while it is\(emnot even | |
2162 | .BR SIGSTOP . | |
3b1fdaf3 MK |
2163 | .\" FIXME Describe how to detach from a group-stopped tracee so that it |
2164 | .\" doesn't run, but continues to wait for SIGCONT. | |
dd3568a1 | 2165 | .PP |
181f997f | 2166 | If the tracer dies, all tracees are automatically detached and restarted, |
8b20acd1 | 2167 | unless they were in group-stop. |
b8d02d56 MK |
2168 | Handling of restart from group-stop is currently buggy, |
2169 | but the "as planned" behavior is to leave tracee stopped and waiting for | |
181f997f MK |
2170 | .BR SIGCONT . |
2171 | If the tracee is restarted from signal-delivery-stop, | |
2172 | the pending signal is injected. | |
2173 | .SS execve(2) under ptrace | |
cb729171 | 2174 | .\" clone(2) CLONE_THREAD says: |
181f997f MK |
2175 | .\" If any of the threads in a thread group performs an execve(2), |
2176 | .\" then all threads other than the thread group leader are terminated, | |
d6e37473 | 2177 | .\" and the new program is executed in the thread group leader. |
181f997f | 2178 | .\" |
8898a252 | 2179 | When one thread in a multithreaded process calls |
181f997f MK |
2180 | .BR execve (2), |
2181 | the kernel destroys all other threads in the process, | |
2182 | .\" In kernel 3.1 sources, see fs/exec.c::de_thread() | |
2183 | and resets the thread ID of the execing thread to the | |
2184 | thread group ID (process ID). | |
181f997f MK |
2185 | (Or, to put things another way, when a multithreaded process does an |
2186 | .BR execve (2), | |
8898a252 | 2187 | at completion of the call, it appears as though the |
181f997f MK |
2188 | .BR execve (2) |
2189 | occurred in the thread group leader, regardless of which thread did the | |
2190 | .BR execve (2).) | |
181f997f MK |
2191 | This resetting of the thread ID looks very confusing to tracers: |
2192 | .IP * 3 | |
2193 | All other threads stop in | |
8898a252 | 2194 | .B PTRACE_EVENT_EXIT |
b8d02d56 | 2195 | stop, if the |
1ae6b2c7 | 2196 | .B PTRACE_O_TRACEEXIT |
8898a252 | 2197 | option was turned on. |
181f997f MK |
2198 | Then all other threads except the thread group leader report |
2199 | death as if they exited via | |
2200 | .BR _exit (2) | |
2201 | with exit code 0. | |
b8d02d56 | 2202 | .IP * |
181f997f MK |
2203 | The execing tracee changes its thread ID while it is in the |
2204 | .BR execve (2). | |
2205 | (Remember, under ptrace, the "pid" returned from | |
2206 | .BR waitpid (2), | |
2207 | or fed into ptrace calls, is the tracee's thread ID.) | |
2208 | That is, the tracee's thread ID is reset to be the same as its process ID, | |
2209 | which is the same as the thread group leader's thread ID. | |
2210 | .IP * | |
f098951d DV |
2211 | Then a |
2212 | .B PTRACE_EVENT_EXEC | |
2213 | stop happens, if the | |
1ae6b2c7 | 2214 | .B PTRACE_O_TRACEEXEC |
f098951d DV |
2215 | option was turned on. |
2216 | .IP * | |
2217 | If the thread group leader has reported its | |
2218 | .B PTRACE_EVENT_EXIT | |
2219 | stop by this time, | |
181f997f MK |
2220 | it appears to the tracer that |
2221 | the dead thread leader "reappears from nowhere". | |
a17e05c5 | 2222 | (Note: the thread group leader does not report death via |
f098951d DV |
2223 | .I WIFEXITED(status) |
2224 | until there is at least one other live thread. | |
a17e05c5 | 2225 | This eliminates the possibility that the tracer will see |
f098951d | 2226 | it dying and then reappearing.) |
181f997f MK |
2227 | If the thread group leader was still alive, |
2228 | for the tracer this may look as if thread group leader | |
2229 | returns from a different system call than it entered, | |
2230 | or even "returned from a system call even though | |
2231 | it was not in any system call". | |
2232 | If the thread group leader was not traced | |
2233 | (or was traced by a different tracer), then during | |
2234 | .BR execve (2) | |
2235 | it will appear as if it has become a tracee of | |
2236 | the tracer of the execing tracee. | |
dd3568a1 | 2237 | .PP |
181f997f MK |
2238 | All of the above effects are the artifacts of |
2239 | the thread ID change in the tracee. | |
dd3568a1 | 2240 | .PP |
181f997f MK |
2241 | The |
2242 | .B PTRACE_O_TRACEEXEC | |
2243 | option is the recommended tool for dealing with this situation. | |
b8d02d56 | 2244 | First, it enables |
1ae6b2c7 | 2245 | .B PTRACE_EVENT_EXEC |
a5c725cf | 2246 | stop, |
b8d02d56 | 2247 | which occurs before |
a5c725cf | 2248 | .BR execve (2) |
b8d02d56 MK |
2249 | returns. |
2250 | In this stop, the tracer can use | |
2251 | .B PTRACE_GETEVENTMSG | |
2252 | to retrieve the tracee's former thread ID. | |
94e66ffd | 2253 | (This feature was introduced in Linux 3.0.) |
b8d02d56 MK |
2254 | Second, the |
2255 | .B PTRACE_O_TRACEEXEC | |
2256 | option disables legacy | |
2257 | .B SIGTRAP | |
2258 | generation on | |
2259 | .BR execve (2). | |
dd3568a1 | 2260 | .PP |
181f997f MK |
2261 | When the tracer receives |
2262 | .B PTRACE_EVENT_EXEC | |
2263 | stop notification, | |
2264 | it is guaranteed that except this tracee and the thread group leader, | |
2265 | no other threads from the process are alive. | |
dd3568a1 | 2266 | .PP |
181f997f MK |
2267 | On receiving the |
2268 | .B PTRACE_EVENT_EXEC | |
2269 | stop notification, | |
2270 | the tracer should clean up all its internal | |
2271 | data structures describing the threads of this process, | |
2272 | and retain only one data structure\(emone which | |
2273 | describes the single still running tracee, with | |
efeece04 | 2274 | .PP |
1ae6b2c7 AC |
2275 | .in +4n |
2276 | .EX | |
2277 | thread ID == thread group ID == process ID. | |
2278 | .EE | |
2279 | .in | |
dd3568a1 | 2280 | .PP |
181f997f MK |
2281 | Example: two threads call |
2282 | .BR execve (2) | |
2283 | at the same time: | |
dd3568a1 | 2284 | .PP |
4d12a715 | 2285 | .nf |
a5c725cf | 2286 | *** we get syscall-enter-stop in thread 1: ** |
4d12a715 DV |
2287 | PID1 execve("/bin/foo", "foo" <unfinished ...> |
2288 | *** we issue PTRACE_SYSCALL for thread 1 ** | |
a5c725cf | 2289 | *** we get syscall-enter-stop in thread 2: ** |
4d12a715 DV |
2290 | PID2 execve("/bin/bar", "bar" <unfinished ...> |
2291 | *** we issue PTRACE_SYSCALL for thread 2 ** | |
2292 | *** we get PTRACE_EVENT_EXEC for PID0, we issue PTRACE_SYSCALL ** | |
2293 | *** we get syscall-exit-stop for PID0: ** | |
2294 | PID0 <... execve resumed> ) = 0 | |
2295 | .fi | |
dd3568a1 | 2296 | .PP |
181f997f MK |
2297 | If the |
2298 | .B PTRACE_O_TRACEEXEC | |
2299 | option is | |
2300 | .I not | |
28e2ca57 | 2301 | in effect for the execing tracee, |
53cdec41 | 2302 | and if the tracee was |
28e2ca57 DV |
2303 | .BR PTRACE_ATTACH ed |
2304 | rather that | |
2305 | .BR PTRACE_SEIZE d, | |
2306 | the kernel delivers an extra | |
181f997f MK |
2307 | .B SIGTRAP |
2308 | to the tracee after | |
2309 | .BR execve (2) | |
8b20acd1 MK |
2310 | returns. |
2311 | This is an ordinary signal (similar to one which can be | |
181f997f | 2312 | generated by |
2c1acf16 | 2313 | .IR "kill \-TRAP" ), |
181f997f MK |
2314 | not a special kind of ptrace-stop. |
2315 | Employing | |
2316 | .B PTRACE_GETSIGINFO | |
2317 | for this signal returns | |
2318 | .I si_code | |
2319 | set to 0 | |
2320 | .RI ( SI_USER ). | |
2321 | This signal may be blocked by signal mask, | |
2322 | and thus may be delivered (much) later. | |
dd3568a1 | 2323 | .PP |
181f997f MK |
2324 | Usually, the tracer (for example, |
2325 | .BR strace (1)) | |
2326 | would not want to show this extra post-execve | |
2327 | .B SIGTRAP | |
2328 | signal to the user, and would suppress its delivery to the tracee (if | |
2329 | .B SIGTRAP | |
2330 | is set to | |
2331 | .BR SIG_DFL , | |
2332 | it is a killing signal). | |
d6e37473 | 2333 | However, determining |
181f997f MK |
2334 | .I which |
2335 | .B SIGTRAP | |
2336 | to suppress is not easy. | |
2337 | Setting the | |
2338 | .B PTRACE_O_TRACEEXEC | |
28e2ca57 DV |
2339 | option or using |
2340 | .B PTRACE_SEIZE | |
2341 | and thus suppressing this extra | |
181f997f MK |
2342 | .B SIGTRAP |
2343 | is the recommended approach. | |
4d12a715 | 2344 | .SS Real parent |
181f997f MK |
2345 | The ptrace API (ab)uses the standard UNIX parent/child signaling over |
2346 | .BR waitpid (2). | |
2347 | This used to cause the real parent of the process to stop receiving | |
2348 | several kinds of | |
2349 | .BR waitpid (2) | |
2350 | notifications when the child process is traced by some other process. | |
dd3568a1 | 2351 | .PP |
181f997f MK |
2352 | Many of these bugs have been fixed, but as of Linux 2.6.38 several still |
2353 | exist; see BUGS below. | |
dd3568a1 | 2354 | .PP |
181f997f MK |
2355 | As of Linux 2.6.38, the following is believed to work correctly: |
2356 | .IP * 3 | |
dc85ba7c MK |
2357 | exit/death by signal is reported first to the tracer, then, |
2358 | when the tracer consumes the | |
181f997f MK |
2359 | .BR waitpid (2) |
2360 | result, to the real parent (to the real parent only when the | |
2361 | whole multithreaded process exits). | |
181f997f MK |
2362 | If the tracer and the real parent are the same process, |
2363 | the report is sent only once. | |
47297adb | 2364 | .SH RETURN VALUE |
051ec121 | 2365 | On success, the |
78686915 | 2366 | .B PTRACE_PEEK* |
051ec121 | 2367 | requests return the requested data (but see NOTES), |
e7a758e3 JH |
2368 | the |
2369 | .B PTRACE_SECCOMP_GET_FILTER | |
8bc6f5fd DL |
2370 | request returns the number of instructions in the BPF program, |
2371 | the | |
2372 | .B PTRACE_GET_SYSCALL_INFO | |
2373 | request returns the number of bytes available to be written by the kernel, | |
2374 | and other requests return zero. | |
dd3568a1 | 2375 | .PP |
2b2581ee MK |
2376 | On error, all requests return \-1, and |
2377 | .I errno | |
f6a4078b | 2378 | is set to indicate the error. |
8bd58774 | 2379 | Since the value returned by a successful |
0daa9e92 | 2380 | .B PTRACE_PEEK* |
181f997f | 2381 | request may be \-1, the caller must clear |
2b2581ee | 2382 | .I errno |
181f997f MK |
2383 | before the call, and then check it afterward |
2384 | to determine whether or not an error occurred. | |
2b2581ee MK |
2385 | .SH ERRORS |
2386 | .TP | |
2387 | .B EBUSY | |
181f997f | 2388 | (i386 only) There was an error with allocating or freeing a debug register. |
2b2581ee MK |
2389 | .TP |
2390 | .B EFAULT | |
2391 | There was an attempt to read from or write to an invalid area in | |
181f997f | 2392 | the tracer's or the tracee's memory, |
2b2581ee MK |
2393 | probably because the area wasn't mapped or accessible. |
2394 | Unfortunately, under Linux, different variations of this fault | |
2f0af33b MK |
2395 | will return |
2396 | .B EIO | |
2397 | or | |
2398 | .B EFAULT | |
2399 | more or less arbitrarily. | |
2b2581ee MK |
2400 | .TP |
2401 | .B EINVAL | |
2402 | An attempt was made to set an invalid option. | |
2403 | .TP | |
2404 | .B EIO | |
181f997f MK |
2405 | .I request |
2406 | is invalid, or an attempt was made to read from or | |
2407 | write to an invalid area in the tracer's or the tracee's memory, | |
2b2581ee MK |
2408 | or there was a word-alignment violation, |
2409 | or an invalid signal was specified during a restart request. | |
2410 | .TP | |
2411 | .B EPERM | |
2412 | The specified process cannot be traced. | |
2413 | This could be because the | |
4d12a715 | 2414 | tracer has insufficient privileges (the required capability is |
2b2581ee | 2415 | .BR CAP_SYS_PTRACE ); |
00b08db3 | 2416 | unprivileged processes cannot trace processes that they |
2b2581ee MK |
2417 | cannot send signals to or those running |
2418 | set-user-ID/set-group-ID programs, for obvious reasons. | |
181f997f MK |
2419 | Alternatively, the process may already be being traced, |
2420 | or (on kernels before 2.6.26) be | |
e8906093 | 2421 | .BR init (1) |
2b2581ee MK |
2422 | (PID 1). |
2423 | .TP | |
2424 | .B ESRCH | |
2425 | The specified process does not exist, or is not currently being traced | |
181f997f MK |
2426 | by the caller, or is not stopped |
2427 | (for requests that require a stopped tracee). | |
3113c7f3 | 2428 | .SH STANDARDS |
44a2c328 | 2429 | SVr4, 4.3BSD. |
fea681da MK |
2430 | .SH NOTES |
2431 | Although arguments to | |
e511ffb6 | 2432 | .BR ptrace () |
c13182ef | 2433 | are interpreted according to the prototype given, |
5260fe08 | 2434 | glibc currently declares |
e511ffb6 | 2435 | .BR ptrace () |
181f997f MK |
2436 | as a variadic function with only the |
2437 | .I request | |
2438 | argument fixed. | |
ca302d0e DV |
2439 | It is recommended to always supply four arguments, |
2440 | even if the requested operation does not use them, | |
2441 | setting unused/ignored arguments to | |
2442 | .I 0L | |
2443 | or | |
2444 | .IR "(void\ *)\ 0". | |
dd3568a1 | 2445 | .PP |
181f997f MK |
2446 | In Linux kernels before 2.6.26, |
2447 | .\" See commit 00cd5c37afd5f431ac186dd131705048c0a11fdb | |
e8906093 | 2448 | .BR init (1), |
181f997f | 2449 | the process with PID 1, may not be traced. |
dd3568a1 | 2450 | .PP |
674f11ec JH |
2451 | A tracees parent continues to be the tracer even if that tracer calls |
2452 | .BR execve (2). | |
dd3568a1 | 2453 | .PP |
181f997f MK |
2454 | The layout of the contents of memory and the USER area are |
2455 | quite operating-system- and architecture-specific. | |
8660aec0 MK |
2456 | The offset supplied, and the data returned, |
2457 | might not entirely match with the definition of | |
2458 | .IR "struct user" . | |
2459 | .\" See http://lkml.org/lkml/2008/5/8/375 | |
dd3568a1 | 2460 | .PP |
181f997f | 2461 | The size of a "word" is determined by the operating-system variant |
3e18f289 | 2462 | (e.g., for 32-bit Linux it is 32 bits). |
dd3568a1 | 2463 | .PP |
fea681da | 2464 | This page documents the way the |
e511ffb6 | 2465 | .BR ptrace () |
c13182ef | 2466 | call works currently in Linux. |
07318a59 | 2467 | Its behavior differs significantly on other flavors of UNIX. |
e63ad01d | 2468 | In any case, use of |
e511ffb6 | 2469 | .BR ptrace () |
181f997f | 2470 | is highly specific to the operating system and architecture. |
4978c606 | 2471 | .\" |
ace93363 MK |
2472 | .\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" |
2473 | .\" | |
2474 | .SS Ptrace access mode checking | |
2475 | Various parts of the kernel-user-space API (not just | |
bf7bc8b8 | 2476 | .BR ptrace () |
00172d8d MK |
2477 | operations), require so-called "ptrace access mode" checks, |
2478 | whose outcome determines whether an operation is permitted | |
2479 | (or, in a few cases, causes a "read" operation to return sanitized data). | |
2480 | These checks are performed in cases where one process can | |
2481 | inspect sensitive information about, | |
2482 | or in some cases modify the state of, another process. | |
2483 | The checks are based on factors such as the credentials and capabilities | |
2484 | of the two processes, | |
2485 | whether or not the "target" process is dumpable, | |
2486 | and the results of checks performed by any enabled Linux Security Module | |
2487 | (LSM)\(emfor example, SELinux, Yama, or Smack\(emand by the commoncap LSM | |
611d3ac4 | 2488 | (which is always invoked). |
efeece04 | 2489 | .PP |
be26fa86 | 2490 | Prior to Linux 2.6.27, all access checks were of a single type. |
ace93363 MK |
2491 | Since Linux 2.6.27, |
2492 | .\" commit 006ebb40d3d65338bd74abb03b945f8d60e362bd | |
2493 | two access mode levels are distinguished: | |
2494 | .TP | |
1ae6b2c7 | 2495 | .B PTRACE_MODE_READ |
ace93363 MK |
2496 | For "read" operations or other operations that are less dangerous, |
2497 | such as: | |
2498 | .BR get_robust_list (2); | |
2499 | .BR kcmp (2); | |
2500 | reading | |
1ae6b2c7 AC |
2501 | .IR /proc/ pid /auxv , |
2502 | .IR /proc/ pid /environ , | |
ace93363 | 2503 | or |
1ae6b2c7 | 2504 | .IR /proc/ pid /stat ; |
ace93363 MK |
2505 | or |
2506 | .BR readlink (2) | |
2507 | of a | |
1ae6b2c7 | 2508 | .IR /proc/ pid /ns/* |
ace93363 MK |
2509 | file. |
2510 | .TP | |
1ae6b2c7 | 2511 | .B PTRACE_MODE_ATTACH |
ace93363 MK |
2512 | For "write" operations, or other operations that are more dangerous, |
2513 | such as: ptrace attaching | |
2514 | .RB ( PTRACE_ATTACH ) | |
2515 | to another process | |
2516 | or calling | |
2517 | .BR process_vm_writev (2). | |
2518 | .RB ( PTRACE_MODE_ATTACH | |
2519 | was effectively the default before Linux 2.6.27.) | |
bcd0d82d MK |
2520 | .\" |
2521 | .\" Regarding the above description of the distinction between | |
2522 | .\" PTRACE_MODE_READ and PTRACE_MODE_ATTACH, Stephen Smalley notes: | |
2523 | .\" | |
2524 | .\" That was the intent when the distinction was introduced, but it doesn't | |
2525 | .\" appear to have been properly maintained, e.g. there is now a common | |
2526 | .\" helper lock_trace() that is used for | |
2527 | .\" /proc/pid/{stack,syscall,personality} but checks PTRACE_MODE_ATTACH, and | |
2528 | .\" PTRACE_MODE_ATTACH is also used in timerslack_ns_write/show(). Likely | |
2529 | .\" should review and make them consistent. There was also some debate | |
2530 | .\" about proper handling of /proc/pid/fd. Arguably that one might belong | |
2531 | .\" back in the _ATTACH camp. | |
2532 | .\" | |
ace93363 MK |
2533 | .PP |
2534 | Since Linux 4.5, | |
2535 | .\" commit caaee6234d05a58c5b4d05e7bf766131b810a657 | |
611d3ac4 | 2536 | the above access mode checks are combined (ORed) with |
ace93363 MK |
2537 | one of the following modifiers: |
2538 | .TP | |
2539 | .B PTRACE_MODE_FSCREDS | |
2540 | Use the caller's filesystem UID and GID (see | |
2541 | .BR credentials (7)) | |
2542 | or effective capabilities for LSM checks. | |
2543 | .TP | |
2544 | .B PTRACE_MODE_REALCREDS | |
2545 | Use the caller's real UID and GID or permitted capabilities for LSM checks. | |
2546 | This was effectively the default before Linux 4.5. | |
2547 | .PP | |
2548 | Because combining one of the credential modifiers with one of | |
2549 | the aforementioned access modes is typical, | |
2550 | some macros are defined in the kernel sources for the combinations: | |
2551 | .TP | |
2552 | .B PTRACE_MODE_READ_FSCREDS | |
2553 | Defined as | |
2554 | .BR "PTRACE_MODE_READ | PTRACE_MODE_FSCREDS" . | |
2555 | .TP | |
2556 | .B PTRACE_MODE_READ_REALCREDS | |
2557 | Defined as | |
2558 | .BR "PTRACE_MODE_READ | PTRACE_MODE_REALCREDS" . | |
2559 | .TP | |
2560 | .B PTRACE_MODE_ATTACH_FSCREDS | |
2561 | Defined as | |
2562 | .BR "PTRACE_MODE_ATTACH | PTRACE_MODE_FSCREDS" . | |
2563 | .TP | |
2564 | .B PTRACE_MODE_ATTACH_REALCREDS | |
2565 | Defined as | |
2566 | .BR "PTRACE_MODE_ATTACH | PTRACE_MODE_REALCREDS" . | |
ace93363 MK |
2567 | .PP |
2568 | One further modifier can be ORed with the access mode: | |
2569 | .TP | |
2570 | .BR PTRACE_MODE_NOAUDIT " (since Linux 3.3)" | |
2571 | .\" commit 69f594a38967f4540ce7a29b3fd214e68a8330bd | |
2572 | .\" Just for /proc/pid/stat | |
2573 | Don't audit this access mode check. | |
3cd161fe SS |
2574 | This modifier is employed for ptrace access mode checks |
2575 | (such as checks when reading | |
1ae6b2c7 | 2576 | .IR /proc/ pid /stat ) |
3cd161fe SS |
2577 | that merely cause the output to be filtered or sanitized, |
2578 | rather than causing an error to be returned to the caller. | |
2579 | In these cases, accessing the file is not a security violation and | |
2580 | there is no reason to generate a security audit record. | |
2581 | This modifier suppresses the generation of | |
2582 | such an audit record for the particular access check. | |
ace93363 | 2583 | .PP |
edb73684 | 2584 | Note that all of the |
1ae6b2c7 | 2585 | .B PTRACE_MODE_* |
edb73684 MK |
2586 | constants described in this subsection are kernel-internal, |
2587 | and not visible to user space. | |
2588 | The constant names are mentioned here in order to label the various kinds of | |
2589 | ptrace access mode checks that are performed for various system calls | |
2590 | and accesses to various pseudofiles (e.g., under | |
2591 | .IR /proc ). | |
32245813 | 2592 | These names are used in other manual pages to provide a simple |
edb73684 | 2593 | shorthand for labeling the different kernel checks. |
efeece04 | 2594 | .PP |
ace93363 MK |
2595 | The algorithm employed for ptrace access mode checking determines whether |
2596 | the calling process is allowed to perform the corresponding action | |
a330bffa MK |
2597 | on the target process. |
2598 | (In the case of opening | |
1ae6b2c7 | 2599 | .IR /proc/ pid |
a330bffa MK |
2600 | files, the "calling process" is the one opening the file, |
2601 | and the process with the corresponding PID is the "target process".) | |
2602 | The algorithm is as follows: | |
9edaeefb | 2603 | .IP 1. 3 |
ace93363 MK |
2604 | If the calling thread and the target thread are in the same |
2605 | thread group, access is always allowed. | |
2606 | .IP 2. | |
2607 | If the access mode specifies | |
2608 | .BR PTRACE_MODE_FSCREDS , | |
78f07865 MK |
2609 | then, for the check in the next step, |
2610 | employ the caller's filesystem UID and GID. | |
2611 | (As noted in | |
2612 | .BR credentials (7), | |
2613 | the filesystem UID and GID almost always have the same values | |
2614 | as the corresponding effective IDs.) | |
efeece04 | 2615 | .IP |
78f07865 | 2616 | Otherwise, the access mode specifies |
ace93363 | 2617 | .BR PTRACE_MODE_REALCREDS , |
78f07865 MK |
2618 | so use the caller's real UID and GID for the checks in the next step. |
2619 | (Most APIs that check the caller's UID and GID use the effective IDs. | |
2620 | For historical reasons, the | |
1ae6b2c7 | 2621 | .B PTRACE_MODE_REALCREDS |
78f07865 | 2622 | check uses the real IDs instead.) |
ace93363 MK |
2623 | .IP 3. |
2624 | Deny access if | |
2625 | .I neither | |
2626 | of the following is true: | |
2627 | .RS | |
2628 | .IP \(bu 2 | |
2629 | The real, effective, and saved-set user IDs of the target | |
2630 | match the caller's user ID, | |
1ae6b2c7 | 2631 | .I and |
ace93363 MK |
2632 | the real, effective, and saved-set group IDs of the target |
2633 | match the caller's group ID. | |
2634 | .IP \(bu | |
2635 | The caller has the | |
2636 | .B CAP_SYS_PTRACE | |
0647331a | 2637 | capability in the user namespace of the target. |
ace93363 MK |
2638 | .RE |
2639 | .IP 4. | |
2640 | Deny access if the target process "dumpable" attribute has a value other than 1 | |
2641 | .RB ( SUID_DUMP_USER ; | |
2642 | see the discussion of | |
1ae6b2c7 | 2643 | .B PR_SET_DUMPABLE |
ace93363 MK |
2644 | in |
2645 | .BR prctl (2)), | |
2646 | and the caller does not have the | |
1ae6b2c7 | 2647 | .B CAP_SYS_PTRACE |
ace93363 MK |
2648 | capability in the user namespace of the target process. |
2649 | .IP 5. | |
2650 | The kernel LSM | |
2651 | .IR security_ptrace_access_check () | |
2652 | interface is invoked to see if ptrace access is permitted. | |
b0459842 | 2653 | The results depend on the LSM(s). |
611d3ac4 | 2654 | The implementation of this interface in the commoncap LSM performs |
ace93363 MK |
2655 | the following steps: |
2656 | .\" (in cap_ptrace_access_check()): | |
2657 | .RS | |
2658 | .IP a) 3 | |
2659 | If the access mode includes | |
2660 | .BR PTRACE_MODE_FSCREDS , | |
2661 | then use the caller's | |
2662 | .I effective | |
2663 | capability set | |
2664 | in the following check; | |
2665 | otherwise (the access mode specifies | |
2666 | .BR PTRACE_MODE_REALCREDS , | |
2667 | so) use the caller's | |
2668 | .I permitted | |
2669 | capability set. | |
2670 | .IP b) | |
2671 | Deny access if | |
2672 | .I neither | |
2673 | of the following is true: | |
2674 | .RS | |
2675 | .IP \(bu 2 | |
0647331a | 2676 | The caller and the target process are in the same user namespace, |
173eb06c | 2677 | and the caller's capabilities are a superset of the target process's |
ace93363 MK |
2678 | .I permitted |
2679 | capabilities. | |
2680 | .IP \(bu | |
2681 | The caller has the | |
2682 | .B CAP_SYS_PTRACE | |
2683 | capability in the target process's user namespace. | |
2684 | .RE | |
2685 | .IP | |
611d3ac4 | 2686 | Note that the commoncap LSM does not distinguish between |
ace93363 MK |
2687 | .B PTRACE_MODE_READ |
2688 | and | |
2689 | .BR PTRACE_MODE_ATTACH . | |
2690 | .RE | |
2691 | .IP 6. | |
2692 | If access has not been denied by any of the preceding steps, | |
2693 | then access is allowed. | |
2694 | .\" | |
2695 | .\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" | |
2696 | .\" | |
4978c606 | 2697 | .SS /proc/sys/kernel/yama/ptrace_scope |
e5323616 MK |
2698 | On systems with the Yama Linux Security Module (LSM) installed |
2699 | (i.e., the kernel was configured with | |
2700 | .BR CONFIG_SECURITY_YAMA ), | |
2701 | the | |
4978c606 | 2702 | .I /proc/sys/kernel/yama/ptrace_scope |
94b0464c | 2703 | file (available since Linux 3.4) |
4978c606 MK |
2704 | .\" commit 2d514487faf188938a4ee4fb3464eeecfbdcf8eb |
2705 | can be used to restrict the ability to trace a process with | |
bf7bc8b8 | 2706 | .BR ptrace () |
4978c606 MK |
2707 | (and thus also the ability to use tools such as |
2708 | .BR strace (1) | |
2709 | and | |
2710 | .BR gdb (1)). | |
2711 | The goal of such restrictions is to prevent attack escalation whereby | |
2712 | a compromised process can ptrace-attach to other sensitive processes | |
2713 | (e.g., a GPG agent or an SSH session) owned by the user in order | |
028b5760 MK |
2714 | to gain additional credentials that may exist in memory |
2715 | and thus expand the scope of the attack. | |
efeece04 | 2716 | .PP |
e5323616 MK |
2717 | More precisely, the Yama LSM limits two types of operations: |
2718 | .IP * 3 | |
2719 | Any operation that performs a ptrace access mode | |
1ae6b2c7 | 2720 | .B PTRACE_MODE_ATTACH |
e5323616 MK |
2721 | check\(emfor example, |
2722 | .BR ptrace () | |
2723 | .BR PTRACE_ATTACH . | |
2724 | (See the "Ptrace access mode checking" discussion above.) | |
e5323616 MK |
2725 | .IP * |
2726 | .BR ptrace () | |
2727 | .BR PTRACE_TRACEME . | |
2728 | .PP | |
2729 | A process that has the | |
4978c606 | 2730 | .B CAP_SYS_PTRACE |
e5323616 | 2731 | capability can update the |
1ae6b2c7 | 2732 | .I /proc/sys/kernel/yama/ptrace_scope |
e5323616 | 2733 | file with one of the following values: |
4978c606 MK |
2734 | .TP |
2735 | 0 ("classic ptrace permissions") | |
e5323616 | 2736 | No additional restrictions on operations that perform |
1ae6b2c7 | 2737 | .B PTRACE_MODE_ATTACH |
e5323616 | 2738 | checks (beyond those imposed by the commoncap and other LSMs). |
efeece04 | 2739 | .IP |
4978c606 | 2740 | The use of |
1ae6b2c7 | 2741 | .B PTRACE_TRACEME |
4978c606 MK |
2742 | is unchanged. |
2743 | .TP | |
e5323616 MK |
2744 | 1 ("restricted ptrace") [default value] |
2745 | When performing an operation that requires a | |
1ae6b2c7 | 2746 | .B PTRACE_MODE_ATTACH |
d5765e27 MK |
2747 | check, the calling process must either have the |
2748 | .B CAP_SYS_PTRACE | |
2749 | capability in the user namespace of the target process or | |
e48ed83a | 2750 | it must have a predefined relationship with the target process. |
4978c606 | 2751 | By default, |
e5323616 | 2752 | the predefined relationship is that the target process |
028b5760 | 2753 | must be a descendant of the caller. |
efeece04 | 2754 | .IP |
e5323616 | 2755 | A target process can employ the |
4978c606 MK |
2756 | .BR prctl (2) |
2757 | .B PR_SET_PTRACER | |
028b5760 | 2758 | operation to declare an additional PID that is allowed to perform |
1ae6b2c7 | 2759 | .B PTRACE_MODE_ATTACH |
e5323616 MK |
2760 | operations on the target. |
2761 | See the kernel source file | |
1ae6b2c7 | 2762 | .I Documentation/admin\-guide/LSM/Yama.rst |
6744a500 ES |
2763 | .\" commit 90bb766440f2147486a2acc3e793d7b8348b0c22 |
2764 | (or | |
1ae6b2c7 | 2765 | .I Documentation/security/Yama.txt |
6744a500 | 2766 | before Linux 4.13) |
e5323616 | 2767 | for further details. |
efeece04 | 2768 | .IP |
4978c606 | 2769 | The use of |
1ae6b2c7 | 2770 | .B PTRACE_TRACEME |
4978c606 MK |
2771 | is unchanged. |
2772 | .TP | |
2773 | 2 ("admin-only attach") | |
2774 | Only processes with the | |
2775 | .B CAP_SYS_PTRACE | |
d5765e27 | 2776 | capability in the user namespace of the target process may perform |
1ae6b2c7 | 2777 | .B PTRACE_MODE_ATTACH |
e5323616 | 2778 | operations or trace children that employ |
4978c606 MK |
2779 | .BR PTRACE_TRACEME . |
2780 | .TP | |
2781 | 3 ("no attach") | |
e5323616 | 2782 | No process may perform |
1ae6b2c7 | 2783 | .B PTRACE_MODE_ATTACH |
e5323616 | 2784 | operations or trace children that employ |
4978c606 | 2785 | .BR PTRACE_TRACEME . |
efeece04 | 2786 | .IP |
4978c606 | 2787 | Once this value has been written to the file, it cannot be changed. |
d5765e27 MK |
2788 | .PP |
2789 | With respect to values 1 and 2, | |
028b5760 MK |
2790 | note that creating a new user namespace effectively removes the |
2791 | protection offered by Yama. | |
2792 | This is because a process in the parent user namespace whose effective | |
2793 | UID matches the UID of the creator of a child namespace | |
2794 | has all capabilities (including | |
2795 | .BR CAP_SYS_PTRACE ) | |
2796 | when performing operations within the child user namespace | |
2797 | (and further-removed descendants of that namespace). | |
2798 | Consequently, when a process tries to use user namespaces to sandbox itself, | |
2799 | it inadvertently weakens the protections offered by the Yama LSM. | |
4978c606 | 2800 | .\" |
e5323616 MK |
2801 | .\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" |
2802 | .\" | |
0722a578 | 2803 | .SS C library/kernel differences |
53a99749 MK |
2804 | At the system call level, the |
2805 | .BR PTRACE_PEEKTEXT , | |
2806 | .BR PTRACE_PEEKDATA , | |
2807 | and | |
1ae6b2c7 | 2808 | .B PTRACE_PEEKUSER |
53a99749 MK |
2809 | requests have a different API: they store the result |
2810 | at the address specified by the | |
2811 | .I data | |
2812 | parameter, and the return value is the error flag. | |
2813 | The glibc wrapper function provides the API given in DESCRIPTION above, | |
2814 | with the result being returned via the function return value. | |
a1d5f77c | 2815 | .SH BUGS |
8bd58774 | 2816 | On hosts with 2.6 kernel headers, |
0daa9e92 | 2817 | .B PTRACE_SETOPTIONS |
181f997f MK |
2818 | is declared with a different value than the one for 2.4. |
2819 | This leads to applications compiled with 2.6 kernel | |
a1d5f77c | 2820 | headers failing when run on 2.4 kernels. |
8bd58774 | 2821 | This can be worked around by redefining |
0daa9e92 | 2822 | .B PTRACE_SETOPTIONS |
8bd58774 MK |
2823 | to |
2824 | .BR PTRACE_OLDSETOPTIONS , | |
2825 | if that is defined. | |
dd3568a1 | 2826 | .PP |
181f997f | 2827 | Group-stop notifications are sent to the tracer, but not to real parent. |
4d12a715 | 2828 | Last confirmed on 2.6.38.6. |
dd3568a1 | 2829 | .PP |
181f997f MK |
2830 | If a thread group leader is traced and exits by calling |
2831 | .BR _exit (2), | |
8898a252 MK |
2832 | .\" Note from Denys Vlasenko: |
2833 | .\" Here "exits" means any kind of death - _exit, exit_group, | |
2834 | .\" signal death. Signal death and exit_group cases are trivial, | |
2835 | .\" though: since signal death and exit_group kill all other threads | |
2836 | .\" too, "until all other threads exit" thing happens rather soon | |
2837 | .\" in these cases. Therefore, only _exit presents observably | |
2838 | .\" puzzling behavior to ptrace users: thread leader _exit's, | |
2839 | .\" but WIFEXITED isn't reported! We are trying to explain here | |
2840 | .\" why it is so. | |
181f997f MK |
2841 | a |
2842 | .B PTRACE_EVENT_EXIT | |
2843 | stop will happen for it (if requested), but the subsequent | |
2844 | .B WIFEXITED | |
2845 | notification will not be delivered until all other threads exit. | |
2846 | As explained above, if one of other threads calls | |
2847 | .BR execve (2), | |
2848 | the death of the thread group leader will | |
2849 | .I never | |
2850 | be reported. | |
2851 | If the execed thread is not traced by this tracer, | |
2852 | the tracer will never know that | |
2853 | .BR execve (2) | |
4d12a715 | 2854 | happened. |
181f997f MK |
2855 | One possible workaround is to |
2856 | .B PTRACE_DETACH | |
2857 | the thread group leader instead of restarting it in this case. | |
2858 | Last confirmed on 2.6.38.6. | |
bea08fec | 2859 | .\" FIXME . need to test/verify this scenario |
dd3568a1 | 2860 | .PP |
181f997f MK |
2861 | A |
2862 | .B SIGKILL | |
2863 | signal may still cause a | |
2864 | .B PTRACE_EVENT_EXIT | |
2865 | stop before actual signal death. | |
2866 | This may be changed in the future; | |
2867 | .B SIGKILL | |
2868 | is meant to always immediately kill tasks even under ptrace. | |
55bd9495 | 2869 | Last confirmed on Linux 3.13. |
dd3568a1 | 2870 | .PP |
a17e05c5 | 2871 | Some system calls return with |
f098951d | 2872 | .B EINTR |
a17e05c5 MK |
2873 | if a signal was sent to a tracee, but delivery was suppressed by the tracer. |
2874 | (This is very typical operation: it is usually | |
f098951d | 2875 | done by debuggers on every attach, in order to not introduce |
a17e05c5 MK |
2876 | a bogus |
2877 | .BR SIGSTOP ). | |
2878 | As of Linux 3.2.9, the following system calls are affected | |
2879 | (this list is likely incomplete): | |
f098951d | 2880 | .BR epoll_wait (2), |
a17e05c5 | 2881 | and |
f098951d | 2882 | .BR read (2) |
a17e05c5 MK |
2883 | from an |
2884 | .BR inotify (7) | |
2885 | file descriptor. | |
ca302d0e DV |
2886 | The usual symptom of this bug is that when you attach to |
2887 | a quiescent process with the command | |
efeece04 | 2888 | .PP |
408731d4 MK |
2889 | .in +4n |
2890 | .EX | |
d064d41a | 2891 | strace \-p <process\-ID> |
408731d4 MK |
2892 | .EE |
2893 | .in | |
efeece04 | 2894 | .PP |
ca302d0e DV |
2895 | then, instead of the usual |
2896 | and expected one-line output such as | |
408731d4 MK |
2897 | .PP |
2898 | .in +4n | |
2899 | .EX | |
2900 | restart_syscall(<... resuming interrupted call ...>_ | |
2901 | .EE | |
2902 | .in | |
2903 | .PP | |
ca302d0e | 2904 | or |
408731d4 MK |
2905 | .PP |
2906 | .in +4n | |
2907 | .EX | |
2908 | select(6, [5], NULL, [5], NULL_ | |
2909 | .EE | |
2910 | .in | |
2911 | .PP | |
ca302d0e DV |
2912 | ('_' denotes the cursor position), you observe more than one line. |
2913 | For example: | |
408731d4 MK |
2914 | .PP |
2915 | .in +4n | |
2916 | .EX | |
ca302d0e DV |
2917 | clock_gettime(CLOCK_MONOTONIC, {15370, 690928118}) = 0 |
2918 | epoll_wait(4,_ | |
408731d4 MK |
2919 | .EE |
2920 | .in | |
2921 | .PP | |
ca302d0e DV |
2922 | What is not visible here is that the process was blocked in |
2923 | .BR epoll_wait (2) | |
2924 | before | |
2925 | .BR strace (1) | |
2926 | has attached to it. | |
2927 | Attaching caused | |
2928 | .BR epoll_wait (2) | |
7fac88a9 | 2929 | to return to user space with the error |
ca302d0e DV |
2930 | .BR EINTR . |
2931 | In this particular case, the program reacted to | |
2932 | .B EINTR | |
b0b1d9b5 | 2933 | by checking the current time, and then executing |
ca302d0e DV |
2934 | .BR epoll_wait (2) |
2935 | again. | |
2936 | (Programs which do not expect such "stray" | |
1ae6b2c7 | 2937 | .B EINTR |
ca302d0e DV |
2938 | errors may behave in an unintended way upon an |
2939 | .BR strace (1) | |
2940 | attach.) | |
c62b9453 JH |
2941 | .PP |
2942 | Contrary to the normal rules, the glibc wrapper for | |
2943 | .BR ptrace () | |
2944 | can set | |
2945 | .I errno | |
2946 | to zero. | |
47297adb | 2947 | .SH SEE ALSO |
fea681da | 2948 | .BR gdb (1), |
53506ea9 | 2949 | .BR ltrace (1), |
fea681da | 2950 | .BR strace (1), |
181f997f | 2951 | .BR clone (2), |
fea681da MK |
2952 | .BR execve (2), |
2953 | .BR fork (2), | |
181f997f | 2954 | .BR gettid (2), |
d901e325 | 2955 | .BR prctl (2), |
3b4a59c4 | 2956 | .BR seccomp (2), |
181f997f MK |
2957 | .BR sigaction (2), |
2958 | .BR tgkill (2), | |
2959 | .BR vfork (2), | |
2960 | .BR waitpid (2), | |
fea681da | 2961 | .BR exec (3), |
181f997f MK |
2962 | .BR capabilities (7), |
2963 | .BR signal (7) |