From c1ed3d958e53df9303dd48371b1225363803596b Mon Sep 17 00:00:00 2001 From: Paul Moore Date: Tue, 19 May 2020 20:52:31 -0400 Subject: doc: update the manpages with return code information Acked-by: Tom Hromatka Signed-off-by: Paul Moore --- doc/man/man3/seccomp_arch_add.3 | 25 ++++++++++++++++----- doc/man/man3/seccomp_attr_set.3 | 17 ++++++++++++-- doc/man/man3/seccomp_export_bpf.3 | 14 ++++++++++-- doc/man/man3/seccomp_init.3 | 11 ++++++++-- doc/man/man3/seccomp_load.3 | 16 ++++++++++++-- doc/man/man3/seccomp_merge.3 | 18 +++++++++++++-- doc/man/man3/seccomp_notify_alloc.3 | 30 +++++++++++++++++-------- doc/man/man3/seccomp_rule_add.3 | 39 +++++++++++++++++++++++++++++++-- doc/man/man3/seccomp_syscall_priority.3 | 21 +++++++++++++++--- 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 .\" ////////////////////////////////////////////////////////////////////////// -- cgit v1.2.1