UNR(9)

🌸 UNR(9) — the kernel unit number allocator, bestie edition 🌸

Kernel Developer's Manual ✨ okay so this is the glow-up of the UNR(9) page and we are gonna make unit numbers make sense, fr fr.

✨ NAME ✨

new_unrhdr, clear_unrhdr, delete_unrhdr, alloc_unr, alloc_unr_specific, free_unr — the kernel unit number allocator 🎀

🦋 SYNOPSIS 🦋

#include <sys/systm.h>

struct unrhdr *
new_unrhdr(int low, int high, struct mtx *mutex);

void
clear_unrhdr(struct unrhdr *uh);

void
delete_unrhdr(struct unrhdr *uh);

int
alloc_unr(struct unrhdr *uh);

int
alloc_unrl(struct unrhdr *uh);

int
alloc_unr_specific(struct unrhdr *uh, u_int item);

void
free_unr(struct unrhdr *uh, u_int item);

💖 DESCRIPTION 💖

The kernel unit number allocator is a generic facility that lets you allocate unit numbers inside a range you pick. It's giving "hand me a number, any number, but like… within bounds" 💅

• new_unrhdr(low, high, mutex) — spin up a brand new unit number allocator entity, bestie ✨ The low and high arguments say what the minimum and maximum number of unit numbers is. Here's the tea: there's no cost associated with the range of unit numbers, so unless the resource is actually finite, you can just use INT_MAX. If mutex is not NULL, it gets used for locking when allocating and freeing units. If it is NULL, the internal mutex gets used instead. Either way, covered 🫶
• clear_unrhdr(uh) — wipe every unit out of the unit number allocator entity you point at. This resets the whole thing as if it had just been initialized with new_unrhdr(). Fresh start energy 🌈
• delete_unrhdr(uh) — delete that unit number allocator entity. Heads up though 👀 this frees the memory associated with the entity — it does not free any units. If you wanna free all the units, that's a clear_unrhdr() job, not this one. Don't mix them up, iykyk.
• alloc_unr(uh) — hand back a new unit number. The lowest free number is always allocated, no cap. This function does not allocate memory and never sleeps — but it may block on a mutex, so keep that in mind. And if there are no free unit numbers left? You get -1. Sad but true 😭
• alloc_unrl(uh) — literally the same as alloc_unr() except the mutex is assumed to already be locked, so it isn't used. That's the whole difference, periodt.
• alloc_unr_specific(uh, item) — allocate one specific unit number, your chosen one 👑 This function allocates memory and thus may sleep, so plan accordingly. On success you get the allocated unit number back. If the number you asked for is already allocated, or it's out of the range, you get -1 🙈
• free_unr(uh, item) — free a unit number that was previously allocated. This function may require allocating memory, and thus it can sleep 😴 Also: there is no pre-locked variant. None. Don't go looking for one.

🔥 CODE REFERENCES 🔥

All the functions above live in sys/kern/subr_unit.c. That's the address, bestie 💜

🎀 HISTORY 🎀

The kernel unit number allocator first appeared in FreeBSD 6.0. Vintage but still eating 💅

🌟 AUTHORS 🌟

The kernel unit number allocator was written by Poul-Henning Kamp. This manpage was written by Gleb Smirnoff. Legends, honestly 🫶

okay that's the whole page, no skips, no cuts, every flag and every vibe intact 💖

Debian · October 4, 2017 · UNR(9) — mwah, that's the sign-off bestie, ty for reading, go allocate responsibly ✨🎀🦋