SOCKOPT(9)

✨ SOCKOPT(9) — the socket options glow-up guide ✨

okay so this is the sockopt(9) page from the Kernel Developer's Manual, and bestie, it's literally all about handling socket options in kernel land. no cap, it's giving "small struct, big responsibilities" energy. let's get into it 💅

---

🌸 NAME 🌸

sockopt_init, sockopt_destroy, sockopt_get, sockopt_getint, sockopt_set, sockopt_setint — socket options handling. yes ma'am, the whole friend group 🫶

---

🎀 SYNOPSIS 🎀

#include <sys/socketvar.h>

void
sockopt_init(struct sockopt *sopt, int level, int name, size_t size);

void
sockopt_destroy(struct sockopt *sopt);

int
sockopt_get(struct sockopt *sopt, void *value, size_t size);

int
sockopt_getint(struct sockopt *sopt, int *value);

int
sockopt_set(struct sockopt *sopt, const void *value, size_t size);

int
sockopt_setint(struct sockopt *sopt, int value);

like, copy that exactly, bestie. character for character. no typos, periodt 💖

---

🦋 DESCRIPTION 🦋

so the sockopt structure is what passes a socket option and its associated value around. it's giving "carry the whole vibe in one little struct":

struct sockopt {
        int             sopt_level;             /* option level */
        int             sopt_name;              /* option name */
        size_t          sopt_size;              /* data length */
        size_t          sopt_retsize;           /* returned data length */
        void *          sopt_data;              /* data pointer */
        uint8_t         sopt_buf[sizeof(int)];  /* internal storage */
};

the internal storage exists for the common case of values up to integer size, so that memory allocation is literally not required — and in that case sopt_data will point to this internal storage. iconic efficiency, honestly 🌟

so here's the tea: instead of providing accessor functions, the sockopt structure is public and its contents are expected to be internally consistent. but the normal practice would be to use the appropriate methods for storage and retrieval of values where a known datatype is expected, because the size will be verified. iykyk 🔥

Note: a sockopt structure may only be used for a single level/name/size combination. if the structure is to be re-used, it must be destroyed and re-initialized with the new values. no recycling your ex, bestie 💀

---

✨ OPTIONS ✨

• options DIAGNOSTIC — kernels compiled with the DIAGNOSTIC option will perform basic sanity checks on socket options operations. it's giving "paranoid but make it fashion" 🕵️‍♀️

---

💜 FUNCTIONS 💜

• sockopt_init(sopt, level, name, size) — initialise sockopt storage. if size is given, sockopt_init() will arrange for sopt_data to point to a buffer of size bytes for the sockopt value. where memory needs to be allocated to satisfy this, sockopt_init() may sleep. so like, don't call it somewhere you can't nap 😴
• sockopt_destroy(sopt) — destroy sockopt storage, releasing any allocated memory. it's the cleanup era, we love to see it 🧹
• sockopt_get(sopt, value, size) — copy out sockopt value. will return EINVAL if an incorrect data size is given. size mismatch? blocked and reported 🚫
• sockopt_getint(sopt, value) — common case of get sockopt integer value. will return EINVAL if sockopt does not contain an integer sized value. int-sized or it's not invited to the party 🙈
• sockopt_set(sopt, value, size) — copy in sockopt value. the sockopt structure must contain a data field of size bytes or be previously unset, in which case a data buffer may be allocated using kmem_alloc(9) with the KM_NOSLEEP flag which may cause sockopt_set() to return ENOMEM. allocation said "not today" and now you're dealing with ENOMEM, oof 😭

Note: if you need to use sockopt_set() in a context where memory allocation may be required and you do not wish to contemplate failure, the sockopt structure can be initialised in a more suitable context using sockopt_init() which will not fail. plan ahead and slay 💅

• sockopt_setint(sopt, value) — common case of set sockopt integer value. the sockopt structure must contain an int sized data field or be previously unset, in which case the data pointer will be set to the internal storage. tiny value, no allocation drama, we love a low-maintenance icon 👑

---

🌈 CODE REFERENCES 🌈

the function prototypes and sockopt structure are defined in the sys/sys/socketvar.h header file, and the socket options implementation is in sys/kern/uipc_socket.c. go read the source, bestie, it's giving main character energy 📖

---

🌸 SEE ALSO 🌸

errno(2), kmem(9)

like, go look at those too. cross-referencing is self-care 🫶

---

🎀 HISTORY 🎀

the socket options KPI was inspired by a similar KPI in FreeBSD and first appeared in NetBSD 5.0. a little throwback moment for the lore keepers 💖

---

and that's the whole page, bestie — no details dropped, no flags forgotten, no cap. this gorgeous little doc is from the Debian edition, dated January 3, 2018, and it lives its best life as SOCKOPT(9). mwah 💋✨