git: 6d28cb5486b8 - stable/13 - improvements to cap_sysctl.3

From: Alan Somers <>
Date: Fri, 27 Jan 2023 19:28:06 UTC
The branch stable/13 has been updated by asomers:


commit 6d28cb5486b83f16f0925c4fbb620ee96e9cb7db
Author:     Alan Somers <>
AuthorDate: 2022-12-01 16:49:57 +0000
Commit:     Alan Somers <>
CommitDate: 2023-01-27 19:27:47 +0000

    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.
    [skip ci]
    Sponsored by:   Axcient
    Reviewed by:    oshogbo
    Differential Revision:
    (cherry picked from commit 6c93a2d0bc37f0c912e402f3f94c3c01350dca26)
 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
@@ -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"
 .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.
 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);
+.Fn cap_sysctl_limit_init
+will return a new limit handle on success or
+on failure, and set
+.Va errno .
+.Fn cap_sysctl_limit_mib
+.Fn cap_sysctl_limit_name
+will return the modified limit handle on success or
+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 ,
+.Fn cap_sysctlnametomib
+have the same return values as their non-capability-mode equivalents as
+documented in
+.Xr sysctl 3 .
 .Xr cap_enter 2 ,
 .Xr err 3 ,