FreeBSD Manual Pages
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 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 be- tween 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 deter- mined with the NULL argument for buf, the size will be returned in the lo- cation 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, other- wise 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 for- mat 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 han- dler, 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 un- documented 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, de- scp, 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 re- spectively. OBJKIND_BYNAME sets buf like an unsigned int with the kind of the object, its for- mat 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 han- dler, false otherwise. NEXTOBJLEAF_BYNAME and NEXTOBJNODE_BYNAME set buf copy the name of the next leaf or also internal node vis- ited 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, de- scp, 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 ca- pability 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 er- rno 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 <asicil- iano@FreeBSD.org>. FreeBSD ports 15.quarterly 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+Ports+15.1.quarterly>