specificdata(9) - NetBSD Manual Pages

SPECIFICDATA(9)        NetBSD 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 con-
           tainers 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 con-
           tainer) by issuing a setspecific() call or by destroying the con-
           tainer.

     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 origi-
           nal; 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>.

NetBSD 9.1                       June 16, 2018                      NetBSD 9.1