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

FreeBSD Manual Pages

  
 
  

home | help
SYSCTLINFO(3)		    Library Functions Manual		 SYSCTLINFO(3)

NAME
       SYSCTLINFO,	      SYSCTLINFO_BYNAME,	    SYSCTLINFO_DESOBJ,
       SYSCTLINFO_DESOBJ_NEXTOID, SYSCTLINFO_DESOBJ_NEXTNAME  --  sysctl  MIB-
       Tree interface

SYNOPSIS
       #include	<sys/types.h>
       #include	<sys/sysctl.h>
       #include	<sysctlinfo.h>
       #define OBJNAME
       #define OBJID_BYNAME
       #define FAKEOBJNAME
       #define FAKEOBJID_BYNAME
       #define OBJDESC
       #define OBJDESC_BYNAME
       #define OBJLABEL
       #define OBJLABEL_BYNAME
       #define OBJKIND
       #define OBJKIND_BYNAME
       #define OBJFMT
       #define OBJFMT_BYNAME
       #define NEXTOBJNODE
       #define NEXTOBJNODE_BYNAME
       #define NEXTOBJLEAF
       #define NEXTOBJLEAF_BYNAME
       #define SEROBJ
       #define SEROBJ_BYNAME
       #define SEROBJNEXTNODE
       #define SEROBJNEXTNODE_BYNAME
       #define SEROBJNEXTLEAF
       #define SEROBJNEXTLEAF_BYNAME
       #define OBJHASHANDLER
       #define OBJHASHANDLER_BYNAME
       #define NEXTOBJLEAFAVOIDSKIP

       int
       SYSCTLINFO(int *id,     size_t idlevel,	   int prop[2],	    void *buf,
	   size_t *buflen);

       int
       SYSCTLINFO_BYNAME(char *name, int prop[2], void *buf, size_t *buflen);

       void
       SYSCTLINFO_DESOBJ(void *buf,  size_t idlevel,   int *id,	  char *namep,
	   char	*descrp, unsigned int kind, char *fmtp,	char *labelp);

       void
       SYSCTLINFO_DESOBJ_NEXTOID(void *buf,	 size_t	idlevel,      int *id,
	   char	*namep,	   char	*descrp,    unsigned int kind,	   char	*fmtp,
	   char	*labelp, size_t	idnextlevel, int *idnext);

       void
       SYSCTLINFO_DESOBJ_NEXTNAME(void *buf,	  size_t idlevel,     int *id,
	   char	*namep,	   char	*descrp,    unsigned int kind,	   char	*fmtp,
	   char	*labelp, char *namenextp);

