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>