NAME

thr_keycreate, thr_setspecific, thr_getspecific − thread-specific data

SYNOPSIS

#include <thread.h>

int thr_keycreate(thread_key_t ∗keyp, void (∗destructor)(void ∗value));

int thr_setspecific(thread_key_t key, void ∗value);

int thr_getspecific(thread_key_t key, void ∗∗valuep);

MT-LEVEL

MT-Safe

DESCRIPTION

thr_keycreate() allocates a key that is used to identify data that is specific to each thread in the process.  The key is global to all threads in the process.  Once a key has been created each thread may bind a value to the key.  The values are specific to the binding thread and are maintained for each thread independently.  All threads initially have the value NULL associated with the key when it is created.  When thr_keycreate() returns successfully the allocated key is stored in the location pointed to by keyp. The caller must ensure that storage and access to this key are properly synchronized.

An optional destructor function, specified by destructor, may be associated with each key. If a key has a non-NULL destructor function and the thread has a non-NULL value associated with that key, the destructor function is called with the current associated value when the thread exits.  The order in which the destructor functions are called for all the allocated keys is unspecified. 

thr_setspecific() binds value to the thread-specific data key, key, for the calling thread.

thr_getspecific() stores the current value bound to key for the calling thread into the location pointed to by valuep.

RETURN VALUES

Zero is returned when successful.  A non-zero value indicates an error. 

ERRORS

If any of the following conditions is detected, thr_keycreate() fails and returns the corresponding value:

EAGAIN The key name space is exhausted. 

If any of the following conditions is detected, thr_keycreate() and thr_setspecific() fail and returns the corresponding value:

ENOMEM Not enough memory is available. 

If any of the following conditions is detected, thr_setspecific() and thr_getspecific() fail and returns the corresponding value:

EINVAL key is invalid. 

EXAMPLE

This examples shows the use of thread-specific data in a function that can be called from more than one thread without special initialization. 

static mutex_t keylock;
static thread_key_t key;
static int once = 0;
func()
{
void ∗ptr;
(void) mutex_lock(&keylock);
if (!once) {
(void) thr_keycreate(&key, free);
once++;
}
(void) mutex_unlock(&keylock);
(void) thr_getspecific(key, (void ∗)&ptr);
if (ptr == NULL) {
ptr = malloc(SIZE);
(void) thr_setspecific(key, ptr);
}
}

SEE ALSO

thr_exit(3T). 

SunOS 5.2  —  Last change: 22 Jan 1993