git: 6c93a2d0bc37 - main - [skip ci] improvements to cap_sysctl.3

The branch main has been updated by asomers:

URL: https://cgit.FreeBSD.org/src/commit/?id=6c93a2d0bc37f0c912e402f3f94c3c01350dca26

commit 6c93a2d0bc37f0c912e402f3f94c3c01350dca26
Author:     Alan Somers <asomers@FreeBSD.org>
AuthorDate: 2022-12-01 16:49:57 +0000
Commit:     Alan Somers <asomers@FreeBSD.org>
CommitDate: 2022-12-08 19:45:47 +0000

    [skip ci] improvements to cap_sysctl.3
    
    * Correct some function prototypes which were documented with the wrong
      pointer type.
    * Clarify return values and requirements for freeing the limit handle.
    
    MFC after:      1 week
    Sponsored by:   Axcient
    Reviewed by:    oshogbo
    Differential Revision: https://reviews.freebsd.org/D37586
---
 lib/libcasper/services/cap_sysctl/cap_sysctl.3 | 42 +++++++++++++++++++++-----
 1 file changed, 35 insertions(+), 7 deletions(-)

diff --git a/lib/libcasper/services/cap_sysctl/cap_sysctl.3 b/lib/libcasper/services/cap_sysctl/cap_sysctl.3
index 0a7d009e1c3c..381315fcbdd7 100644
--- a/lib/libcasper/services/cap_sysctl/cap_sysctl.3
+++ b/lib/libcasper/services/cap_sysctl/cap_sysctl.3
@@ -24,7 +24,7 @@
 .\"
 .\" $FreeBSD$
 .\"
-.Dd May 5, 2020
+.Dd December 1, 2022
 .Dt CAP_SYSCTL 3
 .Os
 .Sh NAME
@@ -41,14 +41,14 @@
 .Fn cap_sysctlbyname "cap_channel_t *chan" "const char *name" "void *oldp" "size_t *oldlenp" "const void *newp" "size_t newlen"
 .Ft int
 .Fn cap_sysctlnametomib "cap_channel_t *chan" "const char *name" "int *mibp" "size_t *sizep"
-.Ft void *
+.Ft cap_sysctl_limit_t *
 .Fn cap_sysctl_limit_init "cap_channel_t *chan"
-.Ft void *
-.Fn cap_sysctl_limit_name "void *limit" "const char *name" "int flags"
-.Ft void *
-.Fn cap_sysctl_limit_mib "void *limit" "const int *mibp" "u_int miblen" "int flags"
+.Ft cap_sysctl_limit_t *
+.Fn cap_sysctl_limit_name "cap_sysctl_limit_t *limit" "const char *name" "int flags"
+.Ft cap_sysctl_limit_t *
+.Fn cap_sysctl_limit_mib "cap_sysctl_limit_t *limit" "const int *mibp" "u_int miblen" "int flags"
 .Ft int
-.Fn cap_sysctl_limit "void *limit"
+.Fn cap_sysctl_limit "cap_sysctl_limit_t *limit"
 .Sh DESCRIPTION
 The
 .Fn cap_sysctl ,
@@ -109,6 +109,8 @@ must be specified.
 .Fn cap_sysctl_limit
 applies a set of sysctl limits to the capability, denying access to sysctl
 variables not belonging to the set.
+It consumes the limit handle.
+After either success or failure, the user must not access the handle again.
 .Pp
 Once a set of limits is applied, subsequent calls to
 .Fn cap_sysctl_limit
@@ -168,6 +170,32 @@ printf("The value of %s is %d.\\n", name, value);
 
 cap_close(capsysctl);
 .Ed
+.Sh RETURN VALUES
+.Fn cap_sysctl_limit_init
+will return a new limit handle on success or
+.Dv NULL
+on failure, and set
+.Va errno .
+.Fn cap_sysctl_limit_mib
+and
+.Fn cap_sysctl_limit_name
+will return the modified limit handle on success or
+.Dv NULL
+on failure and set
+.Va errno .
+After failure, the caller must not access the limit handle again.
+.Fn cap_sysctl_limit
+will return
+.Dv -1
+on failure and set
+.Va errno .
+.Fn cap_sysctl ,
+.Fn cap_sysctlbyname ,
+and
+.Fn cap_sysctlnametomib
+have the same return values as their non-capability-mode equivalents as
+documented in
+.Xr sysctl 3 .
 .Sh SEE ALSO
 .Xr cap_enter 2 ,
 .Xr err 3 ,