1ptrace(2)                     System Calls Manual                    ptrace(2)
2
3
4

NAME

6       ptrace - process trace
7

LIBRARY

9       Standard C library (libc, -lc)
10

SYNOPSIS

12       #include <sys/ptrace.h>
13
14       long ptrace(enum __ptrace_request request, pid_t pid,
15                   void *addr, void *data);
16

DESCRIPTION

18       The  ptrace()  system  call  provides a means by which one process (the
19       "tracer") may observe and control the execution of another process (the
20       "tracee"),  and  examine  and change the tracee's memory and registers.
21       It is primarily used to implement breakpoint debugging and system  call
22       tracing.
23
24       A tracee first needs to be attached to the tracer.  Attachment and sub‐
25       sequent commands are per thread:  in  a  multithreaded  process,  every
26       thread  can  be  individually  attached  to  a  (potentially different)
27       tracer, or  left  not  attached  and  thus  not  debugged.   Therefore,
28       "tracee" always means "(one) thread", never "a (possibly multithreaded)
29       process".  Ptrace commands are always sent to a specific tracee using a
30       call of the form
31
32           ptrace(PTRACE_foo, pid, ...)
33
34       where pid is the thread ID of the corresponding Linux thread.
35
36       (Note that in this page, a "multithreaded process" means a thread group
37       consisting of threads created using the clone(2) CLONE_THREAD flag.)
38
39       A process can initiate a trace by calling fork(2) and  having  the  re‐
40       sulting  child  do  a  PTRACE_TRACEME,  followed  (typically) by an ex‐
41       ecve(2).  Alternatively,  one  process  may  commence  tracing  another
42       process using PTRACE_ATTACH or PTRACE_SEIZE.
43
44       While  being  traced, the tracee will stop each time a signal is deliv‐
45       ered, even if the signal is being ignored.  (An exception  is  SIGKILL,
46       which  has  its usual effect.)  The tracer will be notified at its next
47       call to waitpid(2) (or one of the related "wait"  system  calls);  that
48       call  will  return a status value containing information that indicates
49       the cause of the stop in the tracee.  While the tracee is stopped,  the
50       tracer  can  use  various  ptrace  requests  to  inspect and modify the
51       tracee.  The tracer then causes the tracee to continue, optionally  ig‐
52       noring  the delivered signal (or even delivering a different signal in‐
53       stead).
54
55       If the PTRACE_O_TRACEEXEC option is not in effect, all successful calls
56       to  execve(2)  by the traced process will cause it to be sent a SIGTRAP
57       signal, giving the parent a chance to gain control before the new  pro‐
58       gram begins execution.
59
60       When  the  tracer  is finished tracing, it can cause the tracee to con‐
61       tinue executing in a normal, untraced mode via PTRACE_DETACH.
62
63       The value of request determines the action to be performed:
64
65       PTRACE_TRACEME
66              Indicate that this process is to be traced  by  its  parent.   A
67              process probably shouldn't make this request if its parent isn't
68              expecting to trace it.  (pid, addr, and data are ignored.)
69
70              The PTRACE_TRACEME request is used only by the tracee;  the  re‐
71              maining  requests are used only by the tracer.  In the following
72              requests, pid specifies the thread ID of the tracee to be  acted
73              on.    For  requests  other  than  PTRACE_ATTACH,  PTRACE_SEIZE,
74              PTRACE_INTERRUPT, and PTRACE_KILL, the tracee must be stopped.
75
76       PTRACE_PEEKTEXT, PTRACE_PEEKDATA
77              Read a word at the address addr in the tracee's memory,  return‐
78              ing the word as the result of the ptrace() call.  Linux does not
79              have separate text and data address spaces,  so  these  two  re‐
80              quests  are  currently  equivalent.   (data  is ignored; but see
81              NOTES.)
82
83       PTRACE_PEEKUSER
84              Read a word at offset addr in  the  tracee's  USER  area,  which
85              holds the registers and other information about the process (see
86              <sys/user.h>).  The word  is  returned  as  the  result  of  the
87              ptrace()  call.   Typically,  the  offset  must be word-aligned,
88              though this might vary by architecture.  See  NOTES.   (data  is
89              ignored; but see NOTES.)
90
91       PTRACE_POKETEXT, PTRACE_POKEDATA
92              Copy  the  word data to the address addr in the tracee's memory.
93              As for PTRACE_PEEKTEXT and PTRACE_PEEKDATA, these  two  requests
94              are currently equivalent.
95
96       PTRACE_POKEUSER
97              Copy the word data to offset addr in the tracee's USER area.  As
98              for PTRACE_PEEKUSER, the offset must typically be  word-aligned.
99              In order to maintain the integrity of the kernel, some modifica‐
100              tions to the USER area are disallowed.
101
102       PTRACE_GETREGS, PTRACE_GETFPREGS
103              Copy the tracee's general-purpose or  floating-point  registers,
104              respectively,   to   the   address  data  in  the  tracer.   See
105              <sys/user.h> for information on the format of this data.   (addr
106              is  ignored.)   Note that SPARC systems have the meaning of data
107              and addr reversed; that is, data is ignored  and  the  registers
108              are copied to the address addr.  PTRACE_GETREGS and PTRACE_GETF‐
109              PREGS are not present on all architectures.
110
111       PTRACE_GETREGSET (since Linux 2.6.34)
112              Read the tracee's registers.  addr specifies,  in  an  architec‐
113              ture-dependent way, the type of registers to be read.  NT_PRSTA‐
114              TUS (with numerical value 1) usually results in reading of  gen‐
115              eral-purpose  registers.  If the CPU has, for example, floating-
116              point and/or vector registers, they can be retrieved by  setting
117              addr  to  the  corresponding  NT_foo constant.  data points to a
118              struct iovec, which describes the destination buffer's  location
119              and  length.  On return, the kernel modifies iov.len to indicate
120              the actual number of bytes returned.
121
122       PTRACE_SETREGS, PTRACE_SETFPREGS
123              Modify the tracee's general-purpose or floating-point registers,
124              respectively,  from  the  address  data  in  the tracer.  As for
125              PTRACE_POKEUSER, some general-purpose register modifications may
126              be disallowed.  (addr is ignored.)  Note that SPARC systems have
127              the meaning of data and addr reversed; that is, data is  ignored
128              and  the registers are copied from the address addr.  PTRACE_SE‐
129              TREGS and PTRACE_SETFPREGS are not present on all architectures.
130
131       PTRACE_SETREGSET (since Linux 2.6.34)
132              Modify the tracee's registers.  The meaning of addr and data  is
133              analogous to PTRACE_GETREGSET.
134
135       PTRACE_GETSIGINFO (since Linux 2.3.99-pre6)
136              Retrieve  information  about  the  signal  that caused the stop.
137              Copy a siginfo_t structure (see sigaction(2)) from the tracee to
138              the address data in the tracer.  (addr is ignored.)
139
140       PTRACE_SETSIGINFO (since Linux 2.3.99-pre6)
141              Set  signal information: copy a siginfo_t structure from the ad‐
142              dress data in the tracer to the tracee.  This will  affect  only
143              signals  that would normally be delivered to the tracee and were
144              caught by the tracer.  It may be difficult to tell these  normal
145              signals  from  synthetic  signals  generated by ptrace() itself.
146              (addr is ignored.)
147
148       PTRACE_PEEKSIGINFO (since Linux 3.10)
149              Retrieve siginfo_t structures without removing  signals  from  a
150              queue.   addr points to a ptrace_peeksiginfo_args structure that
151              specifies the ordinal position from  which  copying  of  signals
152              should  start,  and  the  number  of signals to copy.  siginfo_t
153              structures are copied into the buffer pointed to by  data.   The
154              return  value  contains the number of copied signals (zero indi‐
155              cates that there is no signal corresponding to the specified or‐
156              dinal  position).   Within  the returned siginfo structures, the
157              si_code field includes information (__SI_CHLD, __SI_FAULT, etc.)
158              that are not otherwise exposed to user space.
159
160           struct ptrace_peeksiginfo_args {
161               u64 off;    /* Ordinal position in queue at which
162                              to start copying signals */
163               u32 flags;  /* PTRACE_PEEKSIGINFO_SHARED or 0 */
164               s32 nr;     /* Number of signals to copy */
165           };
166
167              Currently,  there  is  only one flag, PTRACE_PEEKSIGINFO_SHARED,
168              for dumping signals from the process-wide signal queue.  If this
169              flag  is  not set, signals are read from the per-thread queue of
170              the specified thread.
171
172       PTRACE_GETSIGMASK (since Linux 3.11)
173              Place a copy of the mask of blocked signals (see sigprocmask(2))
174              in the buffer pointed to by data, which should be a pointer to a
175              buffer of type sigset_t.  The addr argument contains the size of
176              the buffer pointed to by data (i.e., sizeof(sigset_t)).
177
178       PTRACE_SETSIGMASK (since Linux 3.11)
179              Change  the  mask of blocked signals (see sigprocmask(2)) to the
180              value specified in the buffer pointed to by data,  which  should
181              be  a  pointer  to a buffer of type sigset_t.  The addr argument
182              contains the size of  the  buffer  pointed  to  by  data  (i.e.,
183              sizeof(sigset_t)).
184
185       PTRACE_SETOPTIONS (since Linux 2.4.6; see BUGS for caveats)
186              Set  ptrace  options from data.  (addr is ignored.)  data is in‐
187              terpreted as a bit mask of options, which are specified  by  the
188              following flags:
189
190              PTRACE_O_EXITKILL (since Linux 3.8)
191                     Send  a SIGKILL signal to the tracee if the tracer exits.
192                     This option is useful for ptrace jailers that want to en‐
193                     sure that tracees can never escape the tracer's control.
194
195              PTRACE_O_TRACECLONE (since Linux 2.5.46)
196                     Stop  the  tracee  at the next clone(2) and automatically
197                     start tracing the newly cloned process, which will  start
198                     with  a SIGSTOP, or PTRACE_EVENT_STOP if PTRACE_SEIZE was
199                     used.  A waitpid(2) by the tracer will  return  a  status
200                     value such that
201
202                       status>>8 == (SIGTRAP | (PTRACE_EVENT_CLONE<<8))
203
204                     The  PID  of  the  new  process  can  be  retrieved  with
205                     PTRACE_GETEVENTMSG.
206
207                     This option may not catch clone(2) calls  in  all  cases.
208                     If  the  tracee calls clone(2) with the CLONE_VFORK flag,
209                     PTRACE_EVENT_VFORK   will   be   delivered   instead   if
210                     PTRACE_O_TRACEVFORK is set; otherwise if the tracee calls
211                     clone(2)  with  the   exit   signal   set   to   SIGCHLD,
212                     PTRACE_EVENT_FORK will be delivered if PTRACE_O_TRACEFORK
213                     is set.
214
215              PTRACE_O_TRACEEXEC (since Linux 2.5.46)
216                     Stop the tracee at the next execve(2).  A  waitpid(2)  by
217                     the tracer will return a status value such that
218
219                       status>>8 == (SIGTRAP | (PTRACE_EVENT_EXEC<<8))
220
221                     If  the  execing thread is not a thread group leader, the
222                     thread ID is reset to thread  group  leader's  ID  before
223                     this  stop.  Since Linux 3.0, the former thread ID can be
224                     retrieved with PTRACE_GETEVENTMSG.
225
226              PTRACE_O_TRACEEXIT (since Linux 2.5.60)
227                     Stop the tracee at exit.  A waitpid(2) by the tracer will
228                     return a status value such that
229
230                       status>>8 == (SIGTRAP | (PTRACE_EVENT_EXIT<<8))
231
232                     The   tracee's   exit   status   can  be  retrieved  with
233                     PTRACE_GETEVENTMSG.
234
235                     The tracee is stopped early  during  process  exit,  when
236                     registers are still available, allowing the tracer to see
237                     where the exit occurred, whereas the normal exit  notifi‐
238                     cation  is  done  after  the process is finished exiting.
239                     Even though context is available, the tracer cannot  pre‐
240                     vent the exit from happening at this point.
241
242              PTRACE_O_TRACEFORK (since Linux 2.5.46)
243                     Stop  the  tracee  at  the next fork(2) and automatically
244                     start tracing the newly forked process, which will  start
245                     with  a SIGSTOP, or PTRACE_EVENT_STOP if PTRACE_SEIZE was
246                     used.  A waitpid(2) by the tracer will  return  a  status
247                     value such that
248
249                       status>>8 == (SIGTRAP | (PTRACE_EVENT_FORK<<8))
250
251                     The  PID  of  the  new  process  can  be  retrieved  with
252                     PTRACE_GETEVENTMSG.
253
254              PTRACE_O_TRACESYSGOOD (since Linux 2.4.6)
255                     When delivering system call traps, set bit 7 in the  sig‐
256                     nal  number  (i.e., deliver SIGTRAP|0x80).  This makes it
257                     easy for the tracer  to  distinguish  normal  traps  from
258                     those caused by a system call.
259
260              PTRACE_O_TRACEVFORK (since Linux 2.5.46)
261                     Stop  the  tracee  at the next vfork(2) and automatically
262                     start tracing the newly vforked process, which will start
263                     with  a SIGSTOP, or PTRACE_EVENT_STOP if PTRACE_SEIZE was
264                     used.  A waitpid(2) by the tracer will  return  a  status
265                     value such that
266
267                       status>>8 == (SIGTRAP | (PTRACE_EVENT_VFORK<<8))
268
269                     The  PID  of  the  new  process  can  be  retrieved  with
270                     PTRACE_GETEVENTMSG.
271
272              PTRACE_O_TRACEVFORKDONE (since Linux 2.5.60)
273                     Stop the tracee at the completion of the  next  vfork(2).
274                     A  waitpid(2)  by  the  tracer will return a status value
275                     such that
276
277                       status>>8 == (SIGTRAP | (PTRACE_EVENT_VFORK_DONE<<8))
278
279                     The PID of the new process can (since  Linux  2.6.18)  be
280                     retrieved with PTRACE_GETEVENTMSG.
281
282              PTRACE_O_TRACESECCOMP (since Linux 3.5)
283                     Stop  the tracee when a seccomp(2) SECCOMP_RET_TRACE rule
284                     is triggered.  A waitpid(2) by the tracer will  return  a
285                     status value such that
286
287                       status>>8 == (SIGTRAP | (PTRACE_EVENT_SECCOMP<<8))
288
289                     While this triggers a PTRACE_EVENT stop, it is similar to
290                     a syscall-enter-stop.   For  details,  see  the  note  on
291                     PTRACE_EVENT_SECCOMP  below.   The  seccomp event message
292                     data (from the SECCOMP_RET_DATA portion  of  the  seccomp
293                     filter rule) can be retrieved with PTRACE_GETEVENTMSG.
294
295              PTRACE_O_SUSPEND_SECCOMP (since Linux 4.3)
296                     Suspend  the  tracee's seccomp protections.  This applies
297                     regardless of mode, and can be used when the  tracee  has
298                     not  yet installed seccomp filters.  That is, a valid use
299                     case is to suspend a tracee's seccomp protections  before
300                     they  are installed by the tracee, let the tracee install
301                     the filters, and then clear this flag  when  the  filters
302                     should be resumed.  Setting this option requires that the
303                     tracer have the CAP_SYS_ADMIN capability,  not  have  any
304                     seccomp protections installed, and not have PTRACE_O_SUS‐
305                     PEND_SECCOMP set on itself.
306
307       PTRACE_GETEVENTMSG (since Linux 2.5.46)
308              Retrieve a message (as an unsigned long) about the ptrace  event
309              that  just  happened,  placing  it  at  the  address data in the
310              tracer.  For PTRACE_EVENT_EXIT, this is the tracee's  exit  sta‐
311              tus.        For      PTRACE_EVENT_FORK,      PTRACE_EVENT_VFORK,
312              PTRACE_EVENT_VFORK_DONE, and PTRACE_EVENT_CLONE, this is the PID
313              of  the new process.  For PTRACE_EVENT_SECCOMP, this is the sec‐
314              comp(2) filter's SECCOMP_RET_DATA associated with the  triggered
315              rule.  (addr is ignored.)
316
317       PTRACE_CONT
318              Restart  the  stopped tracee process.  If data is nonzero, it is
319              interpreted as the number of a signal to  be  delivered  to  the
320              tracee;  otherwise,  no signal is delivered.  Thus, for example,
321              the tracer can control whether a signal sent to  the  tracee  is
322              delivered or not.  (addr is ignored.)
323
324       PTRACE_SYSCALL, PTRACE_SINGLESTEP
325              Restart  the  stopped tracee as for PTRACE_CONT, but arrange for
326              the tracee to be stopped at the next entry to  or  exit  from  a
327              system call, or after execution of a single instruction, respec‐
328              tively.  (The tracee will also, as usual, be  stopped  upon  re‐
329              ceipt  of  a signal.)  From the tracer's perspective, the tracee
330              will appear to have been stopped by receipt of a  SIGTRAP.   So,
331              for  PTRACE_SYSCALL, for example, the idea is to inspect the ar‐
332              guments to the system call at the first stop,  then  do  another
333              PTRACE_SYSCALL  and  inspect the return value of the system call
334              at the second  stop.   The  data  argument  is  treated  as  for
335              PTRACE_CONT.  (addr is ignored.)
336
337       PTRACE_SET_SYSCALL (since Linux 2.6.16)
338              When in syscall-enter-stop, change the number of the system call
339              that is about to be executed to the number specified in the data
340              argument.   The  addr argument is ignored.  This request is cur‐
341              rently supported only on arm (and arm64, though only  for  back‐
342              wards  compatibility),  but  most other architectures have other
343              means of accomplishing this (usually by  changing  the  register
344              that the userland code passed the system call number in).
345
346       PTRACE_SYSEMU, PTRACE_SYSEMU_SINGLESTEP (since Linux 2.6.14)
347              For PTRACE_SYSEMU, continue and stop on entry to the next system
348              call, which will not be  executed.   See  the  documentation  on
349              syscall-stops  below.  For PTRACE_SYSEMU_SINGLESTEP, do the same
350              but also singlestep if not a system call.  This call is used  by
351              programs  like  User  Mode  Linux  that  want to emulate all the
352              tracee's system calls.  The data  argument  is  treated  as  for
353              PTRACE_CONT.   The addr argument is ignored.  These requests are
354              currently supported only on x86.
355
356       PTRACE_LISTEN (since Linux 3.4)
357              Restart the stopped tracee, but prevent it from executing.   The
358              resulting  state of the tracee is similar to a process which has
359              been stopped by a SIGSTOP (or other stopping signal).   See  the
360              "group-stop" subsection for additional information.  PTRACE_LIS‐
361              TEN works only on tracees attached by PTRACE_SEIZE.
362
363       PTRACE_KILL
364              Send the tracee a SIGKILL to terminate it.  (addr and  data  are
365              ignored.)
366
367              This  operation  is  deprecated; do not use it!  Instead, send a
368              SIGKILL directly using kill(2) or tgkill(2).  The  problem  with
369              PTRACE_KILL  is  that it requires the tracee to be in signal-de‐
370              livery-stop, otherwise it may not work (i.e., may complete  suc‐
371              cessfully  but  won't  kill the tracee).  By contrast, sending a
372              SIGKILL directly has no such limitation.
373
374       PTRACE_INTERRUPT (since Linux 3.4)
375              Stop a tracee.  If the tracee is running or sleeping  in  kernel
376              space and PTRACE_SYSCALL is in effect, the system call is inter‐
377              rupted and syscall-exit-stop is reported.  (The interrupted sys‐
378              tem  call  is  restarted  when the tracee is restarted.)  If the
379              tracee was already stopped by a  signal  and  PTRACE_LISTEN  was
380              sent  to  it, the tracee stops with PTRACE_EVENT_STOP and WSTOP‐
381              SIG(status) returns the stop signal.  If any  other  ptrace-stop
382              is  generated at the same time (for example, if a signal is sent
383              to the tracee), this ptrace-stop happens.  If none of the  above
384              applies  (for  example, if the tracee is running in user space),
385              it stops with PTRACE_EVENT_STOP with  WSTOPSIG(status)  ==  SIG‐
386              TRAP.   PTRACE_INTERRUPT  only  works  on  tracees  attached  by
387              PTRACE_SEIZE.
388
389       PTRACE_ATTACH
390              Attach to the process specified in pid, making it  a  tracee  of
391              the calling process.  The tracee is sent a SIGSTOP, but will not
392              necessarily have stopped by the completion  of  this  call;  use
393              waitpid(2)  to  wait for the tracee to stop.  See the "Attaching
394              and detaching" subsection for additional information.  (addr and
395              data are ignored.)
396
397              Permission  to  perform  a PTRACE_ATTACH is governed by a ptrace
398              access mode PTRACE_MODE_ATTACH_REALCREDS check; see below.
399
400       PTRACE_SEIZE (since Linux 3.4)
401              Attach to the process specified in pid, making it  a  tracee  of
402              the  calling  process.   Unlike PTRACE_ATTACH, PTRACE_SEIZE does
403              not   stop   the   process.    Group-stops   are   reported   as
404              PTRACE_EVENT_STOP  and WSTOPSIG(status) returns the stop signal.
405              Automatically attached children stop with PTRACE_EVENT_STOP  and
406              WSTOPSIG(status)  returns SIGTRAP instead of having SIGSTOP sig‐
407              nal delivered to them.  execve(2) does not deliver an extra SIG‐
408              TRAP.   Only a PTRACE_SEIZEd process can accept PTRACE_INTERRUPT
409              and PTRACE_LISTEN commands.   The  "seized"  behavior  just  de‐
410              scribed is inherited by children that are automatically attached
411              using     PTRACE_O_TRACEFORK,      PTRACE_O_TRACEVFORK,      and
412              PTRACE_O_TRACECLONE.   addr  must  be zero.  data contains a bit
413              mask of ptrace options to activate immediately.
414
415              Permission to perform a PTRACE_SEIZE is governed by a ptrace ac‐
416              cess mode PTRACE_MODE_ATTACH_REALCREDS check; see below.
417
418       PTRACE_SECCOMP_GET_FILTER (since Linux 4.4)
419              This  operation  allows  the tracer to dump the tracee's classic
420              BPF filters.
421
422              addr is an integer specifying the index  of  the  filter  to  be
423              dumped.  The most recently installed filter has the index 0.  If
424              addr is greater than the number of installed filters, the opera‐
425              tion fails with the error ENOENT.
426
427              data  is  either a pointer to a struct sock_filter array that is
428              large enough to store the BPF program, or NULL if the program is
429              not to be stored.
430
431              Upon  success, the return value is the number of instructions in
432              the BPF program.  If data was NULL, then this return  value  can
433              be used to correctly size the struct sock_filter array passed in
434              a subsequent call.
435
436              This operation fails with the error EACCES if  the  caller  does
437              not  have  the  CAP_SYS_ADMIN  capability or if the caller is in
438              strict or filter seccomp mode.  If the  filter  referred  to  by
439              addr  is  not a classic BPF filter, the operation fails with the
440              error EMEDIUMTYPE.
441
442              This operation is available if the kernel  was  configured  with
443              both the CONFIG_SECCOMP_FILTER and the CONFIG_CHECKPOINT_RESTORE
444              options.
445
446       PTRACE_DETACH
447              Restart the stopped tracee as for PTRACE_CONT, but first  detach
448              from  it.  Under Linux, a tracee can be detached in this way re‐
449              gardless of which method was used to initiate tracing.  (addr is
450              ignored.)
451
452       PTRACE_GET_THREAD_AREA (since Linux 2.6.0)
453              This  operation  performs  a similar task to get_thread_area(2).
454              It reads the TLS entry in the GDT whose index is given in  addr,
455              placing a copy of the entry into the struct user_desc pointed to
456              by data.  (By contrast with get_thread_area(2), the entry_number
457              of the struct user_desc is ignored.)
458
459       PTRACE_SET_THREAD_AREA (since Linux 2.6.0)
460              This  operation  performs  a similar task to set_thread_area(2).
461              It sets the TLS entry in the GDT whose index is given  in  addr,
462              assigning  it  the data supplied in the struct user_desc pointed
463              to by data.   (By  contrast  with  set_thread_area(2),  the  en‐
464              try_number  of  the struct user_desc is ignored; in other words,
465              this ptrace operation can't be used to allocate a free  TLS  en‐
466              try.)
467
468       PTRACE_GET_SYSCALL_INFO (since Linux 5.3)
469              Retrieve information about the system call that caused the stop.
470              The information is placed into the buffer pointed  by  the  data
471              argument,  which  should be a pointer to a buffer of type struct
472              ptrace_syscall_info.  The addr argument contains the size of the
473              buffer  pointed  to  by  the  data argument (i.e., sizeof(struct
474              ptrace_syscall_info)).  The return value contains the number  of
475              bytes available to be written by the kernel.  If the size of the
476              data to be written by the kernel exceeds the size  specified  by
477              the addr argument, the output data is truncated.
478
479              The ptrace_syscall_info structure contains the following fields:
480
481                  struct ptrace_syscall_info {
482                      __u8 op;        /* Type of system call stop */
483                      __u32 arch;     /* AUDIT_ARCH_* value; see seccomp(2) */
484                      __u64 instruction_pointer; /* CPU instruction pointer */
485                      __u64 stack_pointer;    /* CPU stack pointer */
486                      union {
487                          struct {    /* op == PTRACE_SYSCALL_INFO_ENTRY */
488                              __u64 nr;       /* System call number */
489                              __u64 args[6];  /* System call arguments */
490                          } entry;
491                          struct {    /* op == PTRACE_SYSCALL_INFO_EXIT */
492                              __s64 rval;     /* System call return value */
493                              __u8 is_error;  /* System call error flag;
494                                                 Boolean: does rval contain
495                                                 an error value (-ERRCODE) or
496                                                 a nonerror return value? */
497                          } exit;
498                          struct {    /* op == PTRACE_SYSCALL_INFO_SECCOMP */
499                              __u64 nr;       /* System call number */
500                              __u64 args[6];  /* System call arguments */
501                              __u32 ret_data; /* SECCOMP_RET_DATA portion
502                                                 of SECCOMP_RET_TRACE
503                                                 return value */
504                          } seccomp;
505                      };
506                  };
507
508              The  op, arch, instruction_pointer, and stack_pointer fields are
509              defined for all kinds of ptrace system call stops.  The rest  of
510              the structure is a union; one should read only those fields that
511              are meaningful for the kind of system call stop specified by the
512              op field.
513
514              The  op  field  has  one  of  the  following  values (defined in
515              <linux/ptrace.h>) indicating what  type  of  stop  occurred  and
516              which part of the union is filled:
517
518              PTRACE_SYSCALL_INFO_ENTRY
519                     The entry component of the union contains information re‐
520                     lating to a system call entry stop.
521
522              PTRACE_SYSCALL_INFO_EXIT
523                     The exit component of the union contains information  re‐
524                     lating to a system call exit stop.
525
526              PTRACE_SYSCALL_INFO_SECCOMP
527                     The  seccomp  component of the union contains information
528                     relating to a PTRACE_EVENT_SECCOMP stop.
529
530              PTRACE_SYSCALL_INFO_NONE
531                     No component of the union contains relevant information.
532
533              In case of system call entry or exit stops, the data returned by
534              PTRACE_GET_SYSCALL_INFO       is       limited      to      type
535              PTRACE_SYSCALL_INFO_NONE unless PTRACE_O_TRACESYSGOOD option  is
536              set before the corresponding system call stop has occurred.
537
538   Death under ptrace
539       When  a (possibly multithreaded) process receives a killing signal (one
540       whose disposition is set to SIG_DFL and whose default action is to kill
541       the  process),  all  threads exit.  Tracees report their death to their
542       tracer(s).  Notification of this event is delivered via waitpid(2).
543
544       Note that the killing signal will first cause signal-delivery-stop  (on
545       one tracee only), and only after it is injected by the tracer (or after
546       it was dispatched to a thread which isn't traced), will death from  the
547       signal happen on all tracees within a multithreaded process.  (The term
548       "signal-delivery-stop" is explained below.)
549
550       SIGKILL does not generate signal-delivery-stop and therefore the tracer
551       can't  suppress  it.   SIGKILL kills even within system calls (syscall-
552       exit-stop is not generated prior to death by SIGKILL).  The net  effect
553       is  that  SIGKILL  always  kills the process (all its threads), even if
554       some threads of the process are ptraced.
555
556       When the tracee calls _exit(2), it reports its  death  to  its  tracer.
557       Other threads are not affected.
558
559       When  any  thread  executes  exit_group(2),  every tracee in its thread
560       group reports its death to its tracer.
561
562       If the PTRACE_O_TRACEEXIT option is on, PTRACE_EVENT_EXIT  will  happen
563       before actual death.  This applies to exits via exit(2), exit_group(2),
564       and signal deaths (except SIGKILL, depending on the kernel version; see
565       BUGS  below),  and  when threads are torn down on execve(2) in a multi‐
566       threaded process.
567
568       The tracer cannot assume that the ptrace-stopped tracee exists.   There
569       are  many  scenarios  when  the  tracee  may die while stopped (such as
570       SIGKILL).  Therefore, the tracer must be prepared to  handle  an  ESRCH
571       error  on  any  ptrace operation.  Unfortunately, the same error is re‐
572       turned if the tracee exists but is  not  ptrace-stopped  (for  commands
573       which  require a stopped tracee), or if it is not traced by the process
574       which issued the ptrace call.  The tracer needs to keep  track  of  the
575       stopped/running  state  of  the  tracee, and interpret ESRCH as "tracee
576       died unexpectedly" only if it knows that the tracee has  been  observed
577       to  enter  ptrace-stop.   Note  that  there  is no guarantee that wait‐
578       pid(WNOHANG) will reliably report the tracee's death status if a ptrace
579       operation  returned  ESRCH.  waitpid(WNOHANG) may return 0 instead.  In
580       other words, the tracee may be "not yet fully dead", but already refus‐
581       ing ptrace requests.
582
583       The tracer can't assume that the tracee always ends its life by report‐
584       ing WIFEXITED(status) or WIFSIGNALED(status);  there  are  cases  where
585       this  does not occur.  For example, if a thread other than thread group
586       leader does an execve(2), it disappears; its PID  will  never  be  seen
587       again,  and  any  subsequent  ptrace  stops  will be reported under the
588       thread group leader's PID.
589
590   Stopped states
591       A tracee can be in two states: running or stopped.  For the purposes of
592       ptrace,  a  tracee  which is blocked in a system call (such as read(2),
593       pause(2), etc.)  is nevertheless considered to be running, even if  the
594       tracee  is  blocked  for  a  long  time.  The state of the tracee after
595       PTRACE_LISTEN is somewhat of a gray area: it is not in any  ptrace-stop
596       (ptrace commands won't work on it, and it will deliver waitpid(2) noti‐
597       fications), but it also may be considered "stopped" because it  is  not
598       executing  instructions (is not scheduled), and if it was in group-stop
599       before PTRACE_LISTEN, it will not respond to signals until  SIGCONT  is
600       received.
601
602       There  are  many  kinds  of  states  when the tracee is stopped, and in
603       ptrace discussions they are often conflated.  Therefore, it  is  impor‐
604       tant to use precise terms.
605
606       In  this manual page, any stopped state in which the tracee is ready to
607       accept ptrace commands from the tracer is called ptrace-stop.   Ptrace-
608       stops  can be further subdivided into signal-delivery-stop, group-stop,
609       syscall-stop, PTRACE_EVENT stops, and so on.  These stopped states  are
610       described in detail below.
611
612       When  the running tracee enters ptrace-stop, it notifies its tracer us‐
613       ing waitpid(2) (or one of the other "wait" system calls).  Most of this
614       manual page assumes that the tracer waits with:
615
616           pid = waitpid(pid_or_minus_1, &status, __WALL);
617
618       Ptrace-stopped  tracees are reported as returns with pid greater than 0
619       and WIFSTOPPED(status) true.
620
621       The __WALL flag does not include the WSTOPPED and  WEXITED  flags,  but
622       implies their functionality.
623
624       Setting the WCONTINUED flag when calling waitpid(2) is not recommended:
625       the "continued" state is per-process and consuming it can  confuse  the
626       real parent of the tracee.
627
628       Use  of the WNOHANG flag may cause waitpid(2) to return 0 ("no wait re‐
629       sults available yet") even if the tracer knows there should be a  noti‐
630       fication.  Example:
631
632           errno = 0;
633           ptrace(PTRACE_CONT, pid, 0L, 0L);
634           if (errno == ESRCH) {
635               /* tracee is dead */
636               r = waitpid(tracee, &status, __WALL | WNOHANG);
637               /* r can still be 0 here! */
638           }
639
640       The  following  kinds  of  ptrace-stops  exist:  signal-delivery-stops,
641       group-stops, PTRACE_EVENT stops, syscall-stops.  They all are  reported
642       by waitpid(2) with WIFSTOPPED(status) true.  They may be differentiated
643       by examining the value status>>8, and if there  is  ambiguity  in  that
644       value,  by  querying  PTRACE_GETSIGINFO.   (Note:  the WSTOPSIG(status)
645       macro can't be used to perform this examination, because it returns the
646       value (status>>8) & 0xff.)
647
648   Signal-delivery-stop
649       When  a  (possibly  multithreaded)  process  receives any signal except
650       SIGKILL, the kernel selects an arbitrary thread which handles the  sig‐
651       nal.  (If the signal is generated with tgkill(2), the target thread can
652       be explicitly selected by the  caller.)   If  the  selected  thread  is
653       traced,  it  enters signal-delivery-stop.  At this point, the signal is
654       not yet delivered to the process, and can be suppressed by the  tracer.
655       If  the tracer doesn't suppress the signal, it passes the signal to the
656       tracee in the next ptrace restart request.  This second step of  signal
657       delivery  is called signal injection in this manual page.  Note that if
658       the signal is blocked, signal-delivery-stop doesn't  happen  until  the
659       signal  is  unblocked,  with  the usual exception that SIGSTOP can't be
660       blocked.
661
662       Signal-delivery-stop is observed by the tracer as waitpid(2)  returning
663       with WIFSTOPPED(status) true, with the signal returned by WSTOPSIG(sta‐
664       tus).  If the signal is SIGTRAP,  this  may  be  a  different  kind  of
665       ptrace-stop;  see  the  "Syscall-stops" and "execve" sections below for
666       details.  If WSTOPSIG(status) returns a stopping signal, this may be  a
667       group-stop; see below.
668
669   Signal injection and suppression
670       After signal-delivery-stop is observed by the tracer, the tracer should
671       restart the tracee with the call
672
673           ptrace(PTRACE_restart, pid, 0, sig)
674
675       where PTRACE_restart is one of the restarting ptrace requests.  If  sig
676       is 0, then a signal is not delivered.  Otherwise, the signal sig is de‐
677       livered.  This operation is called  signal  injection  in  this  manual
678       page, to distinguish it from signal-delivery-stop.
679
680       The  sig  value  may  be different from the WSTOPSIG(status) value: the
681       tracer can cause a different signal to be injected.
682
683       Note that a suppressed signal still causes system calls to return  pre‐
684       maturely.   In  this  case,  system calls will be restarted: the tracer
685       will observe the tracee to reexecute the interrupted  system  call  (or
686       restart_syscall(2)  system call for a few system calls which use a dif‐
687       ferent mechanism for restarting) if  the  tracer  uses  PTRACE_SYSCALL.
688       Even  system  calls  (such  as poll(2)) which are not restartable after
689       signal are restarted after signal is suppressed; however,  kernel  bugs
690       exist  which  cause some system calls to fail with EINTR even though no
691       observable signal is injected to the tracee.
692
693       Restarting ptrace commands issued in ptrace-stops other than signal-de‐
694       livery-stop  are not guaranteed to inject a signal, even if sig is non‐
695       zero.  No error is reported; a  nonzero  sig  may  simply  be  ignored.
696       Ptrace  users  should  not  try  to "create a new signal" this way: use
697       tgkill(2) instead.
698
699       The fact that signal injection requests may be ignored when  restarting
700       the  tracee  after ptrace stops that are not signal-delivery-stops is a
701       cause of confusion among ptrace users.  One typical  scenario  is  that
702       the  tracer  observes group-stop, mistakes it for signal-delivery-stop,
703       restarts the tracee with
704
705           ptrace(PTRACE_restart, pid, 0, stopsig)
706
707       with the intention of injecting stopsig, but stopsig gets  ignored  and
708       the tracee continues to run.
709
710       The  SIGCONT  signal  has a side effect of waking up (all threads of) a
711       group-stopped process.  This side effect happens  before  signal-deliv‐
712       ery-stop.  The tracer can't suppress this side effect (it can only sup‐
713       press signal injection, which only causes the SIGCONT handler to not be
714       executed in the tracee, if such a handler is installed).  In fact, wak‐
715       ing up from group-stop may be followed by signal-delivery-stop for sig‐
716       nal(s) other than SIGCONT, if they were pending when SIGCONT was deliv‐
717       ered.  In other words, SIGCONT may be not the first signal observed  by
718       the tracee after it was sent.
719
720       Stopping  signals cause (all threads of) a process to enter group-stop.
721       This side effect happens after signal injection, and therefore  can  be
722       suppressed by the tracer.
723
724       In Linux 2.4 and earlier, the SIGSTOP signal can't be injected.
725
726       PTRACE_GETSIGINFO  can  be used to retrieve a siginfo_t structure which
727       corresponds to the delivered signal.  PTRACE_SETSIGINFO may be used  to
728       modify  it.  If PTRACE_SETSIGINFO has been used to alter siginfo_t, the
729       si_signo field and the sig parameter in  the  restarting  command  must
730       match, otherwise the result is undefined.
731
732   Group-stop
733       When a (possibly multithreaded) process receives a stopping signal, all
734       threads stop.  If some threads are traced,  they  enter  a  group-stop.
735       Note that the stopping signal will first cause signal-delivery-stop (on
736       one tracee only), and only after it is injected by the tracer (or after
737       it  was  dispatched to a thread which isn't traced), will group-stop be
738       initiated on all tracees within the multithreaded process.   As  usual,
739       every  tracee  reports  its  group-stop separately to the corresponding
740       tracer.
741
742       Group-stop is observed by the tracer as waitpid(2) returning with  WIF‐
743       STOPPED(status)  true,  with  the  stopping signal available via WSTOP‐
744       SIG(status).  The same result is returned  by  some  other  classes  of
745       ptrace-stops, therefore the recommended practice is to perform the call
746
747           ptrace(PTRACE_GETSIGINFO, pid, 0, &siginfo)
748
749       The call can be avoided if the signal is not SIGSTOP, SIGTSTP, SIGTTIN,
750       or SIGTTOU; only these four  signals  are  stopping  signals.   If  the
751       tracer  sees  something else, it can't be a group-stop.  Otherwise, the
752       tracer needs to call  PTRACE_GETSIGINFO.   If  PTRACE_GETSIGINFO  fails
753       with  EINVAL, then it is definitely a group-stop.  (Other failure codes
754       are possible, such as ESRCH ("no such process") if a SIGKILL killed the
755       tracee.)
756
757       If  tracee  was attached using PTRACE_SEIZE, group-stop is indicated by
758       PTRACE_EVENT_STOP: status>>16 == PTRACE_EVENT_STOP.  This allows detec‐
759       tion of group-stops without requiring an extra PTRACE_GETSIGINFO call.
760
761       As  of  Linux  2.6.38, after the tracer sees the tracee ptrace-stop and
762       until it restarts or kills it, the tracee will not run,  and  will  not
763       send  notifications  (except  SIGKILL death) to the tracer, even if the
764       tracer enters into another waitpid(2) call.
765
766       The kernel behavior described in the previous paragraph causes a  prob‐
767       lem  with  transparent  handling  of  stopping  signals.  If the tracer
768       restarts the tracee after group-stop, the  stopping  signal  is  effec‐
769       tively  ignored—the  tracee  doesn't  remain  stopped, it runs.  If the
770       tracer doesn't restart the tracee before entering into the  next  wait‐
771       pid(2), future SIGCONT signals will not be reported to the tracer; this
772       would cause the SIGCONT signals to have no effect on the tracee.
773
774       Since Linux 3.4, there is a method to overcome this problem: instead of
775       PTRACE_CONT, a PTRACE_LISTEN command can be used to restart a tracee in
776       a way where it does not execute, but waits for a new event which it can
777       report via waitpid(2) (such as when it is restarted by a SIGCONT).
778
779   PTRACE_EVENT stops
780       If  the  tracer  sets  PTRACE_O_TRACE_*  options, the tracee will enter
781       ptrace-stops called PTRACE_EVENT stops.
782
783       PTRACE_EVENT stops are observed by the tracer as  waitpid(2)  returning
784       with  WIFSTOPPED(status),  and WSTOPSIG(status) returns SIGTRAP (or for
785       PTRACE_EVENT_STOP, returns the stopping signal if tracee is in a group-
786       stop).  An additional bit is set in the higher byte of the status word:
787       the value status>>8 will be
788
789           ((PTRACE_EVENT_foo<<8) | SIGTRAP).
790
791       The following events exist:
792
793       PTRACE_EVENT_VFORK
794              Stop  before  return  from  vfork(2)  or   clone(2)   with   the
795              CLONE_VFORK flag.  When the tracee is continued after this stop,
796              it will wait for child to exit/exec before continuing its execu‐
797              tion (in other words, the usual behavior on vfork(2)).
798
799       PTRACE_EVENT_FORK
800              Stop before return from fork(2) or clone(2) with the exit signal
801              set to SIGCHLD.
802
803       PTRACE_EVENT_CLONE
804              Stop before return from clone(2).
805
806       PTRACE_EVENT_VFORK_DONE
807              Stop  before  return  from  vfork(2)  or   clone(2)   with   the
808              CLONE_VFORK  flag,  but after the child unblocked this tracee by
809              exiting or execing.
810
811       For all four stops described above,  the  stop  occurs  in  the  parent
812       (i.e.,    the    tracee),    not   in   the   newly   created   thread.
813       PTRACE_GETEVENTMSG can be used to retrieve the new thread's ID.
814
815       PTRACE_EVENT_EXEC
816              Stop  before  return   from   execve(2).    Since   Linux   3.0,
817              PTRACE_GETEVENTMSG returns the former thread ID.
818
819       PTRACE_EVENT_EXIT
820              Stop  before  exit  (including death from exit_group(2)), signal
821              death, or exit caused by execve(2) in a  multithreaded  process.
822              PTRACE_GETEVENTMSG  returns  the  exit status.  Registers can be
823              examined (unlike when "real" exit happens).  The tracee is still
824              alive; it needs to be PTRACE_CONTed or PTRACE_DETACHed to finish
825              exiting.
826
827       PTRACE_EVENT_STOP
828              Stop induced by PTRACE_INTERRUPT command, or group-stop, or ini‐
829              tial  ptrace-stop when a new child is attached (only if attached
830              using PTRACE_SEIZE).
831
832       PTRACE_EVENT_SECCOMP
833              Stop triggered by a seccomp(2) rule on tracee syscall entry when
834              PTRACE_O_TRACESECCOMP  has  been set by the tracer.  The seccomp
835              event message data (from the  SECCOMP_RET_DATA  portion  of  the
836              seccomp  filter  rule) can be retrieved with PTRACE_GETEVENTMSG.
837              The semantics of this stop are described in detail in a separate
838              section below.
839
840       PTRACE_GETSIGINFO  on  PTRACE_EVENT  stops returns SIGTRAP in si_signo,
841       with si_code set to (event<<8) | SIGTRAP.
842
843   Syscall-stops
844       If the tracee was restarted by  PTRACE_SYSCALL  or  PTRACE_SYSEMU,  the
845       tracee enters syscall-enter-stop just prior to entering any system call
846       (which will not be executed if the restart was using PTRACE_SYSEMU, re‐
847       gardless  of  any  change  made  to  registers at this point or how the
848       tracee is restarted after this stop).  No matter  which  method  caused
849       the   syscall-entry-stop,  if  the  tracer  restarts  the  tracee  with
850       PTRACE_SYSCALL, the tracee enters  syscall-exit-stop  when  the  system
851       call  is finished, or if it is interrupted by a signal.  (That is, sig‐
852       nal-delivery-stop never happens between syscall-enter-stop and syscall-
853       exit-stop; it happens after syscall-exit-stop.).  If the tracee is con‐
854       tinued using any other method (including  PTRACE_SYSEMU),  no  syscall-
855       exit-stop  occurs.   Note that all mentions PTRACE_SYSEMU apply equally
856       to PTRACE_SYSEMU_SINGLESTEP.
857
858       However, even if the tracee was continued using PTRACE_SYSCALL,  it  is
859       not  guaranteed  that the next stop will be a syscall-exit-stop.  Other
860       possibilities are that the tracee may stop in a PTRACE_EVENT stop  (in‐
861       cluding seccomp stops), exit (if it entered _exit(2) or exit_group(2)),
862       be killed by SIGKILL, or die silently (if it is a thread group  leader,
863       the execve(2) happened in another thread, and that thread is not traced
864       by the same tracer; this situation is discussed later).
865
866       Syscall-enter-stop and syscall-exit-stop are observed by the tracer  as
867       waitpid(2) returning with WIFSTOPPED(status) true, and WSTOPSIG(status)
868       giving SIGTRAP.  If the PTRACE_O_TRACESYSGOOD option  was  set  by  the
869       tracer, then WSTOPSIG(status) will give the value (SIGTRAP | 0x80).
870
871       Syscall-stops  can be distinguished from signal-delivery-stop with SIG‐
872       TRAP by querying PTRACE_GETSIGINFO for the following cases:
873
874       si_code <= 0
875              SIGTRAP was delivered as a result of a  user-space  action,  for
876              example,  a system call (tgkill(2), kill(2), sigqueue(3), etc.),
877              expiration of a POSIX timer, change of state on a POSIX  message
878              queue, or completion of an asynchronous I/O request.
879
880       si_code == SI_KERNEL (0x80)
881              SIGTRAP was sent by the kernel.
882
883       si_code == SIGTRAP or si_code == (SIGTRAP|0x80)
884              This is a syscall-stop.
885
886       However,  syscall-stops  happen very often (twice per system call), and
887       performing PTRACE_GETSIGINFO for every syscall-stop may be somewhat ex‐
888       pensive.
889
890       Some  architectures  allow  the  cases to be distinguished by examining
891       registers.  For example, on x86, rax == -ENOSYS in  syscall-enter-stop.
892       Since  SIGTRAP  (like  any  other signal) always happens after syscall-
893       exit-stop, and at this point rax almost  never  contains  -ENOSYS,  the
894       SIGTRAP  looks  like "syscall-stop which is not syscall-enter-stop"; in
895       other words, it looks like a "stray syscall-exit-stop" and can  be  de‐
896       tected this way.  But such detection is fragile and is best avoided.
897
898       Using  the  PTRACE_O_TRACESYSGOOD  option  is the recommended method to
899       distinguish syscall-stops from other kinds of ptrace-stops, since it is
900       reliable and does not incur a performance penalty.
901
902       Syscall-enter-stop  and  syscall-exit-stop  are  indistinguishable from
903       each other by the tracer.  The tracer needs to keep track  of  the  se‐
904       quence  of ptrace-stops in order to not misinterpret syscall-enter-stop
905       as syscall-exit-stop or vice versa.  In general,  a  syscall-enter-stop
906       is  always  followed  by  syscall-exit-stop,  PTRACE_EVENT stop, or the
907       tracee's death; no other kinds of ptrace-stop  can  occur  in  between.
908       However,  note  that  seccomp stops (see below) can cause syscall-exit-
909       stops, without preceding syscall-entry-stops.  If seccomp  is  in  use,
910       care needs to be taken not to misinterpret such stops as syscall-entry-
911       stops.
912
913       If after syscall-enter-stop, the tracer uses a restarting command other
914       than PTRACE_SYSCALL, syscall-exit-stop is not generated.
915
916       PTRACE_GETSIGINFO  on  syscall-stops  returns SIGTRAP in si_signo, with
917       si_code set to SIGTRAP or (SIGTRAP|0x80).
918
919   PTRACE_EVENT_SECCOMP stops (Linux 3.5 to Linux 4.7)
920       The behavior of PTRACE_EVENT_SECCOMP stops and their  interaction  with
921       other  kinds of ptrace stops has changed between kernel versions.  This
922       documents the behavior from their introduction until Linux 4.7  (inclu‐
923       sive).  The behavior in later kernel versions is documented in the next
924       section.
925
926       A PTRACE_EVENT_SECCOMP stop occurs whenever a SECCOMP_RET_TRACE rule is
927       triggered.   This  is  independent of which methods was used to restart
928       the system call.  Notably, seccomp still runs even if  the  tracee  was
929       restarted  using  PTRACE_SYSEMU and this system call is unconditionally
930       skipped.
931
932       Restarts from this stop will behave as if the stop had  occurred  right
933       before the system call in question.  In particular, both PTRACE_SYSCALL
934       and PTRACE_SYSEMU will normally cause a subsequent  syscall-entry-stop.
935       However,  if  after  the PTRACE_EVENT_SECCOMP the system call number is
936       negative, both the syscall-entry-stop and the system call  itself  will
937       be  skipped.  This means that if the system call number is negative af‐
938       ter  a  PTRACE_EVENT_SECCOMP  and  the  tracee   is   restarted   using
939       PTRACE_SYSCALL,  the  next  observed  stop will be a syscall-exit-stop,
940       rather than the syscall-entry-stop that might have been expected.
941
942   PTRACE_EVENT_SECCOMP stops (since Linux 4.8)
943       Starting with Linux 4.8, the PTRACE_EVENT_SECCOMP stop was reordered to
944       occur between syscall-entry-stop and syscall-exit-stop.  Note that sec‐
945       comp no longer runs (and no PTRACE_EVENT_SECCOMP will be  reported)  if
946       the system call is skipped due to PTRACE_SYSEMU.
947
948       Functionally,  a  PTRACE_EVENT_SECCOMP  stop  functions comparably to a
949       syscall-entry-stop (i.e., continuations using PTRACE_SYSCALL will cause
950       syscall-exit-stops, the system call number may be changed and any other
951       modified registers are visible to the  to-be-executed  system  call  as
952       well).   Note  that  there  may  be, but need not have been a preceding
953       syscall-entry-stop.
954
955       After a PTRACE_EVENT_SECCOMP stop, seccomp will be rerun, with  a  SEC‐
956       COMP_RET_TRACE  rule  now  functioning the same as a SECCOMP_RET_ALLOW.
957       Specifically, this means that if registers are not modified during  the
958       PTRACE_EVENT_SECCOMP stop, the system call will then be allowed.
959
960   PTRACE_SINGLESTEP stops
961       [Details of these kinds of stops are yet to be documented.]
962
963   Informational and restarting ptrace commands
964       Most   ptrace   commands   (all   except  PTRACE_ATTACH,  PTRACE_SEIZE,
965       PTRACE_TRACEME, PTRACE_INTERRUPT, and PTRACE_KILL) require  the  tracee
966       to be in a ptrace-stop, otherwise they fail with ESRCH.
967
968       When  the  tracee is in ptrace-stop, the tracer can read and write data
969       to the tracee using informational commands.  These commands  leave  the
970       tracee in ptrace-stopped state:
971
972           ptrace(PTRACE_PEEKTEXT/PEEKDATA/PEEKUSER, pid, addr, 0);
973           ptrace(PTRACE_POKETEXT/POKEDATA/POKEUSER, pid, addr, long_val);
974           ptrace(PTRACE_GETREGS/GETFPREGS, pid, 0, &struct);
975           ptrace(PTRACE_SETREGS/SETFPREGS, pid, 0, &struct);
976           ptrace(PTRACE_GETREGSET, pid, NT_foo, &iov);
977           ptrace(PTRACE_SETREGSET, pid, NT_foo, &iov);
978           ptrace(PTRACE_GETSIGINFO, pid, 0, &siginfo);
979           ptrace(PTRACE_SETSIGINFO, pid, 0, &siginfo);
980           ptrace(PTRACE_GETEVENTMSG, pid, 0, &long_var);
981           ptrace(PTRACE_SETOPTIONS, pid, 0, PTRACE_O_flags);
982
983       Note  that  some  errors are not reported.  For example, setting signal
984       information (siginfo) may have no effect in some ptrace-stops, yet  the
985       call   may   succeed   (return   0   and   not   set  errno);  querying
986       PTRACE_GETEVENTMSG may succeed and return some random value if  current
987       ptrace-stop is not documented as returning a meaningful event message.
988
989       The call
990
991           ptrace(PTRACE_SETOPTIONS, pid, 0, PTRACE_O_flags);
992
993       affects  one  tracee.   The tracee's current flags are replaced.  Flags
994       are inherited by new tracees created  and  "auto-attached"  via  active
995       PTRACE_O_TRACEFORK,  PTRACE_O_TRACEVFORK,  or  PTRACE_O_TRACECLONE  op‐
996       tions.
997
998       Another group of commands makes the ptrace-stopped  tracee  run.   They
999       have the form:
1000
1001           ptrace(cmd, pid, 0, sig);
1002
1003       where cmd is PTRACE_CONT, PTRACE_LISTEN, PTRACE_DETACH, PTRACE_SYSCALL,
1004       PTRACE_SINGLESTEP, PTRACE_SYSEMU, or PTRACE_SYSEMU_SINGLESTEP.  If  the
1005       tracee is in signal-delivery-stop, sig is the signal to be injected (if
1006       it is nonzero).  Otherwise, sig may be  ignored.   (When  restarting  a
1007       tracee  from a ptrace-stop other than signal-delivery-stop, recommended
1008       practice is to always pass 0 in sig.)
1009
1010   Attaching and detaching
1011       A thread can be attached to the tracer using the call
1012
1013           ptrace(PTRACE_ATTACH, pid, 0, 0);
1014
1015       or
1016
1017           ptrace(PTRACE_SEIZE, pid, 0, PTRACE_O_flags);
1018
1019       PTRACE_ATTACH sends SIGSTOP to this thread.  If the tracer  wants  this
1020       SIGSTOP to have no effect, it needs to suppress it.  Note that if other
1021       signals are concurrently sent to this thread during attach, the  tracer
1022       may  see  the  tracee  enter  signal-delivery-stop with other signal(s)
1023       first!  The usual practice is to reinject these signals  until  SIGSTOP
1024       is  seen, then suppress SIGSTOP injection.  The design bug here is that
1025       a ptrace attach and a concurrently delivered SIGSTOP may race  and  the
1026       concurrent SIGSTOP may be lost.
1027
1028       Since  attaching  sends  SIGSTOP  and the tracer usually suppresses it,
1029       this may cause a stray EINTR return from the currently executing system
1030       call  in the tracee, as described in the "Signal injection and suppres‐
1031       sion" section.
1032
1033       Since Linux 3.4, PTRACE_SEIZE can be  used  instead  of  PTRACE_ATTACH.
1034       PTRACE_SEIZE  does  not stop the attached process.  If you need to stop
1035       it after attach (or at any other time) without sending it any  signals,
1036       use PTRACE_INTERRUPT command.
1037
1038       The request
1039
1040           ptrace(PTRACE_TRACEME, 0, 0, 0);
1041
1042       turns  the  calling  thread into a tracee.  The thread continues to run
1043       (doesn't enter ptrace-stop).   A  common  practice  is  to  follow  the
1044       PTRACE_TRACEME with
1045
1046           raise(SIGSTOP);
1047
1048       and  allow  the parent (which is our tracer now) to observe our signal-
1049       delivery-stop.
1050
1051       If the PTRACE_O_TRACEFORK, PTRACE_O_TRACEVFORK, or  PTRACE_O_TRACECLONE
1052       options are in effect, then children created by, respectively, vfork(2)
1053       or clone(2) with the CLONE_VFORK flag, fork(2)  or  clone(2)  with  the
1054       exit  signal set to SIGCHLD, and other kinds of clone(2), are automati‐
1055       cally attached to the same tracer which traced their  parent.   SIGSTOP
1056       is  delivered  to  the children, causing them to enter signal-delivery-
1057       stop after they exit the system call which created them.
1058
1059       Detaching of the tracee is performed by:
1060
1061           ptrace(PTRACE_DETACH, pid, 0, sig);
1062
1063       PTRACE_DETACH is a restarting  operation;  therefore  it  requires  the
1064       tracee to be in ptrace-stop.  If the tracee is in signal-delivery-stop,
1065       a signal can be injected.  Otherwise, the sig parameter may be silently
1066       ignored.
1067
1068       If  the tracee is running when the tracer wants to detach it, the usual
1069       solution is to send SIGSTOP (using tgkill(2), to make sure it  goes  to
1070       the  correct  thread),  wait for the tracee to stop in signal-delivery-
1071       stop for SIGSTOP and then detach it (suppressing SIGSTOP injection).  A
1072       design  bug  is  that  this can race with concurrent SIGSTOPs.  Another
1073       complication is that the tracee may enter other ptrace-stops and  needs
1074       to  be  restarted and waited for again, until SIGSTOP is seen.  Yet an‐
1075       other complication is to be sure that the tracee is not already ptrace-
1076       stopped,  because  no  signal  delivery  happens  while  it is—not even
1077       SIGSTOP.
1078
1079       If  the  tracer  dies,  all  tracees  are  automatically  detached  and
1080       restarted,  unless  they  were in group-stop.  Handling of restart from
1081       group-stop is currently buggy, but the  "as  planned"  behavior  is  to
1082       leave  tracee  stopped  and  waiting  for  SIGCONT.   If  the tracee is
1083       restarted from signal-delivery-stop, the pending signal is injected.
1084
1085   execve(2) under ptrace
1086       When one thread in a multithreaded process calls execve(2), the  kernel
1087       destroys  all other threads in the process, and resets the thread ID of
1088       the execing thread to the thread group ID (process ID).   (Or,  to  put
1089       things  another way, when a multithreaded process does an execve(2), at
1090       completion of the call, it appears as though the execve(2) occurred  in
1091       the thread group leader, regardless of which thread did the execve(2).)
1092       This resetting of the thread ID looks very confusing to tracers:
1093
1094       •  All  other  threads  stop  in   PTRACE_EVENT_EXIT   stop,   if   the
1095          PTRACE_O_TRACEEXIT option was turned on.  Then all other threads ex‐
1096          cept the thread group leader report death  as  if  they  exited  via
1097          _exit(2) with exit code 0.
1098
1099       •  The  execing  tracee  changes  its  thread ID while it is in the ex‐
1100          ecve(2).  (Remember, under ptrace, the  "pid"  returned  from  wait‐
1101          pid(2),  or fed into ptrace calls, is the tracee's thread ID.)  That
1102          is, the tracee's thread ID is reset to be the same  as  its  process
1103          ID, which is the same as the thread group leader's thread ID.
1104
1105       •  Then a PTRACE_EVENT_EXEC stop happens, if the PTRACE_O_TRACEEXEC op‐
1106          tion was turned on.
1107
1108       •  If the thread group leader has reported its  PTRACE_EVENT_EXIT  stop
1109          by  this  time, it appears to the tracer that the dead thread leader
1110          "reappears from nowhere".  (Note: the thread group leader  does  not
1111          report death via WIFEXITED(status) until there is at least one other
1112          live thread.  This eliminates the possibility that the  tracer  will
1113          see  it dying and then reappearing.)  If the thread group leader was
1114          still alive, for the tracer this may look as if thread group  leader
1115          returns  from  a different system call than it entered, or even "re‐
1116          turned from a system call even though  it  was  not  in  any  system
1117          call".   If the thread group leader was not traced (or was traced by
1118          a different tracer), then during execve(2) it will appear as  if  it
1119          has become a tracee of the tracer of the execing tracee.
1120
1121       All  of  the above effects are the artifacts of the thread ID change in
1122       the tracee.
1123
1124       The PTRACE_O_TRACEEXEC option is the recommended tool for dealing  with
1125       this situation.  First, it enables PTRACE_EVENT_EXEC stop, which occurs
1126       before  execve(2)  returns.   In  this  stop,  the   tracer   can   use
1127       PTRACE_GETEVENTMSG  to  retrieve  the tracee's former thread ID.  (This
1128       feature was introduced in Linux 3.0.)  Second,  the  PTRACE_O_TRACEEXEC
1129       option disables legacy SIGTRAP generation on execve(2).
1130
1131       When  the  tracer  receives  PTRACE_EVENT_EXEC stop notification, it is
1132       guaranteed that except this tracee and  the  thread  group  leader,  no
1133       other threads from the process are alive.
1134
1135       On receiving the PTRACE_EVENT_EXEC stop notification, the tracer should
1136       clean up all its internal data structures  describing  the  threads  of
1137       this  process,  and  retain only one data structure—one which describes
1138       the single still running tracee, with
1139
1140           thread ID == thread group ID == process ID.
1141
1142       Example: two threads call execve(2) at the same time:
1143
1144       *** we get syscall-enter-stop in thread 1: **
1145       PID1 execve("/bin/foo", "foo" <unfinished ...>
1146       *** we issue PTRACE_SYSCALL for thread 1 **
1147       *** we get syscall-enter-stop in thread 2: **
1148       PID2 execve("/bin/bar", "bar" <unfinished ...>
1149       *** we issue PTRACE_SYSCALL for thread 2 **
1150       *** we get PTRACE_EVENT_EXEC for PID0, we issue PTRACE_SYSCALL **
1151       *** we get syscall-exit-stop for PID0: **
1152       PID0 <... execve resumed> )             = 0
1153
1154       If the PTRACE_O_TRACEEXEC option is  not  in  effect  for  the  execing
1155       tracee,   and   if   the   tracee   was   PTRACE_ATTACHed  rather  that
1156       PTRACE_SEIZEd, the kernel delivers an extra SIGTRAP to the tracee after
1157       execve(2)  returns.   This  is an ordinary signal (similar to one which
1158       can be generated by kill -TRAP), not a  special  kind  of  ptrace-stop.
1159       Employing  PTRACE_GETSIGINFO  for  this signal returns si_code set to 0
1160       (SI_USER).  This signal may be blocked by signal mask, and thus may  be
1161       delivered (much) later.
1162
1163       Usually,  the  tracer  (for  example, strace(1)) would not want to show
1164       this extra post-execve SIGTRAP signal to the user, and  would  suppress
1165       its  delivery  to  the  tracee  (if  SIGTRAP is set to SIG_DFL, it is a
1166       killing signal).  However, determining which SIGTRAP to suppress is not
1167       easy.   Setting the PTRACE_O_TRACEEXEC option or using PTRACE_SEIZE and
1168       thus suppressing this extra SIGTRAP is the recommended approach.
1169
1170   Real parent
1171       The ptrace API (ab)uses the standard UNIX parent/child  signaling  over
1172       waitpid(2).   This used to cause the real parent of the process to stop
1173       receiving several kinds of  waitpid(2)  notifications  when  the  child
1174       process is traced by some other process.
1175
1176       Many  of  these  bugs  have  been fixed, but as of Linux 2.6.38 several
1177       still exist; see BUGS below.
1178
1179       As of Linux 2.6.38, the following is believed to work correctly:
1180
1181       •  exit/death by signal is reported first to the tracer, then, when the
1182          tracer  consumes  the  waitpid(2) result, to the real parent (to the
1183          real parent only when the whole multithreaded  process  exits).   If
1184          the  tracer  and the real parent are the same process, the report is
1185          sent only once.
1186

RETURN VALUE

1188       On success, the PTRACE_PEEK* requests return the  requested  data  (but
1189       see NOTES), the PTRACE_SECCOMP_GET_FILTER request returns the number of
1190       instructions in the BPF program,  the  PTRACE_GET_SYSCALL_INFO  request
1191       returns  the number of bytes available to be written by the kernel, and
1192       other requests return zero.
1193
1194       On error, all requests return -1, and errno is set to indicate the  er‐
1195       ror.  Since the value returned by a successful PTRACE_PEEK* request may
1196       be -1, the caller must clear errno before the call, and then  check  it
1197       afterward to determine whether or not an error occurred.
1198

ERRORS

1200       EBUSY  (i386  only) There was an error with allocating or freeing a de‐
1201              bug register.
1202
1203       EFAULT There was an attempt to read from or write to an invalid area in
1204              the  tracer's  or the tracee's memory, probably because the area
1205              wasn't mapped or accessible.  Unfortunately, under  Linux,  dif‐
1206              ferent  variations  of this fault will return EIO or EFAULT more
1207              or less arbitrarily.
1208
1209       EINVAL An attempt was made to set an invalid option.
1210
1211       EIO    request is invalid, or an attempt was made to read from or write
1212              to  an  invalid  area in the tracer's or the tracee's memory, or
1213              there was a word-alignment violation, or an invalid  signal  was
1214              specified during a restart request.
1215
1216       EPERM  The  specified  process cannot be traced.  This could be because
1217              the tracer has insufficient privileges (the required  capability
1218              is  CAP_SYS_PTRACE);  unprivileged  processes  cannot trace pro‐
1219              cesses that they cannot send signals to or  those  running  set-
1220              user-ID/set-group-ID  programs,  for  obvious reasons.  Alterna‐
1221              tively, the process may already  be  being  traced,  or  (before
1222              Linux 2.6.26) be init(1) (PID 1).
1223
1224       ESRCH  The  specified process does not exist, or is not currently being
1225              traced by the caller, or is not stopped (for requests  that  re‐
1226              quire a stopped tracee).
1227

STANDARDS

1229       None.
1230

HISTORY

1232       SVr4, 4.3BSD.
1233
1234       Before  Linux  2.6.26,  init(1),  the  process  with  PID 1, may not be
1235       traced.
1236

NOTES

1238       Although arguments to ptrace() are interpreted according to the  proto‐
1239       type  given,  glibc  currently declares ptrace() as a variadic function
1240       with only the request argument fixed.  It is recommended to always sup‐
1241       ply  four arguments, even if the requested operation does not use them,
1242       setting unused/ignored arguments to 0L or (void *) 0.
1243
1244       A tracees parent continues to be the tracer even if that  tracer  calls
1245       execve(2).
1246
1247       The  layout of the contents of memory and the USER area are quite oper‐
1248       ating-system- and architecture-specific.  The offset supplied, and  the
1249       data  returned,  might not entirely match with the definition of struct
1250       user.
1251
1252       The size of a "word" is  determined  by  the  operating-system  variant
1253       (e.g., for 32-bit Linux it is 32 bits).
1254
1255       This page documents the way the ptrace() call works currently in Linux.
1256       Its behavior differs significantly on other flavors of  UNIX.   In  any
1257       case,  use  of  ptrace() is highly specific to the operating system and
1258       architecture.
1259
1260   Ptrace access mode checking
1261       Various parts of the kernel-user-space API (not  just  ptrace()  opera‐
1262       tions),  require  so-called  "ptrace access mode" checks, whose outcome
1263       determines whether an operation is  permitted  (or,  in  a  few  cases,
1264       causes  a "read" operation to return sanitized data).  These checks are
1265       performed in cases where one process can inspect sensitive  information
1266       about,  or  in  some  cases  modify the state of, another process.  The
1267       checks are based on factors such as the credentials and capabilities of
1268       the two processes, whether or not the "target" process is dumpable, and
1269       the results of checks performed by any enabled  Linux  Security  Module
1270       (LSM)—for  example,  SELinux,  Yama,  or Smack—and by the commoncap LSM
1271       (which is always invoked).
1272
1273       Prior to Linux 2.6.27, all access checks were of a single type.   Since
1274       Linux 2.6.27, two access mode levels are distinguished:
1275
1276       PTRACE_MODE_READ
1277              For  "read" operations or other operations that are less danger‐
1278              ous,   such    as:    get_robust_list(2);    kcmp(2);    reading
1279              /proc/pid/auxv,  /proc/pid/environ,  or /proc/pid/stat; or read‐
1280              link(2) of a /proc/pid/ns/* file.
1281
1282       PTRACE_MODE_ATTACH
1283              For "write" operations, or other operations that are  more  dan‐
1284              gerous,  such  as:  ptrace  attaching (PTRACE_ATTACH) to another
1285              process or  calling  process_vm_writev(2).   (PTRACE_MODE_ATTACH
1286              was effectively the default before Linux 2.6.27.)
1287
1288       Since  Linux 4.5, the above access mode checks are combined (ORed) with
1289       one of the following modifiers:
1290
1291       PTRACE_MODE_FSCREDS
1292              Use the caller's filesystem UID and GID (see credentials(7))  or
1293              effective capabilities for LSM checks.
1294
1295       PTRACE_MODE_REALCREDS
1296              Use  the caller's real UID and GID or permitted capabilities for
1297              LSM checks.  This was effectively the default before Linux 4.5.
1298
1299       Because combining one of the  credential  modifiers  with  one  of  the
1300       aforementioned  access modes is typical, some macros are defined in the
1301       kernel sources for the combinations:
1302
1303       PTRACE_MODE_READ_FSCREDS
1304              Defined as PTRACE_MODE_READ | PTRACE_MODE_FSCREDS.
1305
1306       PTRACE_MODE_READ_REALCREDS
1307              Defined as PTRACE_MODE_READ | PTRACE_MODE_REALCREDS.
1308
1309       PTRACE_MODE_ATTACH_FSCREDS
1310              Defined as PTRACE_MODE_ATTACH | PTRACE_MODE_FSCREDS.
1311
1312       PTRACE_MODE_ATTACH_REALCREDS
1313              Defined as PTRACE_MODE_ATTACH | PTRACE_MODE_REALCREDS.
1314
1315       One further modifier can be ORed with the access mode:
1316
1317       PTRACE_MODE_NOAUDIT (since Linux 3.3)
1318              Don't audit this access mode check.  This modifier  is  employed
1319              for  ptrace  access  mode  checks  (such  as checks when reading
1320              /proc/pid/stat) that merely cause the output to be  filtered  or
1321              sanitized,  rather  than  causing an error to be returned to the
1322              caller.  In these cases, accessing the file is  not  a  security
1323              violation  and  there  is no reason to generate a security audit
1324              record.  This modifier suppresses the generation of such an  au‐
1325              dit record for the particular access check.
1326
1327       Note  that all of the PTRACE_MODE_* constants described in this subsec‐
1328       tion are kernel-internal, and not visible to user space.  The  constant
1329       names  are mentioned here in order to label the various kinds of ptrace
1330       access mode checks that are performed for various system calls and  ac‐
1331       cesses  to  various  pseudofiles  (e.g., under /proc).  These names are
1332       used in other manual pages to provide a simple shorthand  for  labeling
1333       the different kernel checks.
1334
1335       The  algorithm  employed  for  ptrace  access  mode checking determines
1336       whether the calling process is allowed to perform the corresponding ac‐
1337       tion  on  the target process.  (In the case of opening /proc/pid files,
1338       the "calling process" is the one opening the file, and the process with
1339       the  corresponding  PID  is the "target process".)  The algorithm is as
1340       follows:
1341
1342       (1)  If the calling thread and the target thread are in the same thread
1343            group, access is always allowed.
1344
1345       (2)  If  the  access  mode specifies PTRACE_MODE_FSCREDS, then, for the
1346            check in the next step, employ the  caller's  filesystem  UID  and
1347            GID.   (As noted in credentials(7), the filesystem UID and GID al‐
1348            most always have the same values as  the  corresponding  effective
1349            IDs.)
1350
1351            Otherwise, the access mode specifies PTRACE_MODE_REALCREDS, so use
1352            the caller's real UID and GID for the checks  in  the  next  step.
1353            (Most  APIs  that check the caller's UID and GID use the effective
1354            IDs.  For historical reasons, the PTRACE_MODE_REALCREDS check uses
1355            the real IDs instead.)
1356
1357       (3)  Deny access if neither of the following is true:
1358
1359            •  The real, effective, and saved-set user IDs of the target match
1360               the caller's user ID, and the real,  effective,  and  saved-set
1361               group IDs of the target match the caller's group ID.
1362
1363            •  The  caller has the CAP_SYS_PTRACE capability in the user name‐
1364               space of the target.
1365
1366       (4)  Deny access if the target process "dumpable" attribute has a value
1367            other    than   1   (SUID_DUMP_USER;   see   the   discussion   of
1368            PR_SET_DUMPABLE in prctl(2)), and the caller  does  not  have  the
1369            CAP_SYS_PTRACE  capability  in  the  user  namespace of the target
1370            process.
1371
1372       (5)  The kernel LSM security_ptrace_access_check() interface is invoked
1373            to  see  if ptrace access is permitted.  The results depend on the
1374            LSM(s).  The implementation of this interface in the commoncap LSM
1375            performs the following steps:
1376
1377            (5.1)  If  the  access mode includes PTRACE_MODE_FSCREDS, then use
1378                   the caller's effective  capability  set  in  the  following
1379                   check; otherwise (the access mode specifies PTRACE_MODE_RE‐
1380                   ALCREDS, so) use the caller's permitted capability set.
1381
1382            (5.2)  Deny access if neither of the following is true:
1383
1384                   •  The caller and the target process are in the  same  user
1385                      namespace,  and the caller's capabilities are a superset
1386                      of the target process's permitted capabilities.
1387
1388                   •  The caller has the CAP_SYS_PTRACE capability in the tar‐
1389                      get process's user namespace.
1390
1391                   Note  that  the  commoncap LSM does not distinguish between
1392                   PTRACE_MODE_READ and PTRACE_MODE_ATTACH.
1393
1394       (6)  If access has not been denied by any of the preceding steps,  then
1395            access is allowed.
1396
1397   /proc/sys/kernel/yama/ptrace_scope
1398       On  systems  with the Yama Linux Security Module (LSM) installed (i.e.,
1399       the   kernel   was   configured   with    CONFIG_SECURITY_YAMA),    the
1400       /proc/sys/kernel/yama/ptrace_scope file (available since Linux 3.4) can
1401       be used to restrict the ability to trace a process with  ptrace()  (and
1402       thus  also the ability to use tools such as strace(1) and gdb(1)).  The
1403       goal of such restrictions is to prevent  attack  escalation  whereby  a
1404       compromised  process  can  ptrace-attach  to  other sensitive processes
1405       (e.g., a GPG agent or an SSH session) owned by the  user  in  order  to
1406       gain  additional  credentials  that may exist in memory and thus expand
1407       the scope of the attack.
1408
1409       More precisely, the Yama LSM limits two types of operations:
1410
1411       •  Any operation that performs a ptrace access mode  PTRACE_MODE_ATTACH
1412          check—for  example, ptrace() PTRACE_ATTACH.  (See the "Ptrace access
1413          mode checking" discussion above.)
1414
1415ptrace() PTRACE_TRACEME.
1416
1417       A process  that  has  the  CAP_SYS_PTRACE  capability  can  update  the
1418       /proc/sys/kernel/yama/ptrace_scope  file with one of the following val‐
1419       ues:
1420
1421       0 ("classic ptrace permissions")
1422              No  additional   restrictions   on   operations   that   perform
1423              PTRACE_MODE_ATTACH checks (beyond those imposed by the commoncap
1424              and other LSMs).
1425
1426              The use of PTRACE_TRACEME is unchanged.
1427
1428       1 ("restricted ptrace") [default value]
1429              When performing an operation that requires a  PTRACE_MODE_ATTACH
1430              check,  the  calling process must either have the CAP_SYS_PTRACE
1431              capability in the user namespace of the  target  process  or  it
1432              must have a predefined relationship with the target process.  By
1433              default, the predefined relationship is that the target  process
1434              must be a descendant of the caller.
1435
1436              A  target  process can employ the prctl(2) PR_SET_PTRACER opera‐
1437              tion to declare an additional PID that  is  allowed  to  perform
1438              PTRACE_MODE_ATTACH  operations  on  the  target.  See the kernel
1439              source file Documentation/admin-guide/LSM/Yama.rst (or  Documen‐
1440              tation/security/Yama.txt before Linux 4.13) for further details.
1441
1442              The use of PTRACE_TRACEME is unchanged.
1443
1444       2 ("admin-only attach")
1445              Only  processes  with  the CAP_SYS_PTRACE capability in the user
1446              namespace of the target process may  perform  PTRACE_MODE_ATTACH
1447              operations or trace children that employ PTRACE_TRACEME.
1448
1449       3 ("no attach")
1450              No  process  may  perform PTRACE_MODE_ATTACH operations or trace
1451              children that employ PTRACE_TRACEME.
1452
1453              Once this value has been written  to  the  file,  it  cannot  be
1454              changed.
1455
1456       With respect to values 1 and 2, note that creating a new user namespace
1457       effectively removes the protection offered by Yama.  This is because  a
1458       process  in  the  parent user namespace whose effective UID matches the
1459       UID of the creator of a child namespace has all capabilities (including
1460       CAP_SYS_PTRACE)  when performing operations within the child user name‐
1461       space (and further-removed  descendants  of  that  namespace).   Conse‐
1462       quently, when a process tries to use user namespaces to sandbox itself,
1463       it inadvertently weakens the protections offered by the Yama LSM.
1464
1465   C library/kernel differences
1466       At the system call level,  the  PTRACE_PEEKTEXT,  PTRACE_PEEKDATA,  and
1467       PTRACE_PEEKUSER requests have a different API: they store the result at
1468       the address specified by the data parameter, and the  return  value  is
1469       the  error  flag.  The glibc wrapper function provides the API given in
1470       DESCRIPTION above, with the result being returned via the function  re‐
1471       turn value.
1472

BUGS

1474       On  hosts  with Linux 2.6 kernel headers, PTRACE_SETOPTIONS is declared
1475       with a different value than the one for Linux 2.4.  This leads  to  ap‐
1476       plications  compiled  with Linux 2.6 kernel headers failing when run on
1477       Linux 2.4.  This can be worked around by  redefining  PTRACE_SETOPTIONS
1478       to PTRACE_OLDSETOPTIONS, if that is defined.
1479
1480       Group-stop  notifications  are sent to the tracer, but not to real par‐
1481       ent.  Last confirmed on 2.6.38.6.
1482
1483       If a thread group leader is traced and exits  by  calling  _exit(2),  a
1484       PTRACE_EVENT_EXIT  stop will happen for it (if requested), but the sub‐
1485       sequent WIFEXITED notification will not be delivered  until  all  other
1486       threads  exit.   As  explained above, if one of other threads calls ex‐
1487       ecve(2), the death of the thread group leader will never  be  reported.
1488       If  the  execed  thread  is  not traced by this tracer, the tracer will
1489       never know that execve(2) happened.   One  possible  workaround  is  to
1490       PTRACE_DETACH  the thread group leader instead of restarting it in this
1491       case.  Last confirmed on 2.6.38.6.
1492
1493       A SIGKILL signal may still cause a PTRACE_EVENT_EXIT stop before actual
1494       signal  death.   This may be changed in the future; SIGKILL is meant to
1495       always immediately kill tasks even under  ptrace.   Last  confirmed  on
1496       Linux 3.13.
1497
1498       Some  system  calls return with EINTR if a signal was sent to a tracee,
1499       but delivery was suppressed by the tracer.  (This is very typical oper‐
1500       ation: it is usually done by debuggers on every attach, in order to not
1501       introduce a bogus SIGSTOP).  As of Linux 3.2.9,  the  following  system
1502       calls are affected (this list is likely incomplete): epoll_wait(2), and
1503       read(2) from an inotify(7) file descriptor.  The usual symptom of  this
1504       bug is that when you attach to a quiescent process with the command
1505
1506           strace -p <process-ID>
1507
1508       then, instead of the usual and expected one-line output such as
1509
1510           restart_syscall(<... resuming interrupted call ...>_
1511
1512       or
1513
1514           select(6, [5], NULL, [5], NULL_
1515
1516       ('_' denotes the cursor position), you observe more than one line.  For
1517       example:
1518
1519               clock_gettime(CLOCK_MONOTONIC, {15370, 690928118}) = 0
1520               epoll_wait(4,_
1521
1522       What  is  not  visible  here  is  that  the  process  was  blocked   in
1523       epoll_wait(2)  before  strace(1)  has attached to it.  Attaching caused
1524       epoll_wait(2) to return to user space with the error  EINTR.   In  this
1525       particular  case,  the program reacted to EINTR by checking the current
1526       time, and then executing epoll_wait(2) again.  (Programs which  do  not
1527       expect  such  "stray" EINTR errors may behave in an unintended way upon
1528       an strace(1) attach.)
1529
1530       Contrary to the normal rules, the glibc wrapper for  ptrace()  can  set
1531       errno to zero.
1532

SEE ALSO

1534       gdb(1),  ltrace(1), strace(1), clone(2), execve(2), fork(2), gettid(2),
1535       prctl(2), seccomp(2), sigaction(2),  tgkill(2),  vfork(2),  waitpid(2),
1536       exec(3), capabilities(7), signal(7)
1537
1538
1539
1540Linux man-pages 6.05              2023-03-30                         ptrace(2)
Impressum