From e89d18205c7dcd7582f41051cd6389c9b12dfccf Mon Sep 17 00:00:00 2001 From: Paul Moore Date: Thu, 21 Sep 2017 10:27:38 -0400 Subject: 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 --- doc/Makefile.am | 4 +- doc/man/man3/seccomp_api_get.3 | 98 ++++++++++++++++++++++++++++++++++++++++++ doc/man/man3/seccomp_api_set.3 | 1 + 3 files changed, 102 insertions(+), 1 deletion(-) create mode 100644 doc/man/man3/seccomp_api_get.3 create mode 100644 doc/man/man3/seccomp_api_set.3 (limited to 'doc') 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 +.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 + +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 +.\" ////////////////////////////////////////////////////////////////////////// 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 -- cgit v1.2.1