FreeBSD manual
download PDF document: libcap_sysctl.3.pdf
CAP_SYSCTL(3) FreeBSD Library Functions Manual CAP_SYSCTL(3)
NAME
cap_sysctl - library for getting or setting system information in
capability mode
LIBRARY
library "libcap_sysctl"
SYNOPSIS
#include <libcasper.h>
#include <casper/cap_sysctl.h>
int
cap_sysctl(cap_channel_t *chan, const int *name, u_int namelen,
void *oldp, size_t *oldlenp, const void *newp, size_t newlen);
int
cap_sysctlbyname(cap_channel_t *chan, const char *name, void *oldp,
size_t *oldlenp, const void *newp, size_t newlen);
int
cap_sysctlnametomib(cap_channel_t *chan, const char *name, int *mibp,
size_t *sizep);
cap_sysctl_limit_t *
cap_sysctl_limit_init(cap_channel_t *chan);
cap_sysctl_limit_t *
cap_sysctl_limit_name(cap_sysctl_limit_t *limit, const char *name,
int flags);
cap_sysctl_limit_t *
cap_sysctl_limit_mib(cap_sysctl_limit_t *limit, const int *mibp,
u_int miblen, int flags);
int
cap_sysctl_limit(cap_sysctl_limit_t *limit);
DESCRIPTION
The cap_sysctl(), cap_sysctlbyname() and cap_sysctlnametomib() functions
are equivalent to sysctl(3), sysctlbyname(3) and sysctlnametomib(3),
except that they are implemented by the `system.sysctl' libcasper(3)
service and require a corresponding libcasper(3) capability.
LIMITS
By default, the cap_sysctl capability provides unrestricted access to the
sysctl namespace. Applications typically only require access to a small
number of sysctl variables; the cap_sysctl_limit() interface can be used
to restrict the sysctls that can be accessed using the cap_sysctl
capability. cap_sysctl_limit_init() returns an opaque limit handle used
to store a list of permitted sysctls and access rights. Rights are
encoded using the following flags:
CAP_SYSCTL_READ allow reads of the sysctl variable
CAP_SYSCTL_WRITE allow writes of the sysctl variable
CAP_SYSCTL_RDWR allow reads and writes of the sysctl variable
CAP_RECURSIVE permit access to any child of the sysctl variable
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 cap_sysctl_limit()
will fail unless the new set is a subset of the current set.
cap_sysctlnametomib() will succeed so long as the named sysctl variable
is present in the limit set, regardless of its access rights. When a
sysctl variable name is added to a limit set, its MIB identifier is
automatically added to the set.
EXAMPLES
The following example first opens a capability to casper, uses this
capability to create the system.sysctl casper service, and then uses the
cap_sysctl capability to get the value of kern.trap_enotcap.
cap_channel_t *capcas, *capsysctl;
const char *name = "kern.trap_enotcap";
void *limit;
size_t size;
bool value;
/* Open capability to Casper. */
capcas = cap_init();
if (capcas == NULL)
err(1, "Unable to contact Casper");
/* Enter capability mode sandbox. */
if (cap_enter() < 0 && errno != ENOSYS)
err(1, "Unable to enter capability mode");
/* Use Casper capability to create capability to the system.sysctl service. */
capsysctl = cap_service_open(capcas, "system.sysctl");
if (capsysctl == NULL)
err(1, "Unable to open system.sysctl service");
/* Close Casper capability, we don't need it anymore. */
cap_close(capcas);
/* Create limit for one MIB with read access only. */
limit = cap_sysctl_limit_init(capsysctl);
(void)cap_sysctl_limit_name(limit, name, CAP_SYSCTL_READ);
/* Limit system.sysctl. */
if (cap_sysctl_limit(limit) < 0)
err(1, "Unable to set limits");
/* Fetch value. */
size = sizeof(value);
if (cap_sysctlbyname(capsysctl, name, &value, &size, NULL, 0) < 0)
err(1, "Unable to get value of sysctl");
printf("The value of %s is %d.\n", name, value);
cap_close(capsysctl);
RETURN VALUES
cap_sysctl_limit_init() will return a new limit handle on success or NULL
on failure, and set errno. cap_sysctl_limit_mib() and
SEE ALSO
cap_enter(2), err(3), sysctl(3), sysctlbyname(3), sysctlnametomib(3),
capsicum(4), nv(9)
HISTORY
The cap_sysctl service first appeared in FreeBSD 10.3.
AUTHORS
The cap_sysctl service was implemented by Pawel Jakub Dawidek
<pawel@dawidek.net> under sponsorship from the FreeBSD Foundation.
This manual page was written by
Mariusz Zaborski <oshogbo@FreeBSD.org>.
FreeBSD 14.0-RELEASE-p6 December 1, 2022 FreeBSD 14.0-RELEASE-p6