api: add the SCMP_FLTATR_API_SYSRAWRC filter attribute

See the manpage additions as part of this patch, but the basic idea
is that when this attribute is non-zero we make every effort to
convey the system's errno value back to the caller when something
goes wrong in libc or the kernel.  It is important to note from a
support perspective that our ability to support callers who make use
of this attribute will be diminished as the libc and kernel errno
values are beyond libseccomp's control.

If the attribute is zero, the library hides all of the system
failures under -ECANCELED.

Acked-by: Tom Hromatka <tom.hromatka@oracle.com>
Signed-off-by: Paul Moore <paul@paul-moore.com>

4 files changed, 23 insertions, 6 deletions

diff --git a/doc/man/man3/seccomp_attr_set.3 b/doc/man/man3/seccomp_attr_set.3
index a23d875..6183493 100644
--- a/doc/man/man3/seccomp_attr_set.3
+++ b/doc/man/man3/seccomp_attr_set.3
@@ -1,4 +1,4 @@
-.TH "seccomp_attr_set" 3 "30 May 2020" "paul@paul-moore.com" "libseccomp Documentation"
+.TH "seccomp_attr_set" 3 "06 June 2020" "paul@paul-moore.com" "libseccomp Documentation"
 .\" //////////////////////////////////////////////////////////////////////////
 .SH NAME
 .\" //////////////////////////////////////////////////////////////////////////
@@ -100,6 +100,12 @@ A flag to disable Speculative Store Bypass mitigations for this filter.
 Defaults to off (
 .I value
 == 0).
+.TP
+.B SCMP_FLTATR_API_SYSRAWRC
+A flag to specify if libseccomp should pass system error codes back to the
+caller instead of the default -ECANCELED.  Defaults to off (
+.I value
+== 0).
 .\" //////////////////////////////////////////////////////////////////////////
 .SH RETURN VALUE
 .\" //////////////////////////////////////////////////////////////////////////
diff --git a/doc/man/man3/seccomp_export_bpf.3 b/doc/man/man3/seccomp_export_bpf.3
index 68e735f..98b3572 100644
--- a/doc/man/man3/seccomp_export_bpf.3
+++ b/doc/man/man3/seccomp_export_bpf.3
@@ -49,7 +49,7 @@ Return zero on success or one of the following error codes on
 failure:
 .TP
 .B -ECANCELED
-There was a kernel failure beyond the control of the library.
+There was a system failure beyond the control of the library.
 .TP
 .B -EFAULT
 Internal libseccomp failure.
@@ -59,6 +59,11 @@ 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
 .\" //////////////////////////////////////////////////////////////////////////
diff --git a/doc/man/man3/seccomp_load.3 b/doc/man/man3/seccomp_load.3
index dcca7f5..8e2e6f0 100644
--- a/doc/man/man3/seccomp_load.3
+++ b/doc/man/man3/seccomp_load.3
@@ -39,7 +39,7 @@ is "stricter" than
 Returns zero on success or one of the following error codes on failure:
 .TP
 .B -ECANCELED
-There was a kernel failure beyond the control of the library.
+There was a system failure beyond the control of the library.
 .TP
 .B -EFAULT
 Internal libseccomp failure.
@@ -52,6 +52,11 @@ The library was unable to allocate enough memory.
 .TP
 .B -ESRCH
 Unable to load the filter due to thread issues.
+.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
 .\" //////////////////////////////////////////////////////////////////////////
diff --git a/doc/man/man3/seccomp_notify_alloc.3 b/doc/man/man3/seccomp_notify_alloc.3
index 48c4599..50c8970 100644
--- a/doc/man/man3/seccomp_notify_alloc.3
+++ b/doc/man/man3/seccomp_notify_alloc.3
@@ -47,7 +47,7 @@ this response corresponds to.
 .P
 The
 .BR seccomp_notify_id_valid ()
-function checks to see if the syscall from a particualr notification request is
+function checks to see if the syscall from a particular notification request is
 still valid, i.e. if the task is still alive. See NOTES below for details on
 race conditions.
 .P
@@ -70,11 +70,12 @@ The
 .BR seccomp_notify_receive (),
 and
 .BR seccomp_notify_respond ()
-functions return zero on success or one of the following error codes on
+functions return zero on success,  or one of the following error codes on
 failure:
 .TP
 .B -ECANCELED
-There was a kernel failure beyond the control of the library.
+There was a system failure beyond the control of the library, check the
+\fIerrno\fP value for more information.
 .TP
 .B -EFAULT
 Internal libseccomp failure.