OSD(9)

📦 version 15.1, in freebsd 14.5, freebsd 15.1, nixpkgs unstable

💅 OSD(9) — Object Specific Data 💅

Okay bestie, so this is the OSD(9) page from the Kernel Developer's Manual — and honestly? It's giving iconic kernel infrastructure realness. We're talking about the Object Specific Data framework, which is basically the ✨main character✨ of dynamic data association in the kernel. Let me break it down for you, no cap.

Here's the lineup of all the functions we're gonna talk about:

osd, osd_register, osd_deregister, osd_set, osd_reserve, osd_set_reserved, osd_free_reserved, osd_get, osd_del, osd_call, osd_exit

✨ SYNOPSIS ✨

Like, here's the whole squad of function signatures — keep these exactly as-is, bestie, they're literally the blueprint:

#include <sys/osd.h>

typedef void
(*osd_destructor_t)(void *value);

typedef int
(*osd_method_t)(void *obj, void *data);

int
osd_register(u_int type, osd_destructor_t destructor,
    const osd_method_t *methods);

void
osd_deregister(u_int type, u_int slot);

int
osd_set(u_int type, struct osd *osd, u_int slot, void *value);

void **
osd_reserve(u_int slot);

int
osd_set_reserved(u_int type, struct osd *osd, u_int slot, void **rsv,
    void *value);

void
osd_free_reserved(void **rsv);

void *
osd_get(u_int type, struct osd *osd, u_int slot);

void
osd_del(u_int type, struct osd *osd, u_int slot);

int
osd_call(u_int type, u_int method, void *obj, void *data);

void
osd_exit(u_int type, struct osd *osd);

🦋 DESCRIPTION 🦋

Okay so the osd framework is literally the matchmaker of the kernel — it dynamically associates arbitrary data at run-time with any kernel data structure that's been suitably modified for use with osd. The one-off modification required? Just embed a struct osd inside the kernel data structure. That's it. Periodt. 💅

The glow-up here is that after the initial change to a structure is made, all subsequent use of osd with the structure involves zero changes to the structure's layout. By extension, if the data structure is part of the ABI, osd provides a way of extending the structure in an ABI-preserving manner. It's giving "we can grow without breaking things" energy. 🔥

The details of the embedded struct osd are not relevant to consumers of the osd framework and should not be manipulated directly. Like, don't touch — not yours. 🙈

Data associated with a structure is referenced by the osd framework using a type/slot identifier pair. Types are statically defined in <sys/osd.h> and provide a high-level grouping for slots to be registered under. Slot identifiers are dynamically assigned by the framework when a data type is registered using osd_register() and remain valid until a corresponding call to osd_deregister(). It's literally a whole dynamic duo situation. 🎀

💖 Functions 💖

osd_register() — registers a type/slot identifier pair with the osd framework for use with a new data type. The function may sleep and therefore cannot be called from a non-sleepable context. The type argument specifies which high-level type grouping from <sys/osd.h> the slot identifier should be allocated under. The destructor argument specifies an optional osd_destructor_t function pointer that will be called for objects of the type being registered which are later destroyed by the osd_del() function. NULL may be passed if no destructor is required. The methods argument specifies an optional array of osd_method_t function pointers which can be later invoked by the osd_call() function. NULL may be passed if no methods are required. The methods argument is currently only useful with the OSD_JAIL type identifier. (iykyk 🔐)
osd_deregister() — deregisters a previously registered type/slot identifier pair. The function may sleep and therefore cannot be called from a non-sleepable context. The type argument specifies which high-level type grouping from <sys/osd.h> the slot identifier is allocated under. The slot argument specifies the slot identifier which is being deregistered and should be the value that was returned by osd_register() when the data type was registered. It's literally the "you're done here" button. 💀
osd_set() — associates a data object pointer with a kernel data structure's struct osd member. The type argument specifies which high-level type grouping from <sys/osd.h> the slot identifier is allocated under. The osd argument is a pointer to the kernel data structure's struct osd which will have the value pointer associated with it. The slot argument specifies the slot identifier to assign the value pointer to. The value argument points to a data object to associate with osd. This is the "make it official" function. 🫶
osd_set_reserved() — does the same as osd_set(), but with an extra argument rsv that is internal-use memory previously allocated via osd_reserve(). Like, it's the VIP backstage pass version of osd_set(). 🎟️
osd_get() — returns the data pointer associated with a kernel data structure's struct osd member from the specified type/slot identifier pair. The type argument specifies which high-level type grouping from <sys/osd.h> the slot identifier is allocated under. The osd argument is a pointer to the kernel data structure's struct osd to retrieve the data pointer from. The slot argument specifies the slot identifier to retrieve the data pointer from. The retrieval pipeline is giving "constant time and fast" energy. ⚡
osd_del() — removes the data pointer associated with a kernel data structure's struct osd member from the specified type/slot identifier pair. The type argument specifies which high-level type grouping from <sys/osd.h> the slot identifier is allocated under. The osd argument is a pointer to the kernel data structure's struct osd to remove the data pointer from. The slot argument specifies the slot identifier to remove the data pointer from. If an osd_destructor_t function pointer was specified at registration time, the destructor function will be called and passed the data pointer for the type/slot identifier pair which is being deleted. It's giving cleanup era. 🧹
osd_call() — calls the specified osd_method_t function pointer for all currently registered slots of a given type on the specified obj and data pointers. The function may sleep and therefore cannot be called from a non-sleepable context. The type argument specifies which high-level type grouping from <sys/osd.h> to call the method for. The method argument specifies the index into the osd_method_t array that was passed to osd_register(). The obj and data arguments are passed to the method function pointer of each slot. This is literally the "summon the whole group chat" function. 📞
osd_exit() — removes all data object pointers from all currently registered slots for a given type for the specified kernel data structure's struct osd member. The type argument specifies which high-level type grouping from <sys/osd.h> to remove data pointers from. The osd argument is a pointer to the kernel data structure's struct osd to remove all data object pointers for all currently registered slots from. It's the "everybody out of the pool" moment. 🏊‍♀️

