api: create an API level construct as part of the supported API

This patch adds the concept of "API levels" which are a way of
indicating what functionality is supported at runtime.  There are two
new API functions added, as explained by the manpage:

 "The seccomp_api_get() function returns an integer representing the
  functionality ("API level") provided by the current running kernel.
  It is important to note that while seccomp_api_get() can be called
  multiple times, the kernel is only probed the first time to see
  what functionality is supported, all following calls to
  seccomp_api_get() return a cached value.

  The seccomp_api_set() function allows callers to force the API
  level to the provided value; however, this is almost always a bad
  idea and use of this function is strongly discouraged."

Signed-off-by: Paul Moore <paul@paul-moore.com>

3 files changed, 102 insertions, 1 deletions

diff --git a/doc/Makefile.am b/doc/Makefile.am
index 872d089..a37a32b 100644
--- a/doc/Makefile.am
+++ b/doc/Makefile.am
@@ -43,4 +43,6 @@ dist_man3_MANS = \
 	man/man3/seccomp_syscall_resolve_name_arch.3 \
 	man/man3/seccomp_syscall_resolve_name_rewrite.3 \
 	man/man3/seccomp_syscall_resolve_num_arch.3 \
-	man/man3/seccomp_version.3
+	man/man3/seccomp_version.3 \
+	man/man3/seccomp_api_get.3 \
+	man/man3/seccomp_api_set.3
diff --git a/doc/man/man3/seccomp_api_get.3 b/doc/man/man3/seccomp_api_get.3
new file mode 100644
index 0000000..a209dcc
--- /dev/null
+++ b/doc/man/man3/seccomp_api_get.3
@@ -0,0 +1,98 @@
+.TH "seccomp_api_get" 3 "8 October 2017" "paul@paul-moore.com" "libseccomp Documentation"
+.\" //////////////////////////////////////////////////////////////////////////
+.SH NAME
+.\" //////////////////////////////////////////////////////////////////////////
+seccomp_api_get, seccomp_api_set \- Manage the libseccomp API level
+.\" //////////////////////////////////////////////////////////////////////////
+.SH SYNOPSIS
+.\" //////////////////////////////////////////////////////////////////////////
+.nf
+.B #include <seccomp.h>
+.sp
+.BI "const unsigned int seccomp_api_get(" void ");"
+.BI "int seccomp_api_set(unsigned int " level ");"
+.sp
+Link with \fI\-lseccomp\fP.
+.fi
+.\" //////////////////////////////////////////////////////////////////////////
+.SH DESCRIPTION
+.\" //////////////////////////////////////////////////////////////////////////
+.P
+The
+.BR seccomp_api_get ()
+function returns an integer representing the functionality ("API level")
+provided by the current running kernel.  It is important to note that while
+.BR seccomp_api_get ()
+can be called multiple times, the kernel is only probed the first time to see
+what functionality is supported, all following calls to
+.BR seccomp_api_get ()
+return a cached value.
+.P
+The
+.BR seccomp_api_set ()
+function allows callers to force the API level to the provided value; however,
+this is almost always a bad idea and use of this function is strongly
+discouraged.
+.P
+The different API level values are described below:
+.TP
+.B 0
+Reserved value, not currently used.
+.TP
+.B 1
+Base level support.
+.TP
+.B 2
+The SCMP_FLTATR_CTL_TSYNC filter attribute is supported and libseccomp uses
+the
+.BR seccomp(2)
+syscall to load the seccomp filter into the kernel.
+.\" //////////////////////////////////////////////////////////////////////////
+.SH RETURN VALUE
+.\" //////////////////////////////////////////////////////////////////////////
+The
+.BR seccomp_api_get ()
+function returns an integer representing the supported API level.  The
+.BR seccomp_api_set ()
+function returns zero on success, negative values on failure.
+.\" //////////////////////////////////////////////////////////////////////////
+.SH EXAMPLES
+.\" //////////////////////////////////////////////////////////////////////////
+.nf
+#include <seccomp.h>
+
+int main(int argc, char *argv[])
+{
+	unsigned int api;
+
+	api = seccomp_api_get();
+	switch (api) {
+	case 2:
+		/* ... */
+	default:
+		/* ... */
+	}
+
+	return 0;
+
+err:
+	return \-1;
+}
+.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>
+.\" //////////////////////////////////////////////////////////////////////////
diff --git a/doc/man/man3/seccomp_api_set.3 b/doc/man/man3/seccomp_api_set.3
new file mode 100644
index 0000000..6ed16f8
--- /dev/null
+++ b/doc/man/man3/seccomp_api_set.3
@@ -0,0 +1 @@
+.so man3/seccomp_api_get.3