DESCRIPTION
       Macros  to  wrap	 the  sysctlinfo(4) interface for exploring the	sysctl
       MIB-Tree	and for	getting	the properties of an object, as	it is not  de-
       signed  to  get and set object values, anyone wishing to	do this	should
       see sysctl(3).

       An object is identified by an Object Identifier (OID), a	series of num-
       bers, represented by a pair int	*id  and  size_t  idlevel,  the	 level
       should  be between 1 and	CTL_MAXNAME.  It is possible to	replace	a num-
       ber  with  a  string  to	 obtain	 an  object  name,  e.g.,   [1.1]   ->
       "kern.ostype".

       SYSCTLINFO()  and SYSCLINFO_BYNAME() seek the node with id / idlevel or
       name, then the information specified by prop is copied into the	buffer
       buf.   Before the call buflen gives the size of buf, after a successful
       call buflen gives the amount of data copied; the	size of	the  info  can
       be determined with the NULL argument for	buf, the size will be returned
       in  the	location pointed to by buflen.	The value of prop[0] should be
       CTL_SYSCTL and prop[1] can specify the desired info, the	possible  val-
       ues are listed later.

       SYSCTLINFO()  accepts an	array id of idlevel elements and the following
       prop[1]:

       OBJFAKENAME
	       if the object exists buf	is set like a string  with  its	 name,
	       otherwise  SYSCTLINFO() build a name depending on the id, e.g.,
	       with  a	non-existent  OID  [1.1.100.500.1000]  the   name   is
	       "kern.ostype.100.500.1000".

       OBJNAME,	OBJDESC, OBJLABEL and OBJFMT
	       set  buf	 like  a  string with the name,	description, label and
	       format, respectively.

       OBJKIND
	       sets buf	like an	unsigned int with the kind of the object,  its
	       format  is: 3 bytes for flags and 1 byte	for type, they are de-
	       fined in	<sys/sysctl.h>.

       HASHANDLER
	       sets buf	like a bool value, true	if the object  has  a  defined
	       handler,	false otherwise.

       NEXTOBJLEAF and NEXTOBJNODE
	       set  buf	like an	integer	array with the OID of the next leaf or
	       also internal visited in	a "Depth-First	Traversal",  the  next
	       level  is  "buflen / sizeof(int)" to be consistent with the ac-
	       ceptable	level range.

       FAKENEXTOBJLEAFNOSKIP
	       sets buf	like the OID of	the next  leaf	ignoring  the  objects
	       with  the SKIP flag; this feature exists	for compatibility with
	       the undocumented	interface, see "IMPLEMENTATION NOTES".

       DESOBJ  serializes the object info in buf, it  should  be  deserialized
	       via  SYSCTLINFO_DESOBJ(),  if  description,  format or label is
	       NULL, descp, fmtp or labep is set to "" respectively.

       SEROBJNEXTNODE and SEROBJNEXTLEAF
	       serialize the object info like DESOBJ adding  the  next	Object
	       OID,	  buf	    should	 be	 deserialized	   via
	       SYSCTLINFO_DESOBJ_NEXTOID(),   if   no	next   object	exists
	       idnextlevel is set to 0.

       SYSCTLINFO_BYNAME() accepts a string name and the following prop[1]:

       OBJFAKEID_BYNAME	and OBJID_BYNAME
	       set  buf	 like an integer array with the	OID of the object, the
	       level is	"buflen	/ sizeof(int)".	  OBJFAKEID_BYNAME  builds  an
	       incomplete OID if some level name is "",	e.g., name "n1.n2.n3."
	       -> [1.2.3].

       OBJDESC_BYNAME, OBJLABEL_BYNAME and OBJFMT_BYNAME
	       set  buf	 like  a string	with the description, label and	format
	       respectively.

       OBJKIND_BYNAME
	       sets buf	like an	unsigned int with the kind of the object,  its
	       format  is: 3 bytes for flags and 1 byte	for type, they are de-
	       fined in	<sys/sysctl.h>.

       HASHANDLER_BYNAME
	       sets buf	like a bool value, true	if the object  has  a  defined
	       handler,	false otherwise.

       NEXTOBJLEAF_BYNAME and NEXTOBJNODE_BYNAME
	       set  buf	 copy  the name	of the next leaf or also internal node
	       visited in a "Depth-First Traversal".

       DESOBJ_BYNAME
	       serializes the object info in buf, it  should  be  deserialized
	       via  SYSCTLINFO_DESOBJ(),  if  description,  format or label is
	       NULL, descp, fmtp or labep is set to "" respectively.

       SEROBJNEXTLEAF_BYNAME and SEROBJNEXTNODE_BYNAME
	       serialize the object info like DESOBJ adding  the  next	object
	       name,	   buf	     should	 be	 deserialized	   via
	       SYSCTLINFO_DESOBJ_NEXTNAME(),  if   no	next   object	exists
	       nextnamep is set	to "".

