SYSCTL_INT(9)

💖 NAME 💖

okay bestie, welcome to the SYSCTL_INT(9) page from the Kernel Developer's Manual — this is the kernel sysctl interface and it's literally a whole cast of characters. The lineup is sysctl_int, sysctl_bounded_arr, sysctl_quad, sysctl_string, sysctl_tstring, sysctl_rdint, sysctl_rdquad, sysctl_rdstring, sysctl_rdstruct, and sysctl_struct — all giving kernel sysctl interface energy. 💅

✨ SYNOPSIS ✨

#include <sys/types.h>
#include <sys/sysctl.h>

int
sysctl_int(void *oldp, size_t *oldlenp, void *newp, size_t newlen,
    int *valp);

int
sysctl_bounded_arr(const struct sysctl_bounded_args *valpp,
    u_int valplen, int *name, u_int namelen, void *oldp,
    size_t *oldlenp, void *newp, size_t newlen);

int
sysctl_quad(void *oldp, size_t *oldlenp, void *newp, size_t newlen,
    int64_t *valp);

int
sysctl_string(void *oldp, size_t *oldlenp, void *newp, size_t newlen,
    char *str, int maxlen);

int
sysctl_tstring(void *oldp, size_t *oldlenp, void *newp, size_t newlen,
    char *str, int maxlen);

int
sysctl_rdint(void *oldp, size_t *oldlenp, void *newp, int val);

int
sysctl_rdquad(void *oldp, size_t *oldlenp, void *newp, int64_t val);

int
sysctl_rdstring(void *oldp, size_t *oldlenp, void *newp,
    const char *str);

int
sysctl_rdstruct(void *oldp, size_t *oldlenp, void *newp, const void *sp,
    int len);

int
sysctl_struct(void *oldp, size_t *oldlenp, void *newp, size_t newlen,
    void *sp, int len);

💅 DESCRIPTION 💅

These functions and data structures are here to simplify and partially implement operations for the kernel and user implementations of the sysctl(2) interface. A single syscall(9) is used to request and modify kernel variables. The mib argument is recursively scanned as an array of integers, either calling further functions for parsing the rest of the MIB for nodes or operating on kernel data for leaf nodes. 🦋

🔮 Data Structures 🔮

For each level of the MIB tree, the kernel header files provide a cpp(1) macro initialiser for an array of this data structure:

struct ctlname {
        char    *ctl_name;      /* subsystem name */
        int     ctl_type;       /* type of name */
};

For example:

#define CTL_NAMES { \
        { 0, 0 }, \
        { "kern", CTLTYPE_NODE }, \
        { "vm", CTLTYPE_NODE }, \
        { "fs", CTLTYPE_NODE }, \
        { "net", CTLTYPE_NODE }, \
        { "debug", CTLTYPE_NODE }, \
        { "hw", CTLTYPE_NODE }, \
        { "machdep", CTLTYPE_NODE }, \
        { "user", CTLTYPE_NODE }, \
        { "ddb", CTLTYPE_NODE }, \
        { "vfs", CTLTYPE_NODE }, \
}

Each array element initialiser maps the correspondent MIB identifier. The ctl_name field provides a string name. The ctl_type field describes the identifier type, where possible values are:

• CTLTYPE_NODE — the name is a node;
• CTLTYPE_INT — the name describes an integer;
• CTLTYPE_STRING — the name describes a string;
• CTLTYPE_QUAD — the name describes a 64-bit number;
• CTLTYPE_STRUCT — the name describes a structure.

For each of the types there are two functions provided to perform both read and write or only a read operation on the identifier (see the following subsection).

These data structures are used by the sysctl(8) program to provide mapping into MIB identifiers. 🎀

🎀 Functions 🎀

All of the functions perform a write provided that newp is not a NULL pointer and newlen specifies an appropriate data length. All read-only versions of the functions return EPERM if a write operation is requested. 🫶

The following helper functions are provided to aid operation on the kernel data variables referenced by the leaf nodes in the MIBs:

• sysctl_int(void *oldp, size_t *oldlenp, void *newp, size_t newlen, int *valp) — the variable referenced by valp is a 32-bit integer. Read or write returning the previous value in the user memory location pointed to by the oldp argument. The value pointed to by oldlenp has to be no less than four.
• sysctl_rdint(void *oldp, size_t *oldlenp, void *newp, int val) — a read-only version of the above.
• sysctl_bounded_arr(const struct sysctl_bounded_args *valpp, u_int valplen, int *name, u_int namelen, void *oldp, size_t *oldlenp, void *newp, size_t newlen) — asserts the new value is in the range specified by the element of valpp with the value of the mib field equal to name[0], before invoking sysctl_int() to read/write as normal.
• sysctl_quad(void *oldp, size_t *oldlenp, void *newp, size_t newlen, int64_t *valp) — the variable referenced is a 64-bit integer. Read or write returning the previous value in the user memory location pointed to by the oldp argument. The value pointed to by oldlenp has to be no less than eight.
• sysctl_rdquad(void *oldp, size_t *oldlenp, void *newp, int64_t val) — a read-only version of the above.
• sysctl_string(void *oldp, size_t *oldlenp, void *newp, size_t newlen, char *str, int maxlen) — the variable referenced by the str argument is a string of maximum length of maxlen. The old value is copied out into a user buffer pointed to by the oldp argument. If there is not enough space to store it, an ENOMEM is returned. If newlen is larger than maxlen, an EINVAL error is returned.
• sysctl_tstring(void *oldp, size_t *oldlenp, void *newp, size_t newlen, char *str, int maxlen) — a version of the above that truncates the old value that does not fit into the buffer provided by oldp instead of returning ENOMEM.
• sysctl_rdstring(void *oldp, size_t *oldlenp, void *newp, const char *str) — a read-only version of sysctl_string().
• sysctl_struct(void *oldp, size_t *oldlenp, void *newp, size_t newlen, void *sp, int len) — assume the area pointed to by the sp argument is an opaque array of bytes of size len. Old and new length checks are performed and data is copied in and/or out.
• sysctl_rdstruct(void *oldp, size_t *oldlenp, void *newp, const void *sp, int len) — a read-only version of the above. 💜

🔥 SEE ALSO 🔥

sysctl(2), sysctl.conf(5), sysctl(8), syscall(9)

👑 HISTORY 👑

These functions first appeared in 4.4BSD. 🌈

---

mwah 💋 this cute little page is from Debian, dated September 1, 2020, and it's SYSCTL_INT(9) — periodt. 🫶