all: add seccomp_precompute() functionality

This patch adds a seccomp_precompute() API to precompute the seccomp
filter prior to calling seccomp_load() or similar functions.  Not
only does this improve the performance of seccomp_load(), it ensures
that seccomp_load() is async-signal-safe if no additional changes
have been made since the filter was precomputed.

Python bindings, test, and manpage updates are included in this
patch.

One minor side effect of this change is that seccomp_export_bpf_mem()
now always return the length of the filter in the "len" function
parameter, even in cases where the passed buffer is too small.
Arguably seccomp_export_bpf_mem() should have always behaved this
way.

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

3 files changed, 112 insertions, 3 deletions

diff --git a/doc/Makefile.am b/doc/Makefile.am
index a21d4c8..2eff0ad 100644
--- a/doc/Makefile.am
+++ b/doc/Makefile.am
@@ -33,6 +33,7 @@ dist_man3_MANS = \
 	man/man3/seccomp_init.3 \
 	man/man3/seccomp_load.3 \
 	man/man3/seccomp_merge.3 \
+	man/man3/seccomp_precompute.3 \
 	man/man3/seccomp_release.3 \
 	man/man3/seccomp_reset.3 \
 	man/man3/seccomp_rule_add.3 \
diff --git a/doc/man/man3/seccomp_load.3 b/doc/man/man3/seccomp_load.3
index 729f73e..d0d43eb 100644
--- a/doc/man/man3/seccomp_load.3
+++ b/doc/man/man3/seccomp_load.3
@@ -22,7 +22,12 @@ Link with \fI\-lseccomp\fP.
 Loads the seccomp filter provided by
 .I ctx
 into the kernel; if the function
-succeeds the new seccomp filter will be active when the function returns.
+succeeds the new seccomp filter will be active when the function returns.  If
+.BR seccomp_precompute (3)
+was called prior to attempting to load the seccomp filter, and no changes have
+been made to the filter,
+.BR seccomp_load ()
+can be considered to be async-signal-safe.
 .P
 As it is possible to have multiple stacked seccomp filters for a given task
 (defined as either a process or a thread), it is important to remember that
@@ -108,5 +113,5 @@ Paul Moore <paul@paul-moore.com>
 .BR seccomp_release (3),
 .BR seccomp_rule_add (3),
 .BR seccomp_rule_add_exact (3)
-
-
+.BR seccomp_precompute (3)
+.BR signal-safety (7)
diff --git a/doc/man/man3/seccomp_precompute.3 b/doc/man/man3/seccomp_precompute.3
new file mode 100644
index 0000000..b82bd0a
--- /dev/null
+++ b/doc/man/man3/seccomp_precompute.3
@@ -0,0 +1,103 @@
+.TH "seccomp_precompute" 3 "19 September 2022" "paul@paul-moore.com" "libseccomp Documentation"
+.\" //////////////////////////////////////////////////////////////////////////
+.SH NAME
+.\" //////////////////////////////////////////////////////////////////////////
+seccomp_precompute \- Precompute the current seccomp filter
+.\" //////////////////////////////////////////////////////////////////////////
+.SH SYNOPSIS
+.\" //////////////////////////////////////////////////////////////////////////
+.nf
+.B #include <seccomp.h>
+.sp
+.B typedef void * scmp_filter_ctx;
+.sp
+.BI "int seccomp_precompute(scmp_filter_ctx " ctx ");"
+.sp
+Link with \fI\-lseccomp\fP.
+.fi
+.\" //////////////////////////////////////////////////////////////////////////
+.SH DESCRIPTION
+.\" //////////////////////////////////////////////////////////////////////////
+.P
+Precomputes the seccomp filter for later use by
+.BR seccomp_load ()
+and similar functions.  Not only does this improve performance of
+.BR seccomp_load ()
+it also ensures that the seccomp filter can be loaded in an async-signal-safe
+manner if no changes have been made to the filter since it was precomputed.
+.\" //////////////////////////////////////////////////////////////////////////
+.SH RETURN VALUE
+.\" //////////////////////////////////////////////////////////////////////////
+Returns zero on success or one of the following error codes on failure:
+.TP
+.B -ECANCELED
+There was a system failure beyond the control of the library.
+.TP
+.B -EFAULT
+Internal libseccomp failure.
+.TP
+.B -EINVAL
+Invalid input, either the context or architecture token is invalid.
+.TP
+.B -ENOMEM
+The library was unable to allocate enough memory.
+.P
+If the \fISCMP_FLTATR_API_SYSRAWRC\fP filter attribute is non-zero then
+additional error codes may be returned to the caller; these additional error
+codes are the negative \fIerrno\fP values returned by the system.  Unfortunately
+libseccomp can make no guarantees about these return values.
+.\" //////////////////////////////////////////////////////////////////////////
+.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_precompute(ctx);
+	if (rc < 0)
+		goto out;
+
+	/* ... */
+
+	rc = seccomp_load(ctx);
+	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_load (3)
+.BR signal-safety (7)