.\" PTRACE_SETSIGINFO, PTRACE_SYSEMU, PTRACE_SYSEMU_SINGLESTEP
.\" (Thanks to Blaisorblade, Daniel Jacobowitz and others who helped.)
.\" 2011-09, major update by Denys Vlasenko <vda.linux@googlemail.com>
+.\" 2015-01, Kees Cook <keescook@chromium.org>
+.\" Added PTRACE_O_TRACESECCOMP, PTRACE_EVENT_SECCOMP
.\"
-.TH PTRACE 2 2013-07-11 "Linux" "Linux Programmer's Manual"
+.TH PTRACE 2 2015-07-23 "Linux" "Linux Programmer's Manual"
.SH NAME
ptrace \- process trace
.SH SYNOPSIS
and
.IR data
are ignored.)
-.LP
+.IP
The
.B PTRACE_TRACEME
request is used only by the tracee;
For requests other than
.BR PTRACE_ATTACH ,
.BR PTRACE_SEIZE ,
-.B PTRACE_INTERRUPT
+.BR PTRACE_INTERRUPT ,
and
.BR PTRACE_KILL ,
the tracee must be stopped.
Linux does not have separate text and data address spaces,
so these two requests are currently equivalent.
.RI ( data
-is ignored.)
+is ignored; but see NOTES.)
.TP
.B PTRACE_PEEKUSER
.\" PTRACE_PEEKUSR in kernel source, but glibc uses PTRACE_PEEKUSER,
architecture.
See NOTES.
.RI ( data
-is ignored.)
+is ignored; but see NOTES.)
.TP
.BR PTRACE_POKETEXT ", " PTRACE_POKEDATA
Copy the word
As for
.BR PTRACE_POKEUSER ,
some general-purpose register modifications may be disallowed.
-.\" FIXME In the preceding sentence, which modifications are disallowed,
+.\" FIXME . In the preceding sentence, which modifications are disallowed,
.\" and when they are disallowed, how does user space discover that fact?
.RI ( addr
is ignored.)
.RI ( addr
is ignored.)
.TP
+.BR PTRACE_PEEKSIGINFO " (since Linux 3.10)"
+.\" commit 84c751bd4aebbaae995fe32279d3dba48327bad4
+Retrieve
+.I siginfo_t
+structures without removing signals from a queue.
+.I addr
+points to a
+.I ptrace_peeksiginfo_args
+structure that specifies the ordinal position from which
+copying of signals should start,
+and the number of signals to copy.
+.I siginfo_t
+structures are copied into the buffer pointed to by
+.IR data .
+The return value contains the number of copied signals (zero indicates
+that there is no signal corresponding to the specified ordinal position).
+Within the returned
+.I siginfo
+structures,
+the
+.IR si_code
+field includes information
+.RB ( __SI_CHLD ,
+.BR __SI_FAULT ,
+etc.) that are not otherwise exposed to user space.
+.PP
+.in +10n
+.nf
+struct ptrace_peeksiginfo_args {
+ u64 off; /* Ordinal position in queue at which
+ to start copying signals */
+ u32 flags; /* PTRACE_PEEKSIGINFO_SHARED or 0 */
+ s32 nr; /* Number of signals to copy */
+};
+.fi
+
+Currently, there is only one flag,
+.BR PTRACE_PEEKSIGINFO_SHARED ,
+for dumping signals from the process-wide signal queue.
+If this flag is not set,
+signals are read from the per-thread queue of the specified thread.
+.in
+.PP
+.TP
+.BR PTRACE_GETSIGMASK " (since Linux 3.11)"
+.\" commit 29000caecbe87b6b66f144f72111f0d02fbbf0c1
+Place a copy of the mask of blocked signals (see
+.BR sigprocmask (2))
+in the buffer pointed to by
+.IR data ,
+which should be a pointer to a buffer of type
+.IR sigset_t .
+The
+.I addr
+argument contains the size of the buffer pointed to by
+.IR data
+(i.e.,
+.IR sizeof(sigset_t) ).
+.TP
+.BR PTRACE_SETSIGMASK " (since Linux 3.11)"
+Change the mask of blocked signals (see
+.BR sigprocmask (2))
+to the value specified in the buffer pointed to by
+.IR data ,
+which should be a pointer to a buffer of type
+.IR sigset_t .
+The
+.I addr
+argument contains the size of the buffer pointed to by
+.IR data
+(i.e.,
+.IR sizeof(sigset_t) ).
+.TP
.BR PTRACE_SETOPTIONS " (since Linux 2.4.6; see BUGS for caveats)"
Set ptrace options from
.IR data .
The PID of the new process can (since Linux 2.6.18) be retrieved with
.BR PTRACE_GETEVENTMSG .
+.TP
+.BR PTRACE_O_TRACESECCOMP " (since Linux 3.5)"
+Stop the tracee when a
+.BR seccomp (2)
+.BR SECCOMP_RET_TRACE
+rule is triggered.
+A
+.BR waitpid (2)
+by the tracer will return a
+.I status
+value such that
+
+.nf
+ status>>8 == (SIGTRAP | (PTRACE_EVENT_SECCOMP<<8))
+.fi
+
+While this triggers a
+.BR PTRACE_EVENT
+stop, it is similar to a syscall-enter-stop, in that the tracee has
+not yet entered the syscall that seccomp triggered on.
+The seccomp event message data (from the
+.BR SECCOMP_RET_DATA
+portion of the seccomp filter rule) can be retrieved with
+.BR PTRACE_GETEVENTMSG .
+.TP
+.BR PTRACE_O_SUSPEND_SECCOMP " (since Linux 4.2)"
+Suspend the tracee's seccomp protections. This applies regardless of mode, and
+can be used when the tracee has not yet installed seccomp filters. That is, a
+valid usecase is to suspend a tracee's seccomp protections before they are
+installed by the tracee, let the tracee install the filters, and then clear
+this flag when the filters should be resumed. Setting this option requires that
+the tracer have
+.BR CAP_SYS_ADMIN ,
+not have any seccomp protections installed, and not have
+.BR PTRACE_O_SUSPEND_SECCOMP
+set on itself.
.RE
.TP
.BR PTRACE_GETEVENTMSG " (since Linux 2.5.46)"
and
.BR PTRACE_EVENT_CLONE ,
this is the PID of the new process.
-.RI ( addr
+For
+.BR PTRACE_EVENT_SECCOMP ,
+this is the
+.BR seccomp (2)
+filter's
+.BR SECCOMP_RET_DATA
+associated with the triggered rule.
+.RI ( addr
is ignored.)
.TP
.B PTRACE_CONT
returns the stop signal.
If any other ptrace-stop is generated at the same time (for example,
if a signal is sent to the tracee), this ptrace-stop happens.
-If none of the above applies (for example, if the tracee is running in userspace),
-it stops with
+If none of the above applies (for example, if the tracee is running in user
+space), it stops with
.B PTRACE_EVENT_STOP
with
.I WSTOPSIG(status)
.BR PTRACE_ATTACH ,
.B PTRACE_SEIZE
does not stop the process.
+Group-stops are reported as
+.B PTRACE_EVENT_STOP
+and
+.I WSTOPSIG(status)
+returns the stop signal.
+Automatically attached children stop with
+.B PTRACE_EVENT_STOP
+and
+.I WSTOPSIG(status)
+returns
+.B SIGTRAP
+instead of having
+.B SIGSTOP
+signal delivered to them.
+.BR evecve (2)
+does not deliver an extra
+.BR SIGTRAP .
Only a
.BR PTRACE_SEIZE d
process can accept
and
.B PTRACE_LISTEN
commands.
+The "seized" behavior just described is inherited by
+children that are automatically attached using
+.BR PTRACE_O_TRACEFORK ,
+.BR PTRACE_O_TRACEVFORK ,
+and
+.BR PTRACE_O_TRACECLONE .
.I addr
must be zero.
.I data
.BR exit (2),
.BR exit_group (2),
and signal deaths (except
-.BR SIGKILL ),
+.BR SIGKILL ,
+depending on the kernel version; see BUGS below),
and when threads are torn down on
.BR execve (2)
in a multithreaded process.
/* r can still be 0 here! */
}
.fi
-.\" FIXME:
+.\" FIXME .
.\" waitid usage? WNOWAIT?
.\" describe how wait notifications queue (or not queue)
.LP
.LP
Note that a suppressed signal still causes system calls to return
prematurely.
-In this case system calls will be restarted: the tracer will
+In this case, system calls will be restarted: the tracer will
observe the tracee to reexecute the interrupted system call (or
.BR restart_syscall (2)
-system call for a few syscalls which use a different mechanism
+system call for a few system calls which use a different mechanism
for restarting) if the tracer uses
.BR PTRACE_SYSCALL .
Even system calls (such as
.BR poll (2))
which are not restartable after signal are restarted after
signal is suppressed;
-however, kernel bugs exist which cause some syscalls to fail with
+however, kernel bugs exist which cause some system calls to fail with
.B EINTR
even though no observable signal is injected to the tracee.
.LP
killed the tracee.)
.LP
If tracee was attached using
-.IR PTRACE_SEIZE ,
+.BR PTRACE_SEIZE ,
group-stop is indicated by
.BR PTRACE_EVENT_STOP :
.IR "status>>16 == PTRACE_EVENT_STOP" .
.B PTRACE_INTERRUPT
command, or group-stop, or initial ptrace-stop when a new child is attached
(only if attached using
-.BR PTRACE_SEIZE ),
-or
-.B PTRACE_EVENT_STOP
-if
-.B PTRACE_SEIZE
-was used.
+.BR PTRACE_SEIZE ).
+.TP
+.B PTRACE_EVENT_SECCOMP
+Stop triggered by a
+.BR seccomp (2)
+rule on tracee syscall entry when
+.BR PTRACE_O_TRACESECCOMP
+has been set by the tracer.
+The seccomp event message data (from the
+.BR SECCOMP_RET_DATA
+portion of the seccomp filter rule) can be retrieved with
+.BR PTRACE_GETEVENTMSG .
.LP
.B PTRACE_GETSIGINFO
on
.SS PTRACE_SINGLESTEP, PTRACE_SYSEMU, PTRACE_SYSEMU_SINGLESTEP stops
[Details of these kinds of stops are yet to be documented.]
.\"
-.\" FIXME
+.\" FIXME .
.\" document stops occurring with PTRACE_SINGLESTEP, PTRACE_SYSEMU,
.\" PTRACE_SYSEMU_SINGLESTEP
.SS Informational and restarting ptrace commands
.B SIGSTOP
may be lost.
.\"
-.\" FIXME: Describe how to attach to a thread which is already
-.\" group-stopped.
+.\" FIXME . Describe how to attach to a thread which is already group-stopped.
.LP
Since attaching sends
.B SIGSTOP
the tracee is not already ptrace-stopped,
because no signal delivery happens while it is\(emnot even
.BR SIGSTOP .
-.\" FIXME: Describe how to detach from a group-stopped tracee so that it
+.\" FIXME . Describe how to detach from a group-stopped tracee so that it
.\" doesn't run, but continues to wait for SIGCONT.
.LP
If the tracer dies, all tracees are automatically detached and restarted,
In this stop, the tracer can use
.B PTRACE_GETEVENTMSG
to retrieve the tracee's former thread ID.
-(This feature was introduced in Linux 3.0).
+(This feature was introduced in Linux 3.0.)
Second, the
.B PTRACE_O_TRACEEXEC
option disables legacy
.B PTRACE_O_TRACEEXEC
option is
.I not
-in effect for the execing tracee, the kernel delivers an extra
+in effect for the execing tracee,
+and if the tracee was
+.BR PTRACE_ATTACH ed
+rather that
+.BR PTRACE_SEIZE d,
+the kernel delivers an extra
.B SIGTRAP
to the tracee after
.BR execve (2)
to suppress is not easy.
Setting the
.B PTRACE_O_TRACEEXEC
-option and thus suppressing this extra
+option or using
+.B PTRACE_SEIZE
+and thus suppressing this extra
.B SIGTRAP
is the recommended approach.
.SS Real parent
If the tracer and the real parent are the same process,
the report is sent only once.
.SH RETURN VALUE
-On success,
-.B PTRACE_PEEK*
-requests return the requested data, while other requests return zero.
-(On Linux, this is done in the libc wrapper around ptrace system call.
-On the system call level,
+On success, the
.B PTRACE_PEEK*
-requests have a different API: they store the result
-at the address specified by
-.I data
-parameter, and return value is the error flag.)
+requests return the requested data (but see NOTES),
+while other requests return zero.
.LP
On error, all requests return \-1, and
.I errno
set-user-ID/set-group-ID programs, for obvious reasons.
Alternatively, the process may already be being traced,
or (on kernels before 2.6.26) be
-.BR init (8)
+.BR init (1)
(PID 1).
.TP
.B ESRCH
.LP
In Linux kernels before 2.6.26,
.\" See commit 00cd5c37afd5f431ac186dd131705048c0a11fdb
-.BR init (8),
+.BR init (1),
the process with PID 1, may not be traced.
.LP
+A tracees parent continues to be the tracer even if that tracer calls
+.BR execve (2).
+.LP
The layout of the contents of memory and the USER area are
quite operating-system- and architecture-specific.
The offset supplied, and the data returned,
This page documents the way the
.BR ptrace ()
call works currently in Linux.
-Its behavior differs noticeably on other flavors of UNIX.
+Its behavior differs significantly on other flavors of UNIX.
In any case, use of
.BR ptrace ()
is highly specific to the operating system and architecture.
+.SS C library/kernel differences
+At the system call level, the
+.BR PTRACE_PEEKTEXT ,
+.BR PTRACE_PEEKDATA ,
+and
+.BR PTRACE_PEEKUSER
+requests have a different API: they store the result
+at the address specified by the
+.I data
+parameter, and the return value is the error flag.
+The glibc wrapper function provides the API given in DESCRIPTION above,
+with the result being returned via the function return value.
.SH BUGS
On hosts with 2.6 kernel headers,
.B PTRACE_SETOPTIONS
.B PTRACE_DETACH
the thread group leader instead of restarting it in this case.
Last confirmed on 2.6.38.6.
-.\" FIXME: ^^^ need to test/verify this scenario
+.\" FIXME . need to test/verify this scenario
.LP
A
.B SIGKILL
This may be changed in the future;
.B SIGKILL
is meant to always immediately kill tasks even under ptrace.
-Last confirmed on 2.6.38.6.
+Last confirmed on Linux 3.13.
.LP
Some system calls return with
.B EINTR
The usual symptom of this bug is that when you attach to
a quiescent process with the command
- strace -p <process-ID>
+ strace
\-p <process-ID>
then, instead of the usual
and expected one-line output such as
.BR execve (2),
.BR fork (2),
.BR gettid (2),
+.BR seccomp (2),
.BR sigaction (2),
.BR tgkill (2),
.BR vfork (2),
projects / thirdparty / man-pages.git / blobdiff