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

FreeBSD Manual Pages

  
 
  

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

NAME
     cap_sysctl	-- library for getting or setting system information in	capa-
     bility 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);

     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);

     int
     cap_sysctl_limit(void *limit);

DESCRIPTION
     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.

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

EXAMPLES
     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;
     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);

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	13.0			  May 5, 2020			  FreeBSD 13.0

NAME | LIBRARY | SYNOPSIS | DESCRIPTION | LIMITS | EXAMPLES | SEE ALSO | HISTORY | AUTHORS

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=cap_sysctl&sektion=3&manpath=FreeBSD+13.0-RELEASE+and+Ports>

home | help