SPECIFICDATA(9)

SPECIFICDATA(9) | Kernel Developer's Manual | SPECIFICDATA(9)

# NAME

`specificdata`, `specificdata_domain_create`, `specificdata_domain_delete`, `specificdata_key_create`, `specificdata_key_delete`, `specificdata_init`, `specificdata_fini`, `specificdata_getspecific`, `specificdata_getspecific_unlocked`, `specificdata_setspecific`, `specificdata_setspecific_nowait` —
manipulate arbitrary data attached to objects

# SYNOPSIS

`#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

The `specificdata` facility provides a mechanism for storing arbitrary data, identified by an index key, within containers which exist within the objects associated with a particular domain.

# FUNCTIONS

`specificdata_domain_create`()
  Create and initialize a new domain.
`specificdata_domain_delete`(sd)
  Deletes domain sd.
`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.
`specificdata_key_delete`(sd, key)
  Delete a key for sd, and delete any associated data from all containers within the domain.
`specificdata_init`(sd, ref)
  Initialize the container ref for use in sd.
`specificdata_fini`(sd, ref)
  Destroy the container ref, and destroy all of the data stuffed into the container.
`specificdata_getspecific`(sd, ref, key)
  Retrieve the datum from the container ref associated with key.
`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.
`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.
`specificdata_setspecific_nowait`(sd, ref, key, data)
  (Unimplemented)

# CODE REFERENCES

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

The header file `<sys/sys/specificdata.h>` describes the public interface.

# HISTORY

The `specificdata` subsystem first appeared in NetBSD 4.0.

# AUTHORS

The `specificdata` subsystem was written by Jason Thorpe <thorpej@NetBSD.org>. This manual page was written by Paul Goyette <pgoyette@NetBSD.org>.

June 16, 2018 | NetBSD 9.0