docs: add man pages for seccomp_notif_* functions

Here's some basic documentation for the seccomp_notif_* family of
functions. I put them all on the same page because that seems to make the
most sense; they'll all be used together.

Signed-off-by: Tycho Andersen <[email protected]>

doc/man/man3/seccomp_notif_alloc.3

@@ -0,0 +1,105 @@
+.TH "seccomp_notif_alloc" 3 "24 April 2019" "[email protected]" "libseccomp Documentation"
+.\" //////////////////////////////////////////////////////////////////////////
+.SH NAME
+.\" //////////////////////////////////////////////////////////////////////////
+seccomp_notif_alloc, seccomp_notif_free, seccomp_notif_receive,
+seccomp_notif_send_resp, seccomp_notif_id_valid, seccomp_notif_fd \- Manage seccomp notifications
+.\" //////////////////////////////////////////////////////////////////////////
+.SH SYNOPSIS
+.\" //////////////////////////////////////////////////////////////////////////
+.nf
+.B #include <seccomp.h>
+.sp
+.BI "int seccomp_notif_alloc(struct seccomp_notif **" req ", struct seccomp_notif_resp **" resp ")"
+.BI "void seccomp_notif_free(struct seccomp_notif *" req ", struct seccomp_notif_resp *" resp ")"
+.BI "int seccomp_notif_receive(int " fd ", struct seccomp_notif *" req ")"
+.BI "int seccomp_notif_send_resp(int " fd ", struct seccomp_notif_resp *" resp ")"
+.BI "int seccomp_notif_id_valid(int " fd ", uint64_t " id ")"
+.BI "int seccomp_notif_fd(const scmp_filter_ctx " ctx ")"
+.sp
+Link with \fI\-lseccomp\fP.
+.fi
+.\" //////////////////////////////////////////////////////////////////////////
+.SH DESCRIPTION
+.\" //////////////////////////////////////////////////////////////////////////
+.P
+The
+.BR seccomp_notif_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 kerenl how big each structure
+should be, and allocates the right amount of memory. The
+.BR seccomp_notif_free ()
+function frees memory allocated by
+.BR seccomp_notif_alloc ().
+.P
+The
+.BR seccomp_notif_receive ()
+function receives a notification from a seccomp notify fd (obtained from
+.BR seccomp_notif_fd ()).
+.P
+The
+.BR seccomp_notif_send_resp ()
+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_notif_id_valid ()
+function checks to see if the syscall from a particualr 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_notif_fd ()
+returns the notification fd of a filter after it has been loaded. Note that one
+must set the
+.BR SCMP_FLTATR_NEW_LISTENER
+attribute and have loaded the filter, or this function returns an error.
+.\" //////////////////////////////////////////////////////////////////////////
+.SH RETURN VALUE
+.\" //////////////////////////////////////////////////////////////////////////
+.P
+The
+.BR seccomp_notif_alloc (),
+.BR seccomp_notif_receive (),
+and
+.BR seccomp_notif_send_resp ()
+functions all return 0 on success, -1 on failure.
+.P
+The
+.BR seccomp_notif_id_valid ()
+returns 0 if the id is valid, and -ENOENT if it is not.
+.P
+The
+.BR seccomp_notif_fd ()
+returns the notification fd of a filter that was loaded with the
+.BR SCMP_FLTATR_NEW_LISTENER
+attribute set.
+.\" //////////////////////////////////////////////////////////////////////////
+.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_notif_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 a
+.BR /samples/seccomp/user-trap.c.
+.\" //////////////////////////////////////////////////////////////////////////
+.SH AUTHOR
+.\" //////////////////////////////////////////////////////////////////////////
+Tycho Andersen <[email protected]>
+.\" //////////////////////////////////////////////////////////////////////////

doc/man/man3/seccomp_notif_fd.3

@@ -0,0 +1 @@
+.so man3/seccomp_notif_alloc.3

doc/man/man3/seccomp_notif_free.3

@@ -0,0 +1 @@
+.so man3/seccomp_notif_alloc.3

doc/man/man3/seccomp_notif_id_valid.3

@@ -0,0 +1 @@
+.so man3/seccomp_notif_alloc.3

doc/man/man3/seccomp_notif_receive.3

@@ -0,0 +1 @@
+.so man3/seccomp_notif_alloc.3

doc/man/man3/seccomp_notif_send_resp.3

@@ -0,0 +1 @@
+.so man3/seccomp_notif_alloc.3