1 files changed, 166 insertions, 0 deletions
diff --git a/doc/man/man3/seccomp_init.3 b/doc/man/man3/seccomp_init.3
new file mode 100644
index 0000000..ca6224c
--- /dev/null
+++ b/doc/man/man3/seccomp_init.3
@@ -0,0 +1,166 @@
+.TH "seccomp_init" 3 "30 May 2020" "paul@paul-moore.com" "libseccomp Documentation"
+.\" //////////////////////////////////////////////////////////////////////////
+.SH NAME
+.\" //////////////////////////////////////////////////////////////////////////
+seccomp_init, seccomp_reset \- Initialize the seccomp filter state
+.\" //////////////////////////////////////////////////////////////////////////
+.SH SYNOPSIS
+.\" //////////////////////////////////////////////////////////////////////////
+.nf
+.B #include <seccomp.h>
+.sp
+.B typedef void * scmp_filter_ctx;
+.sp
+.BI "scmp_filter_ctx seccomp_init(uint32_t " def_action ");"
+.BI "int seccomp_reset(scmp_filter_ctx " ctx ", uint32_t " def_action ");"
+.sp
+Link with \fI\-lseccomp\fP.
+.fi
+.\" //////////////////////////////////////////////////////////////////////////
+.SH DESCRIPTION
+.\" //////////////////////////////////////////////////////////////////////////
+.P
+The
+.BR seccomp_init ()
+and
+.BR seccomp_reset ()
+functions (re)initialize the internal seccomp filter state, prepares it for
+use, and sets the default action based on the
+.I def_action
+parameter.  The
+.BR seccomp_init ()
+function must be called before any other libseccomp functions as the rest
+of the library API will fail if the filter context is not initialized properly.
+The
+.BR seccomp_reset ()
+function releases the existing filter context state before reinitializing it
+and can only be called after a call to
+.BR seccomp_init ()
+has succeeded.  If
+.BR seccomp_reset ()
+is called with a NULL filter, it resets the library's global task state,
+including any notification file descriptors retrieved by
+.BR seccomp_notify_fd (3).
+Normally this is not needed, but it may be required to continue using the
+library after a
+.BR fork ()
+or
+.BR clone ()
+call to ensure the API level and user notification state is properly reset.
+.P
+When the caller is finished configuring the seccomp filter and has loaded it
+into the kernel, the caller should call
+.BR seccomp_release (3)
+to release all of the filter context state.
+.P
+Valid
+.I def_action
+values are as follows:
+.TP
+.B SCMP_ACT_KILL
+The thread will be terminated by the kernel with SIGSYS when it calls a syscall
+that does not match any of the configured seccomp filter rules.  The thread
+will not be able to catch the signal.
+.TP
+.B SCMP_ACT_KILL_PROCESS
+The entire process will be terminated by the kernel with SIGSYS when it calls a
+syscall that does not match any of the configured seccomp filter rules.
+.TP
+.B SCMP_ACT_TRAP
+The thread will be sent a SIGSYS signal when it calls a syscall that does not
+match any of the configured seccomp filter rules.  It may catch this and change
+its behavior accordingly.  When using SA_SIGINFO with
+.BR sigaction (2),
+si_code will be set to SYS_SECCOMP, si_syscall will be set to the syscall that
+failed the rules, and si_arch will be set to the AUDIT_ARCH for the active ABI.
+.TP
+.B SCMP_ACT_ERRNO(uint16_t errno)
+The thread will receive a return value of
+.I errno
+when it calls a syscall that does not match any of the configured seccomp filter
+rules.
+.TP
+.B SCMP_ACT_TRACE(uint16_t msg_num)
+If the thread is being traced and the tracing process specified the
+.B PTRACE_O_TRACESECCOMP
+option in the call to
+.BR ptrace (2),
+the tracing process will be notified, via
+.BR PTRACE_EVENT_SECCOMP ,
+and the value provided in
+.I msg_num
+can be retrieved using the
+.B PTRACE_GETEVENTMSG
+option.
+.TP
+.B SCMP_ACT_LOG
+The seccomp filter will have no effect on the thread calling the syscall if it
+does not match any of the configured seccomp filter rules but the syscall will
+be logged.
+.TP
+.B SCMP_ACT_ALLOW
+The seccomp filter will have no effect on the thread calling the syscall if it
+does not match any of the configured seccomp filter rules.
+.\" //////////////////////////////////////////////////////////////////////////
+.SH RETURN VALUE
+.\" //////////////////////////////////////////////////////////////////////////
+The
+.BR seccomp_init ()
+function returns a filter context on success, NULL on failure.  The
+.BR seccomp_reset ()
+function returns zero on success or one of the following error codes on
+failure:
+.TP
+.B -EINVAL
+Invalid input, either the context or action is invalid.
+.TP
+.B -ENOMEM
+The library was unable to allocate enough memory.
+.\" //////////////////////////////////////////////////////////////////////////
+.SH EXAMPLES
+.\" //////////////////////////////////////////////////////////////////////////
+.nf
+#include <seccomp.h>
+
+int main(int argc, char *argv[])
+{
+	int rc = \-1;
+	scmp_filter_ctx ctx;
+
+	ctx = seccomp_init(SCMP_ACT_KILL);
+	if (ctx == NULL)
+		goto out;
+
+	/* ... */
+
+	rc = seccomp_reset(ctx, SCMP_ACT_KILL);
+	if (rc < 0)
+		goto out;
+
+	/* ... */
+
+out:
+	seccomp_release(ctx);
+	return \-rc;
+}
+.fi
+.\" //////////////////////////////////////////////////////////////////////////
+.SH NOTES
+.\" //////////////////////////////////////////////////////////////////////////
+.P
+While the seccomp filter can be generated independent of the kernel, kernel
+support is required to load and enforce the seccomp filter generated by
+libseccomp.
+.P
+The libseccomp project site, with more information and the source code
+repository, can be found at https://github.com/seccomp/libseccomp.  This tool,
+as well as the libseccomp library, is currently under development, please
+report any bugs at the project site or directly to the author.
+.\" //////////////////////////////////////////////////////////////////////////
+.SH AUTHOR
+.\" //////////////////////////////////////////////////////////////////////////
+Paul Moore <paul@paul-moore.com>
+.\" //////////////////////////////////////////////////////////////////////////
+.SH SEE ALSO
+.\" //////////////////////////////////////////////////////////////////////////
+.BR seccomp_release (3)