NAME

       seccomp_notify_alloc, seccomp_notify_free, seccomp_notify_receive, seccomp_notify_respond,
       seccomp_notify_id_valid, seccomp_notify_fd - Manage seccomp notifications

SYNOPSIS

       #include <seccomp.h>

       int seccomp_notify_alloc(struct seccomp_notif **req, struct seccomp_notif_resp **resp)
       void seccomp_notify_free(struct seccomp_notif *req, struct seccomp_notif_resp *resp)
       int seccomp_notify_receive(int fd, struct seccomp_notif *req)
       int seccomp_notify_respond(int fd, struct seccomp_notif_resp *resp)
       int seccomp_notify_id_valid(int fd, uint64_t id)
       int seccomp_notify_fd(const scmp_filter_ctx ctx)

       Link with -lseccomp.

DESCRIPTION

       The 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  seccomp_notify_free()  function  frees  memory
       allocated by seccomp_notify_alloc().

       The  seccomp_notify_receive()  function  receives  a notification from a seccomp notify fd
       (obtained from seccomp_notify_fd()).

       The 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.

       The 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.

       The seccomp_notify_fd() returns the notification fd of a filter after it has been loaded.

RETURN VALUE

       The 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.

       The seccomp_notify_id_valid() returns 0 if the id is valid, and -ENOENT if it is not.

       The   seccomp_notify_alloc(),   seccomp_notify_receive(),   and   seccomp_notify_respond()
       functions return zero on success,  or one of the following error codes on failure:

       -ECANCELED
              There was a system failure beyond the control of the library, check the errno value
              for more information.

       -EFAULT
              Internal libseccomp failure.

       -ENOMEM
              The library was unable to allocate enough memory.

       -EOPNOTSUPP
              The library doesn't support the particular operation.

NOTES

       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
       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.

       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.

       A complete example of how to avoid these two races is available in the Linux Kernel source
       tree at /samples/seccomp/user-trap.c.

AUTHOR

       Tycho Andersen <tycho@tycho.ws>