👑 IMPLEMENTATION NOTES 👑

osd uses a two dimensional matrix (array of arrays) as the data structure to manage the external data associated with a kernel data structure's struct osd member. The type identifier is used as the index into the outer array, and the slot identifier is used as the index into the inner array. To set or retrieve a data pointer for a given type/slot identifier pair, osd_set() and osd_get() perform the equivalent of array[type][slot], which is both constant time and fast. Like, the efficiency is honestly stunning. ✨

If osd_set() is called on a struct osd for the first time, the array for storing data pointers is dynamically allocated using malloc(9) with M_NOWAIT to a size appropriate for the slot identifier being set. If a subsequent call to osd_set() attempts to set a slot identifier which is numerically larger than the slot used in the previous osd_set() call, realloc(9) is used to grow the array to the appropriate size such that the slot identifier can be used. To maximise the efficiency of any code which calls osd_set() sequentially on a number of different slot identifiers (e.g., during an initialisation phase) one should loop through the slot identifiers in descending order from highest to lowest. This will result in only a single malloc(9) call to create an array of the largest slot size and all subsequent calls to osd_set() will proceed without any realloc(9) calls. Bestie, this is the optimization tip you didn't know you needed. 📈

⚠️ It is possible for osd_set() to fail to allocate this array. To ensure that such allocation succeeds, osd_reserve() may be called (in a non-blocking context), and it will pre-allocate the memory via malloc(9) with M_WAITOK. Then this pre-allocated memory is passed to osd_set_reserved(), which will use it if necessary or otherwise discard it. The memory may also be explicitly discarded by calling osd_free_reserved(). As this method always allocates memory whether or not it is ultimately needed, it should be used only rarely, such as in the unlikely event that osd_set() fails. Like, don't overuse this, bestie — it's giving "emergency backup plan" vibes. 🚨

The osd API is geared towards slot identifiers storing pointers to the same underlying data structure type for a given osd type identifier. This is not a requirement, and khelp(9) for example stores completely different data types in slots under the OSD_KHELP type identifier. Flexible queen behavior. 💅

🔒 Locking 🔒

osd internally uses a mix of mutex(9), rmlock(9) and sx(9) locks to protect its internal data structures and state. It's a whole security detail situation. 🛡️

Responsibility for synchronising access to a kernel data structure's struct osd member is left to the subsystem that uses the data structure and calls the osd API. Like, you gotta handle your own vibes here. 🤷‍♀️

osd_get() only acquires an rmlock(9) in read mode, therefore making it safe to use in the majority of contexts within the kernel including most fast paths. It's giving "I can go anywhere without causing drama" energy. 🦋

🌸 RETURN VALUES 🌸

osd_register() returns the slot identifier for the newly registered data type. That's your new bestie's phone number, basically. 📱
osd_set() and osd_set_reserved() return zero on success or ENOMEM if the specified type/slot identifier pair triggered an internal realloc(9) which failed (osd_set_reserved() will always succeed when rsv is non-NULL). So like, if rsv is giving, you're good. 🙌
osd_get() returns the data pointer for the specified type/slot identifier pair, or NULL if the slot has not been initialised yet. No data = no cap, just NULL. 💀
osd_reserve() returns a pointer suitable for passing to osd_set_reserved() or osd_free_reserved(). It's the golden ticket. 🎫
osd_call() returns zero if no method is run or the method for each slot runs successfully. If a method for a slot returns non-zero, osd_call() terminates prematurely and returns the method's error to the caller. So like, if something goes wrong, it bails immediately — no continuing the group call after the drama starts. 😭

🔥 SEE ALSO 🔥

khelp(9)

⭐ HISTORY ⭐

The Object Specific Data (OSD) facility first appeared in FreeBSD 8.0. A legend was born. 👑

💜 AUTHORS 💜

The osd facility was written by Pawel Jakub Dawidek <pjd@FreeBSD.org>.

This manual page was written by Lawrence Stewart <lstewart@FreeBSD.org>.

Okay bestie, that's the whole OSD(9) page — every detail, every function, every vibe preserved. This iconique page comes to you courtesy of Debian and the date October 07, 2024, under the manual section OSD(9). Slay. 💅✨

📦 where this page comes from

freebsd 14.5: base 14.5
freebsd 15.1: base 15.1
nixpkgs unstable: source
💖 girlified by deepseek-ai/DeepSeek-V4.1-Flash-1017 on 2026-11-04: a language model's rewrite of the original, under its terms