SYSCTL_CTX_INIT(9)

✨ SYSCTL_CTX_INIT(9) ✨

okay so bestie, welcome to the Kernel Developer's Manual 💅 this one's all about sysctl_ctx_init, sysctl_ctx_free, sysctl_ctx_entry_add, sysctl_ctx_entry_find, and sysctl_ctx_entry_del — the sysctl context crew that manages your dynamically created sysctl OIDs. no cap, this is the group chat that keeps track of your OIDs so you don't have to 🫶

---

🌸 NAME 🌸

sysctl_ctx_init, sysctl_ctx_free, sysctl_ctx_entry_add, sysctl_ctx_entry_find, sysctl_ctx_entry_del — the sysctl context that manages all your dynamically created sysctl OIDs ✨

---

🎀 SYNOPSIS 🎀

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

int
sysctl_ctx_init(struct sysctl_ctx_list *clist);

int
sysctl_ctx_free(struct sysctl_ctx_list *clist);

struct sysctl_ctx_entry *
sysctl_ctx_entry_add(struct sysctl_ctx_list *clist,
    struct sysctl_oid *oidp);

struct sysctl_ctx_entry *
sysctl_ctx_entry_find(struct sysctl_ctx_list *clist,
    struct sysctl_oid *oidp);

int
sysctl_ctx_entry_del(struct sysctl_ctx_list *clist,
    struct sysctl_oid *oidp);

---

💖 DESCRIPTION 💖

so these functions are literally the interface for managing dynamically created OIDs. the sysctl context is the main character here — it keeps track of every OID you create, and it makes sure they get removed properly when the time comes 👑

the way it works is it adds a little transactional moment to OID removal. like, if a removal operation fails partway through, you can roll the whole sysctl tree right back to its previous state. it's giving undo button, and we love that for us 💅

• sysctl_ctx_init() initializes a sysctl context. the clist argument must point to an already allocated variable. a context must be initialized before use, fr fr — no skipping steps. once it's initialized, you can pass a pointer to the context as an argument to all the SYSCTL_ADD_* macros (peep sysctl_add_oid(9)), and it gets updated with entries pointing to the newly created OIDS ✨

internally, the context is represented as a queue(3) TAILQ linked list. the list consists of struct sysctl_ctx_entry entries:

struct sysctl_ctx_entry {
        struct sysctl_oid *entry;
        TAILQ_ENTRY(sysctl_ctx_entry) link;
};

TAILQ_HEAD(sysctl_ctx_list, sysctl_ctx_entry);

each context entry points to one dynamic OID that it manages. newly created OIDs are always inserted in the front of the list 🌈

• sysctl_ctx_free() removes the context and the associated OIDs it manages. if it completes successfully, all managed OIDs have been unregistered (removed from the tree) and freed, together with all their allocated memory, and the entries of the context have been freed as well. clean slate, iconic behavior 🧚

the removal operation happens in two steps:

1. first, for each context entry, sysctl_remove_oid(9) is executed with parameter del set to 0, which inhibits the freeing of resources. if there are no errors during this step, sysctl_ctx_free() proceeds to the next step. if the first step fails, all unregistered OIDs associated with the context are registered again 🔁

Note: in most cases, the programmer specifies OID_AUTO as the OID number when creating an OID. however, during registration of the OID in the tree, this number is changed to the first available number greater than or equal to CTL_AUTO_START. if the first step of context deletion fails, re-registration of the OID does not change the already assigned OID number (which is different from OID_AUTO). this ensures that re-registered entries maintain their original positions in the tree 💀

2. the second step actually performs the deletion of the dynamic OIDs. sysctl_remove_oid(9) iterates through the context list, starting from the beginning (i.e., the newest entries). Important: this time, the function not only deletes the OIDs from the tree, but also frees their memory (provided that oid_refcnt == 0), as well as the memory of all context entries 🔥

• sysctl_ctx_entry_add() lets you add an existing dynamic OID to a context 🫶
• sysctl_ctx_entry_del() removes an entry from the context. Important: in this case, only the corresponding struct sysctl_ctx_entry is freed, but the oidp pointer remains intact. after that, the programmer is responsible for managing the resources allocated to this OID. it's your problem now bestie 😭
• sysctl_ctx_entry_find() searches for a given oidp within a context list, either returning a pointer to the struct sysctl_ctx_entry found, or NULL 🔍

---

🦋 EXAMPLES 🦋

here's how you create a new top-level category and hook up another subtree to an existing static node. this example uses contexts to keep track of the OIDs 👑

#include <sys/sysctl.h>
 ...
static struct sysctl_ctx_list clist;
static struct sysctl_oid *oidp;
static int a_int;
static const char *string = "dynamic sysctl";
 ...

sysctl_ctx_init(&clist);
oidp = SYSCTL_ADD_ROOT_NODE(&clist,
        OID_AUTO, "newtree", CTLFLAG_RW, 0, "new top level tree");
oidp = SYSCTL_ADD_INT(&clist, SYSCTL_CHILDREN(oidp),
        OID_AUTO, "newint", CTLFLAG_RW, &a_int, 0, "new int leaf");
 ...
oidp = SYSCTL_ADD_NODE(&clist, SYSCTL_STATIC_CHILDREN(_debug),
        OID_AUTO, "newtree", CTLFLAG_RW, 0, "new tree under debug");
oidp = SYSCTL_ADD_STRING(&clist, SYSCTL_CHILDREN(oidp),
        OID_AUTO, "newstring", CTLFLAG_RD, string, 0, "new string leaf");
 ...
/* Now we can free up the OIDs */
if (sysctl_ctx_free(&clist)) {
        printf("can't free this context - other OIDs depend on it");
        return (ENOTEMPTY);
} else {
        printf("Success!\n");
        return (0);
}

this example creates the following subtrees:

debug.newtree.newstring
newtree.newint

note that both trees are removed, and their resources freed, through one sysctl_ctx_free() call, which starts by freeing the newest entries (leaves) and then proceeds to free the older entries (in this case the nodes). one call, whole cleanup, ate and left no crumbs 💅✨

---

🌟 SEE ALSO 🌟

• queue(3)
• sysctl(8)
• sysctl(9)
• sysctl_add_oid(9)
• sysctl_remove_oid(9)

---

💜 HISTORY 💜

these functions first appeared in FreeBSD 4.2. vintage but still slaying 🎀

---

👑 AUTHORS 👑

Andrzej Bialecki <abial@FreeBSD.org> — thank you bestie, we owe you one 🫶

---

💀 BUGS 💀

• the current removal algorithm is somewhat heavy. in the worst case, all OIDs need to be unregistered, registered again, and then unregistered and deleted. but ngl, the algorithm does guarantee transactional properties for removal operations, so it's giving messy but reliable 😭
• all operations on contexts involve linked list traversal. for this reason, creation and removal of entries is relatively costly. not me paying the linked-list tax 🙈

---

and that's the whole page bestie! this came to you from the Debian-flavored copy of the page dated July 31, 2014 — yes, it's an oldie, but it's still out here doing main character work in the kernel. mwah 💋