Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages


home | help
CAP_SYSCTL(3)		 BSD Library Functions Manual		 CAP_SYSCTL(3)

     cap_sysctl	-- library for getting or setting system information in	capa-
     bility mode

     library "libcap_sysctl"

     #include <libcasper.h>
     #include <casper/cap_sysctl.h>

     cap_sysctl(cap_channel_t *chan, const int *name, u_int namelen,
	 void *oldp, size_t *oldlenp, const void *newp,	size_t newlen);

     cap_sysctlbyname(cap_channel_t *chan, const char *name, void *oldp,
	 size_t	*oldlenp, const	void *newp, size_t newlen);

     cap_sysctlnametomib(cap_channel_t *chan, const char *name,	int *mibp,
	 size_t	*sizep);

     void *
     cap_sysctl_limit_init(cap_channel_t *chan);

     void *
     cap_sysctl_limit_name(void	*limit,	const char *name, int flags);

     void *
     cap_sysctl_limit_mib(void *limit, const int *mibp,	u_int miblen,
	 int flags);

     cap_sysctl_limit(void *limit);

     The cap_sysctl(), cap_sysctlbyname() and cap_sysctlnametomib() functions
     are equivalent to sysctl(3), sysctlbyname(3) and sysctlnametomib(3), ex-
     cept that they are	implemented by the `system.sysctl' libcasper(3)	ser-
     vice and require a	corresponding libcasper(3) capability.

     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 capa-
     bility.  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 cap_sysctl_limit_name() function adds the sysctl identified by	name
     to	the limit list,	and cap_sysctl_limit_mib() function adds the sysctl
     identified	by mibp	to the limit list.  The	access rights for the sysctl
     are specified in the flags	parameter; at least one	of CAP_SYSCTL_READ,
     CAP_SYSCTL_WRITE and CAP_SYSCTL_RDWR must be specified.
     cap_sysctl_limit()	applies	a set of sysctl	limits to the capability,
     denying access to sysctl variables	not belonging to the set.

     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 auto-
     matically added to	the set.

     The following example first opens a capability to casper, uses this capa-
     bility 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;
     int value;
     size_t size;

     /*	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. */

     /*	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. */
     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_enter(2), err(3), sysctl(3), sysctlbyname(3), sysctlnametomib(3),
     capsicum(4), nv(9)

     The cap_sysctl service first appeared in FreeBSD 10.3.

     The cap_sysctl service was	implemented by Pawel Jakub Dawidek
     <> under sponsorship from	the FreeBSD Foundation.

     This manual page was written by
     Mariusz Zaborski <>.

BSD				  May 5, 2020				   BSD


Want to link to this manual page? Use this URL:

home | help