NAME

SYSCTLMIF_VERSION, sysctlmif_name, sysctlmif_oidbyname, sysctlmif_oidextendedbyname, sysctlmif_desc, sysctlmif_descbyname, sysctlmif_label, sysctlmif_labelbyname, sysctlmif_fmt, sysctlmif_fmtbyname, sysctlmif_hashandler, sysctlmif_hashandlerbyname, sysctlmif_kind, sysctlmif_kindbyname, SYSCTLMIF_KINDTYPE, SYSCTLMIF_KINDFLAGS, sysctlmif_nextnode, sysctlmif_nextnodebyname, sysctlmif_nextleaf, sysctlmif_nextleafbyname, sysctlmif_object, sysctlmif_objectbyname, sysctlmif_freeobject, sysctlmif_list, sysctlmif_grouplist, sysctlmif_grouplistbyname, sysctlmif_leaves, sysctlmif_leavesbyname, sysctlmif_freelist, sysctlmif_tree, sysctlmif_treebyname, sysctlmif_freetree, sysctlmif_mib, sysctlmif_freemib — sysctl MIB-Tree API

LIBRARY

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

sysctlinfo_load="YES"
sysctlbyname_improved_load="YES"

library “libsysctlmibinfo2”

SYNOPSIS

#include <sysctlmibinfo2.h>

#define SYSCTLMIF_VERSION

int
sysctlmif_name(int *id, size_t idlevel, char *name, size_t *namelen);

int
sysctlmif_oidbyname(const char *name, int *id, size_t *idlevel);

int
sysctlmif_oidextendedbyname(const char *name, int *id, size_t *idlevel);

int
sysctlmif_desc(int *id, size_t idlevel, char *desc, size_t *desclen);

int
sysctlmif_descbyname(const char *name, char *desc, size_t *desclen);

int
sysctlmif_label(int *id, size_t idlevel, char *label, size_t *labellen);

int
sysctlmif_labelbyname(const char *name, char *label, size_t *labellen);

int
sysctlmif_fmt(int *id, size_t idlevel, char *fmt, size_t *fmtlen);

int
sysctlmif_fmtbyname(const char *name, char *fmt, size_t *fmtlen);

int
sysctlmif_hashandler(int *id, size_t idlevel, bool *handler);

int
sysctlmif_hashandlerbyname(const char *name, bool *handler);

int
sysctlmif_kind(int *id, size_t idlevel, unsigned int *kind);

int
sysctlmif_kindbyname(const char *name, unsigned int *kind);

unsigned int
SYSCTLMIF_KINDTYPE(unsigned int kind);

unsigned int
SYSCTLMIF_KINDFLAGS(unsigned int kind);

int
sysctlmif_nextleaf(int *id, size_t idlevel, int *idnext, size_t *idnextlevel);

int
sysctlmif_nextleafbyname(const char *name, char *next, size_t *nextlen);

int
sysctlmif_nextnode(int *id, size_t idlevel, int *idnext, size_t *idnextlevel);

int
sysctlmif_nextnodebyname(const char *name, char *next, size_t *nextlen);

struct sysctlmif_object *
sysctlmif_object(int *id, size_t idlevel);

struct sysctlmif_object *
sysctlmif_objectbyname(const char *name);

void
sysctlmif_freeobject(struct sysctlmif_object *object);

struct sysctlmif_list *
sysctlmif_list();

struct sysctlmif_list *
sysctlmif_grouplist(int *idroot, size_t idrootlen);

struct sysctlmif_list *
sysctlmif_grouplistbyname(const char *name);

struct sysctlmif_list *
sysctlmif_leaves(int *idroot, size_t idrootlen);

struct sysctlmif_list *
sysctlmif_leavesbyname(const char *name);

void
sysctlmif_freelist(struct sysctlmif_list *list);

struct sysctlmif_object *
sysctlmif_tree(int *idroot, size_t idrootlevel);

struct sysctlmif_object *
sysctlmif_treebyname(const char *name);

void
sysctlmif_freetree(struct sysctlmif_object *node);

struct sysctlmif_list *
sysctlmif_mib();

void
sysctlmif_freemib(struct sysctlmif_list *mib);

DESCRIPTION

The sysctlmibinfo2 library is an interface to the kernel sysctl MIB-Tree. It implements wrappers around the sysctlinfo(4) interface and sysctlbyname-improved to explore the sysctl MIB and to get the info of an object, moreover it defines a struct sysctlmif_object and provides a convenient API to build data structures of sysctlmif_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”.

SYSCTLMIF_VERSION is set to 2 to differentiate between this library and sysctlmibinfo(3).

SLIST_HEAD(sysctlmif_list, sysctlmif_object);

struct sysctlmif_object {
	SLIST_ENTRY(sysctlmif_object) object_link;
	int      *id;            /* array of idlevel entries  */
	size_t   idlevel;        /* between 1 and CTL_MAXNAME */
	char     *name;          /* name in MIB notation      */
	char     *desc;          /* description               */
	char     *label;         /* aggregation label         */
	uint8_t  type;           /* defined in <sys/sysctl.h> */
	uint32_t flags;          /* defined in <sys/sysctl.h> */
	char     *fmt;           /* format string             */
	struct sysctlmif_list *children; /* children list     */
};

RETURN VALUES

The sysctlmif_oidbyname(), sysctlmif_oidextendedbyname(), sysctlmif_name(), sysctlmif_desc(), sysctlmif_descbyname(), sysctlmif_label(), sysctlmif_labelbyname(), sysctlmif_fmt(), sysctlmif_fmtbyname(), sysctlmif_hashandler(), sysctlmif_hashandlerbyname(), sysctlmif_kind(), sysctlmif_kindbyname(), sysctlmif_nextnode(), sysctlmif_nextnodebyname(), sysctlmif_nextleaf(), and sysctlmif_nextleafbyname() functions return the value 0 if successful; otherwise the value -1 is returned and the global variable errno is set to indicate the error.

The sysctlmif_object(), sysctlmif_objectbyname(), sysctlmif_list(), sysctlmif_grouplist(), sysctlmif_grouplistbyname(), sysctlmif_leaves(), sysctlmif_leavesbyname(), sysctlmif_tree(), sysctlmif_treebyname(), sysctlmif_mib() functions return NULL upon error or a pointer to allocated memory for success.

EXAMPLES

Complete set of examples: https://gitlab.com/alfix/sysctlmibinfo2/tree/master/examples

If installed:

Example to print the Sound Driver objects:

struct sysctlmif_list *list;
struct sysctlmif_object *obj;

if ((list = sysctlmif_leavesbyname("hw.snd")) == NULL)
	return (1);

SLIST_FOREACH(obj, list, object_link) {
	printf("name:   %s\n", obj->name);
	printf("descr.: %s\n", obj->desc);
	printf("label:  %s\n", obj->label);
	printf("flags:  %u\n", obj->flags);
	printf("type:   %u\n", obj->type);
	printf("fmt:    %s\n", obj->fmt);
	printf("----------------------\n");
}

sysctlmif_freelist(list);

ERRORS

The following errors may be reported:

[ECAPMODE]

The node has not the CTLFLAG_CAPRD or CTLFLAG_CAPWR flag in capability mode.

[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 node exists but its info is NULL.

[ENOENT]

The node does not exist.

[ENOMEM]

Cannot allocate memory.

SEE ALSO

cap_enter(2), queue(3), sysctl(3), sysctlinfo(3), sysctlinfo(4)

HISTORY

The sysctlmibinfo2 library first appeared in FreeBSD 13.0.

AUTHORS

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