SYSCTLINFO(4)          FreeBSD Kernel Interfaces Manual          SYSCTLINFO(4)

NAME
     sysctlinfo - sysctl MIB-Tree Interface

SYNOPSIS
     sysctl.objname
     sysctl.objid_byname
     sysctl.objfakename
     sysctl.objfakeid_byname
     sysctl.objdesc
     sysctl.objdesc_byname
     sysctl.objlabel
     sysctl.objlabel_byname
     sysctl.objkind
     sysctl.objkind_byname
     sysctl.objfmt
     sysctl.objfmt_byname
     sysctl.nextobjnode
     sysctl.nextobjnode_byname
     sysctl.nextobjleaf
     sysctl.nextobjleaf_byname
     sysctl.serobj
     sysctl.serobj_byname
     sysctl.serobjnextnode
     sysctl.serobjnextnode_byname
     sysctl.serobjnextleaf
     sysctl.serobjnextleaf_byname
     sysctl.objhashandler
     sysctl.objhashandler_byname
     sysctl.fakenextobjleafnoskip

DESCRIPTION
     The sysctlinfo interface explores the sysctl MIB-Tree to pass the info of
     the objects to userland, it should be used via sysctlinfo(3).

     To load the required kernel modules at boot time, place the following
     lines in loader.conf(5):

           sysctlinfo_load="YES"

SEE ALSO
     sysctl(3), sysctlinfo(3)

HISTORY
     The sysctlinfo interface first appeared in FreeBSD 13.0.

AUTHORS
     sysctlinfo was written by Alfonso Sabato Siciliano
     <alf.siciliano@gmail.com>.

FreeBSD 13.0-ALPHA1            February 21, 2021           FreeBSD 13.0-ALPHA1

SYSCTLINFO(3)          FreeBSD 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 designed
     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
     numbers, 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 number
     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 values
     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
             defined 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
             acceptable 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
             defined 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
     ignore 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 variable
     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)

HISTORY
     The sysctlinfo interface first appeared in FreeBSD 13.0.

AUTHORS
     sysctlinfo was written by Alfonso Sabato Siciliano
     <alf.siciliano@gmail.com>.

FreeBSD 13.0-ALPHA1              April 1, 2021             FreeBSD 13.0-ALPHA1