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

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("%s, 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>.