IMPLEMENTATION NOTES
       The  kernel  provides  an  undocumented	interface  for the info	of the
       sysctl tree, sysctlinfo and the current kernel interface	can coexist.

       In "capability mode", see cap_enter(2), sysctlinfo checks if the	object
       has  CTLFLAG_CAPRD  or  CTLFLAG_CAPWR  before  to  return   its	 info.
       NEXTOBJNODE, NEXTOBJLEAF, NEXTOBJNODE_BYNAME and	NEXTOBJLEAF_BYNAME ig-
       nore  capability	 flags	to  traverse the tree also in capability mode,
       OBJFAKENAME ignores capability flags for	compatibility with the	kernel
       interface.

RETURN VALUES
       The  SYSCTLINFO()  and SYSCTLINFO_BYNAME() functions return the value 0
       if successful; otherwise	the value -1 is	returned and the global	 vari-
       able errno is set to indicate the error.

EXAMPLES
       If installed:
	     /usr/local/share/examples/sysctlinfo/

       Example to explore the MIB printing only	names

	     char name[MAXPATHLEN], next[MAXPATHLEN];
	     int prop[2] = {CTL_SYSCTL,	NEXTOBJNODE_BYNAME};
	     size_t nextlen = MAXPATHLEN;

	     strcpy(next, "sysctl");
	     do	{
		     strncpy(name, next, nextlen);
		     printf("%s0, name);
		     nextlen = MAXPATHLEN;
	     } while(SYSCTLINFO_BYNAME(name, prop, next, &nextlen) == 0);

       Example to explore the MIB printing all of the properties:

	     int i, id[CTL_MAXNAME], *idp_unused, *idnextp;
	     size_t idlevel, idnextlevel, buflen, lev_unused;
	     unsigned int kind;
	     char buf[BUFSIZE],	*namep,	*descrp, *fmtp,	*labelp;
	     int prop[2] = {CTL_SYSCTL,	SEROBJNEXTNODE};

	     id[0]   = 0;
	     idlevel = 1;

	     for (;;) {
		     buflen = BUFSIZE;
		     if(SYSCTLINFO(id, idlevel,	prop, buf, &buflen) != 0)
			     err(1, "SEROBJNEXTNODE");

		     SYSCTLINFO_DESOBJ_NEXTOID(buf, lev_unused,	idp_unused, namep,
			 descrp, kind, fmtp, labelp, idnextlevel, idnextp);

		     for (i = 0; i < idlevel; i++)
			     printf("%d%c", id[i], i+1 < idlevel ? '.' : '\n');
		     printf("name:  %s\n", namep);
		     printf("descr: %s\n", descrp);
		     printf("label: %s\n", labelp);
		     printf("fmt:   %s\n", fmtp);
		     printf("kind:  %u\n", kind);
		     printf("flags: %u\n", kind	& 0xfffffff0);
		     printf("type:  %u\n", kind	& CTLTYPE);
		     printf("------------------------------------\n");

		     if	(idnextlevel < 1)
			     break;

		     memcpy(id,	idnextp, idnextlevel * sizeof(int));
		     idlevel = idnextlevel;
	     }

ERRORS
       The following errors may	be reported:

       [ECAPMODE]	  In   capability   mode   the	 object	 has  not  the
			  CTLFLAG_CAPRD	or CTLFLAG_CAPWR flag.

       [EINVAL]		  name has more	than CTL_MAXNAME levels.

       [EINVAL]		  idlevel is either greater CTL_MAXNAME, equal to zero
			  or is	not an integer.

       [ENAMETOOLONG]	  name is >= MAXPATHLEN.

       [ENOATTR]	  The object exists but	its info is NULL.

       [ENOENT]		  The object does not exist.

SEE ALSO
       cap_enter(2), sysctl(3),	sysctlinfo(4)

AUTHORS
       sysctlinfo    was    written    by     Alfonso	  Sabato     Siciliano
       <asiciliano@FreeBSD.org>.

FreeBSD	13.2			April 20, 2022			 SYSCTLINFO(3)

NAME | SYNOPSIS | DESCRIPTION | IMPLEMENTATION NOTES | RETURN VALUES | EXAMPLES | ERRORS | SEE ALSO | AUTHORS

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

home | help