.\" 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 2014-02-20 "Linux" "Linux Programmer's Manual"
+.TH PTRACE 2 2015-01-22 "Linux" "Linux Programmer's Manual"
.SH NAME
ptrace \- process trace
.SH SYNOPSIS
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.)
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 .
.RE
.TP
.BR PTRACE_GETEVENTMSG " (since Linux 2.5.46)"
and
.BR PTRACE_EVENT_CLONE ,
this is the PID of the new process.
+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
/* r can still be 0 here! */
}
.fi
-.\" FIXME:
+.\" FIXME .
.\" waitid usage? WNOWAIT?
.\" describe how wait notifications queue (or not queue)
.LP
if
.B PTRACE_SEIZE
was used.
+.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,
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
or
.IR "(void\ *)\ 0".
.LP
-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.
-.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
The layout of the contents of memory and the USER area are
In any case, use of
.BR ptrace ()
is highly specific to the operating system and architecture.
+.SS C library/kernel ABI 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
.BR execve (2),
.BR fork (2),
.BR gettid (2),
+.BR seccomp (2),
.BR sigaction (2),
.BR tgkill (2),
.BR vfork (2),
.BR capabilities (7),
.BR signal (7)
.SH COLOPHON
-This page is part of release 3.68 of the Linux
+This page is part of release 3.79 of the Linux
.I man-pages
project.
A description of the project,