doc: update the manpages with return code information

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

9 files changed, 162 insertions, 29 deletions

diff --git a/doc/man/man3/seccomp_arch_add.3 b/doc/man/man3/seccomp_arch_add.3
index 21b962e..7baa21e 100644
--- a/doc/man/man3/seccomp_arch_add.3
+++ b/doc/man/man3/seccomp_arch_add.3
@@ -86,13 +86,28 @@ new architecture will be added to all of the architectures in the filter.
 .SH RETURN VALUE
 .\" //////////////////////////////////////////////////////////////////////////
 The
-.BR seccomp_arch_add ()
+.BR seccomp_arch_add (),
+.BR seccomp_arch_remove (),
 and
-.BR seccomp_arch_remove ()
-functions return zero on success, negative errno values on failure.  The
 .BR seccomp_arch_exist ()
-function returns zero if the architecture exists, \-EEXIST if it does not, and
-other negative errno values on failure.
+functions return zero on success or one of the following error codes on
+failure:
+.TP
+.B -EDOM
+Architecture specific failure.
+.TP
+.B -EEXIST
+In the case of
+.BR seccomp_arch_add ()
+the architecture already exists and in the case of
+.BR seccomp_arch_remove ()
+the architecture does not exist.
+.TP
+.B -EINVAL
+Invalid input, either the context or architecture token is invalid.
+.TP
+.B -ENOMEM
+The library was unable to allocate enough memory.
 .\" //////////////////////////////////////////////////////////////////////////
 .SH EXAMPLES
 .\" //////////////////////////////////////////////////////////////////////////
diff --git a/doc/man/man3/seccomp_attr_set.3 b/doc/man/man3/seccomp_attr_set.3
index c66668d..a23d875 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 "21 August 2014" "paul@paul-moore.com" "libseccomp Documentation"
+.TH "seccomp_attr_set" 3 "30 May 2020" "paul@paul-moore.com" "libseccomp Documentation"
 .\" //////////////////////////////////////////////////////////////////////////
 .SH NAME
 .\" //////////////////////////////////////////////////////////////////////////
