SPECIFICDATA(9)

🎀 SPECIFICDATA(9) — arbitrary data, but make it iconic 🎀

💖 NAME 💖

okay bestie, this whole page is about specificdata and its lil crew: specificdata_domain_create, specificdata_domain_delete, specificdata_key_create, specificdata_key_delete, specificdata_init, specificdata_fini, specificdata_getspecific, specificdata_getspecific_unlocked, specificdata_setspecific, and specificdata_setspecific_nowait. Together they manipulate arbitrary data attached to objects. Slay.

---

✨ SYNOPSIS ✨

first up, include this exactly:

#include <sys/specificdata.h>

specificdata_domain_t
specificdata_domain_create();

void
specificdata_domain_delete(specificdata_domain_t sd);

int
specificdata_key_create(specificdata_domain_t sd,
    specificdata_key_t *keyp, specificdata_dtor_t dtor);

void
specificdata_key_delete(specificdata_domain_t sd,
    specificdata_key_t key);

int
specificdata_init(specificdata_domain_t sd,
    specificdata_reference *ref);

void
specificdata_fini(specificdata_domain_t sd,
    specificdata_reference *ref);

void *
specificdata_getspecific(specificdata_domain_t sd,
    specificdata_reference *ref, specificdata_key_t key);

void *
specificdata_getspecific_unlocked(specificdata_domain_t sd,
    specificdata_reference *ref, specificdata_key_t key);

void
specificdata_setspecific(specificdata_domain_t sd,
    specificdata_reference *ref, specificdata_key_t key, void *data);

int
specificdata_setspecific_nowait(specificdata_domain_t sd,
    specificdata_reference *ref, specificdata_key_t key, void *data);

---

🦋 DESCRIPTION 🦋

okay so the specificdata facility is literally a whole mechanism for storing arbitrary data, identified by an index key, inside containers which exist within the objects associated with a particular domain. That's the vibe. It's giving "attach your stuff to objects, but organized."

---

💅 FUNCTIONS 💅

🌸 specificdata_domain_create()

Create and initialize a new domain. New domain era, honestly.

🌸 specificdata_domain_delete(sd)

Deletes domain sd. Bye bestie.

🌸 specificdata_key_create(sd, keyp, dtor)

Create a new key for sd. If the dtor argument is not NULL, it specifies a destructor which will be called when a datum associated with the specified key is deleted from a container within the sd. The unique identifier of the created key is returned in keyp. Cute and functional.

🌸 specificdata_key_delete(sd, key)

Delete a key for sd, and delete any associated data from all containers within the domain. It's a whole cleanup moment.

🌸 specificdata_init(sd, ref)

Initialize the container ref for use in sd. Container is ready for its main character era.

🌸 specificdata_fini(sd, ref)

Destroy the container ref, and destroy all of the data stuffed into the container. Very "closing the group chat" energy.

🌸 specificdata_getspecific(sd, ref, key)

Retrieve the datum from the container ref associated with key. Got it.

🌸 specificdata_getspecific_unlocked(sd, ref, key)

Retrieve the datum from the container ref associated with key in a lockless manner. Care must be taken to ensure that no other thread could cause ref to become invalid (i.e. point at the wrong container) by issuing a setspecific() call or by destroying the container. This is the careful part, bestie — do not skip the vibe check.

🌸 specificdata_setspecific(sd, ref, key, data)

Store data in the container ref and associate it with key. If a datum has previously been stored, the new value replaces the original; the original value is not destroyed, i.e. its destructor is not invoked. Note that there is no provision for removing a datum without replacing it. So yes: replacement is the move, and the old datum does not get a destructor send-off here.

🌸 specificdata_setspecific_nowait(sd, ref, key, data)

(Unimplemented) — that's the whole note, no cap.

---

🌈 CODE REFERENCES 🌈

The specificdata functionality is implemented in sys/kern/subr_specificdata.c.

The header file <sys/sys/specificdata.h> describes the public interface. Yes, that is the exact path shown here — keep it exactly as written.

---

⭐ HISTORY ⭐

The specificdata subsystem first appeared in NetBSD 4.0. Vintage, but make it current.

---

👑 AUTHORS 👑

The specificdata subsystem was written by Jason Thorpe <thorpej@NetBSD.org>. This manual page was written by Paul Goyette <pgoyette@NetBSD.org>. Authorship icons only, fr fr.

---

okay that's the page! footer tea: source/version and date are Debian, June 16, 2018, and SPECIFICDATA(9) — mwah 💋✨