doc/man/man3/seccomp_notify_alloc.3 - main - githubmirror/libseccomp

doc/man/man3/seccomp_notify_alloc.3
124 строки5 KB
Sudipta Pandit
api: add the seccomp notify addfd support
08 апр 2026, 21:48
08 апр 2026, 21:486e12822
.TH "seccomp_notify_alloc" 3 "30 May 2020" "tycho@tycho.ws" "libseccomp Documentation"
.\" //////////////////////////////////////////////////////////////////////////
.SH NAME
.\" //////////////////////////////////////////////////////////////////////////
seccomp_notify_alloc, seccomp_notify_free, seccomp_notify_receive,
seccomp_notify_respond, seccomp_notify_id_valid, seccomp_notify_fd, seccomp_notify_addfd \- Manage seccomp notifications
.\" //////////////////////////////////////////////////////////////////////////
.SH SYNOPSIS
.\" //////////////////////////////////////////////////////////////////////////
.nf
.B #include <seccomp.h>
.sp
.BI "int seccomp_notify_alloc(struct seccomp_notif **" req ", struct seccomp_notif_resp **" resp ")"
.BI "void seccomp_notify_free(struct seccomp_notif *" req ", struct seccomp_notif_resp *" resp ")"
.BI "int seccomp_notify_receive(int " fd ", struct seccomp_notif *" req ")"
.BI "int seccomp_notify_respond(int " fd ", struct seccomp_notif_resp *" resp ")"
.BI "int seccomp_notify_id_valid(int " fd ", uint64_t " id ")"
.BI "int seccomp_notify_fd(const scmp_filter_ctx " ctx ")"
.BI "int seccomp_notify_addfd(int " fd ", struct seccomp_notif_addfd *" addfd ")"
.sp
Link with \fI\-lseccomp\fP.
.fi
.\" //////////////////////////////////////////////////////////////////////////
.SH DESCRIPTION
.\" //////////////////////////////////////////////////////////////////////////
.P
The
.BR seccomp_notify_alloc ()
function dynamically allocates enough memory for a seccomp notification and
response. Note that one should always use these functions and not depend on the
structure sizes in headers, since the size can vary depending on the kernel
version. This function takes care to ask the kernel how big each structure
should be, and allocates the right amount of memory. The
.BR seccomp_notify_free ()
function frees memory allocated by
.BR seccomp_notify_alloc ().
.P
The
.BR seccomp_notify_receive ()
function receives a notification from a seccomp notify fd (obtained from
.BR seccomp_notify_fd ()).
.P
The
.BR seccomp_notify_respond ()
function sends a response to a particular notification. The id field should be
the same as the id from the request, so that the kernel knows which request
this response corresponds to.
.P
The
.BR seccomp_notify_id_valid ()
function checks to see if the syscall from a particular notification request is
still valid, i.e. if the task is still alive. See NOTES below for details on
race conditions.
.P
The
.BR seccomp_notify_fd ()
returns the notification fd of a filter after it has been loaded.
.P
The
.BR seccomp_notify_addfd ()
function enables the caller to install a file descriptor into the target's file descriptor table.
The id field of the struct should be the same as the id from the request.
.\" //////////////////////////////////////////////////////////////////////////
.SH RETURN VALUE
.\" //////////////////////////////////////////////////////////////////////////
The
.BR seccomp_notify_fd ()
returns the notification fd of the loaded filter, -1 if a notification fd has
not yet been created, and -EINVAL if the filter context is invalid.
.P
The
.BR seccomp_notify_id_valid ()
returns 0 if the id is valid, and -ENOENT if it is not.
.P
The
.BR seccomp_notify_addfd ()
returns the installed fd number on success, and one of error codes mentioned below on failure.
.P
The
.BR seccomp_notify_alloc (),
.BR seccomp_notify_receive (),
and
.BR seccomp_notify_respond ()
functions return zero on success,  or one of the following error codes on
failure:
.TP
.B -ECANCELED
There was a system failure beyond the control of the library, check the
\fIerrno\fP value for more information.
.TP
.B -EFAULT
Internal libseccomp failure.
.TP
.B -ENOMEM
The library was unable to allocate enough memory.
.TP
.B -EOPNOTSUPP
The library doesn't support the particular operation.
.\" //////////////////////////////////////////////////////////////////////////
.SH NOTES
.\" //////////////////////////////////////////////////////////////////////////
.P
Care should be taken to avoid two different time of check/time of use errors.
First, after opening any resources relevant to the pid for a notification (e.g.
/proc/pid/mem for reading tracee memory to make policy decisions), applications
should call
.BR seccomp_notify_id_valid ()
to make sure that the resources the application has opened correspond to the
right pid, i.e. that the pid didn't die and a different task take its place.
.P
Second, the classic time of check/time of use issue with seccomp memory should
also be avoided: applications should copy any memory they wish to use to make
decisions from the tracee into its own address space before applying any policy
decisions, since a multi-threaded tracee may edit the memory at any time,
including after it's used to make a policy decision.
.P
A complete example of how to avoid these two races is available in the Linux
Kernel source tree at
.BR /samples/seccomp/user-trap.c.
.\" //////////////////////////////////////////////////////////////////////////
.SH AUTHOR
.\" //////////////////////////////////////////////////////////////////////////
Tycho Andersen <tycho@tycho.ws>
.\" //////////////////////////////////////////////////////////////////////////