NAME

SYNOPSIS

#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

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

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

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(name, "sysctl");
while(SYSCTLINFO_BYNAME(name, prop, next, &nextlen) == 0) {
        printf("%s\n", name);
        strncpy(name, next, nextlen);
        nextlen = MAXPATHLEN;
}

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

[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

HISTORY

AUTHORS