@@ -103,7 +103,20 @@ Defaults to off (
 .\" //////////////////////////////////////////////////////////////////////////
 .SH RETURN VALUE
 .\" //////////////////////////////////////////////////////////////////////////
-Returns zero on success, negative errno values on failure.
+Returns zero on success or one of the following error codes on
+failure:
+.TP
+.B -EACCES
+Setting the attribute with the given value is not allowed.
+.TP
+.B -EEXIST
+The attribute does not exist.
+.TP
+.B -EINVAL
+Invalid input, either the context or architecture token is invalid.
+.TP
+.B -EOPNOTSUPP
+The library doesn't support the particular operation.
 .\" //////////////////////////////////////////////////////////////////////////
 .SH EXAMPLES
 .\" //////////////////////////////////////////////////////////////////////////
diff --git a/doc/man/man3/seccomp_export_bpf.3 b/doc/man/man3/seccomp_export_bpf.3
index 613a110..bb0627c 100644
--- a/doc/man/man3/seccomp_export_bpf.3
+++ b/doc/man/man3/seccomp_export_bpf.3
@@ -1,4 +1,4 @@
-.TH "seccomp_export_bpf" 3 "25 July 2012" "paul@paul-moore.com" "libseccomp Documentation"
+.TH "seccomp_export_bpf" 3 "30 May 2020" "paul@paul-moore.com" "libseccomp Documentation"
 .\" //////////////////////////////////////////////////////////////////////////
 .SH NAME
 .\" //////////////////////////////////////////////////////////////////////////
@@ -45,7 +45,17 @@ ordering, are not guaranteed to be the same in both the BPF and PFC formats.
 .\" //////////////////////////////////////////////////////////////////////////
 .SH RETURN VALUE
 .\" //////////////////////////////////////////////////////////////////////////
-Returns zero on success, negative errno values on failure.
+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.
+.TP
+.B -EINVAL
+Invalid input, either the context or architecture token is invalid.
+.TP
+.B -ENOMEM
+The library was unable to allocate enough memory.
 .\" //////////////////////////////////////////////////////////////////////////
 .SH EXAMPLES
 .\" //////////////////////////////////////////////////////////////////////////
diff --git a/doc/man/man3/seccomp_init.3 b/doc/man/man3/seccomp_init.3
index ad1371f..3ab68fe 100644
--- a/doc/man/man3/seccomp_init.3
+++ b/doc/man/man3/seccomp_init.3
@@ -1,4 +1,4 @@
-.TH "seccomp_init" 3 "25 July 2012" "paul@paul-moore.com" "libseccomp Documentation"
+.TH "seccomp_init" 3 "30 May 2020" "paul@paul-moore.com" "libseccomp Documentation"
 .\" //////////////////////////////////////////////////////////////////////////
 .SH NAME
 .\" //////////////////////////////////////////////////////////////////////////
@@ -98,7 +98,14 @@ The
 .BR seccomp_init ()
 function returns a filter context on success, NULL on failure.  The
 .BR seccomp_reset ()
-function returns zero on success, negative errno values on failure.
+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
 .\" //////////////////////////////////////////////////////////////////////////
diff --git a/doc/man/man3/seccomp_load.3 b/doc/man/man3/seccomp_load.3
index fb40660..15ace53 100644
--- a/doc/man/man3/seccomp_load.3
+++ b/doc/man/man3/seccomp_load.3
@@ -1,4 +1,4 @@
-.TH "seccomp_load" 3 "25 July 2012" "paul@paul-moore.com" "libseccomp Documentation"
+.TH "seccomp_load" 3 "30 May 2020" "paul@paul-moore.com" "libseccomp Documentation"
 .\" //////////////////////////////////////////////////////////////////////////
 .SH NAME
 .\" //////////////////////////////////////////////////////////////////////////
@@ -36,7 +36,19 @@ is "stricter" than
 .\" //////////////////////////////////////////////////////////////////////////
 .SH RETURN VALUE
 .\" //////////////////////////////////////////////////////////////////////////
-Returns zero on success, negative errno values on failure.
+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.
+.TP
+.B -EINVAL
+Invalid input, either the context or architecture token is invalid.
+.TP
+.B -ENOMEM
+The library was unable to allocate enough memory.
+.TP
+.B -ESRCH
+Unable to load the filter due to thread issues.
 .\" //////////////////////////////////////////////////////////////////////////
 .SH EXAMPLES
 .\" //////////////////////////////////////////////////////////////////////////
diff --git a/doc/man/man3/seccomp_merge.3 b/doc/man/man3/seccomp_merge.3
index d580ab5..10b3c3f 100644
--- a/doc/man/man3/seccomp_merge.3
+++ b/doc/man/man3/seccomp_merge.3
@@ -1,4 +1,4 @@
-.TH "seccomp_merge" 3 "28 September 2012" "paul@paul-moore.com" "libseccomp Documentation"
+.TH "seccomp_merge" 3 "30 May 2020" "paul@paul-moore.com" "libseccomp Documentation"
 .\" //////////////////////////////////////////////////////////////////////////
 .SH NAME
 .\" //////////////////////////////////////////////////////////////////////////
@@ -41,7 +41,21 @@ attribute values and no overlapping architectures.
 .\" //////////////////////////////////////////////////////////////////////////
 .SH RETURN VALUE
 .\" //////////////////////////////////////////////////////////////////////////
-Returns zero on success and negative values on failure.
+Returns zero on success or one of the following error codes on
+failure:
+.TP
+.B -EDOM
+Unable to merge the filters due to architecture issues, e.g. byte endian
+mismatches.
+.TP
+.B -EEXIST
+The architecture already exists in the filter.
+.TP
+.B -EINVAL
+One of the filters is invalid.
+.TP
+.B -ENOMEM
+The library was unable to allocate enough memory.
 .\" //////////////////////////////////////////////////////////////////////////
 .SH EXAMPLES
 .\" //////////////////////////////////////////////////////////////////////////
diff --git a/doc/man/man3/seccomp_notify_alloc.3 b/doc/man/man3/seccomp_notify_alloc.3
index c265ba2..48c4599 100644
--- a/doc/man/man3/seccomp_notify_alloc.3
+++ b/doc/man/man3/seccomp_notify_alloc.3
@@ -1,4 +1,4 @@
-.TH "seccomp_notify_alloc" 3 "24 April 2019" "tycho@tycho.ws" "libseccomp Documentation"
+.TH "seccomp_notify_alloc" 3 "30 May 2020" "tycho@tycho.ws" "libseccomp Documentation"
 .\" //////////////////////////////////////////////////////////////////////////
 .SH NAME
 .\" //////////////////////////////////////////////////////////////////////////
@@ -57,21 +57,33 @@ returns the notification fd of a filter after it has been loaded.
 .\" //////////////////////////////////////////////////////////////////////////
 .SH RETURN VALUE
 .\" //////////////////////////////////////////////////////////////////////////
-.P
 The
-.BR seccomp_notify_alloc (),
-.BR seccomp_notify_receive (),
-and
-.BR seccomp_notify_respond ()
-functions all return 0 on success, -1 on failure.
+.BR seccomp_notify_fd ()
+returns the notification fd of the loaded filter.
 .P
 The
 .BR seccomp_notify_id_valid ()
 returns 0 if the id is valid, and -ENOENT if it is not.
 .P
 The
-.BR seccomp_notify_fd ()
-returns the notification fd of the loaded filter.
+.BR seccomp_notify_alloc (),
+.BR seccomp_notify_receive (),
+and
+.BR seccomp_notify_respond ()
+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.
+.TP
+.B -EFAULT
+Internal libseccomp failure.
+.TP
+.B -ENOMEM
+The library was unable to allocate enough memory.
+.TP
+.B -EOPNOTSUPP
+The library doesn't support the particular operation.
 .\" //////////////////////////////////////////////////////////////////////////
 .SH NOTES
 .\" //////////////////////////////////////////////////////////////////////////
diff --git a/doc/man/man3/seccomp_rule_add.3 b/doc/man/man3/seccomp_rule_add.3
index 0b9bcff..99d85e2 100644
--- a/doc/man/man3/seccomp_rule_add.3
+++ b/doc/man/man3/seccomp_rule_add.3
@@ -1,4 +1,4 @@
-.TH "seccomp_rule_add" 3 "17 February 2019" "paul@paul-moore.com" "libseccomp Documentation"
+.TH "seccomp_rule_add" 3 "30 May 2020" "paul@paul-moore.com" "libseccomp Documentation"
 .\" //////////////////////////////////////////////////////////////////////////
 .SH NAME
 .\" //////////////////////////////////////////////////////////////////////////
@@ -279,12 +279,47 @@ SCMP_CMP(
 .SH RETURN VALUE
 .\" //////////////////////////////////////////////////////////////////////////
 The
+.BR SCMP_SYS ()
+macro returns a value suitable for use as the
+.I syscall
+value in the
+.BR seccomp_rule_add* ()
+functions.  In a similar manner, the
+.BR SCMP_CMP ()
+and
+.BR SCMP_A* ()
+macros return values suitable for use as argument comparisons in the
+.BR seccomp_rule_add ()
+and
+.BR seccomp_rule_add_exact ()
+functions.
+.P
+The
 .BR seccomp_rule_add (),
 .BR seccomp_rule_add_array (),
 .BR seccomp_rule_add_exact (),
 and
 .BR seccomp_rule_add_exact_array ()
-functions return zero on success, negative errno values on failure.
+functions return zero on success or one of the following error codes on
+failure:
+.TP
+.B -EDOM
+Architecture specific failure.
+.TP
+.B -EEXIST
+The rule already exists.
+.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.
+.TP
+.B -EOPNOTSUPP
+The library doesn't support the particular operation.
 .\" //////////////////////////////////////////////////////////////////////////
 .SH EXAMPLES
 .\" //////////////////////////////////////////////////////////////////////////
diff --git a/doc/man/man3/seccomp_syscall_priority.3 b/doc/man/man3/seccomp_syscall_priority.3
index 5a11037..5621b85 100644
--- a/doc/man/man3/seccomp_syscall_priority.3
+++ b/doc/man/man3/seccomp_syscall_priority.3
@@ -1,4 +1,4 @@
-.TH "seccomp_syscall_priority" 3 "25 July 2012" "paul@paul-moore.com" "libseccomp Documentation"
+.TH "seccomp_syscall_priority" 3 "30 May 2020" "paul@paul-moore.com" "libseccomp Documentation"
 .\" //////////////////////////////////////////////////////////////////////////
 .SH NAME
 .\" //////////////////////////////////////////////////////////////////////////
@@ -53,13 +53,28 @@ is the value returned by the call to
 .SH RETURN VALUE
 .\" //////////////////////////////////////////////////////////////////////////
 The
-.BR seccomp_syscall_priority ()
-function returns zero on success, negative errno values on failure.  The
 .BR SCMP_SYS ()
 macro returns a value suitable for use as the
 .I syscall
 value in
 .BR seccomp_syscall_priority ().
+.P
+The
+.BR seccomp_syscall_priority ()
+function returns zero on success or one of the following error codes on
+failure:
+.TP
+.B -EDOM
+Architecture specific failure.
+.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.
 .\" //////////////////////////////////////////////////////////////////////////
 .SH EXAMPLES
 .\" //////////////////////////////////////////////////////////////////////////