pthread_setspecific(3pthread)

pthread_setspecific, pthread_getspecific -- thread-specific data management

Synopsis

   cc [options] -Kthread file
   
   #include <pthread.h>
   

   int pthread_setspecific(pthread_key_t *key, const void (*value);
   void *pthread_getspecific(pthread_key_t *key);

Description

pthread_setspecific associates a thread-specific value with key. Different threads can bind different values to the same key.

If the value bound to key must be updated during the lifetime of the thread, the caller must release the storage associated with the old value before a new value is bound, or the storage is lost.

pthread_getspecific obtains the value currently bound to the specified key on behalf of the calling thread.

Both pthread_setspecific and pthread_getspecific may be called from a thread-specific data destructor function. However, calling pthread_setspecific from a destructor may result in lost storage or infinite loops.

The key parameter is a key obtained with a previous call to pthread_key_create, whose value is returned by pthread_getspecific and to which value is bound by pthread_setspecific.

The effect of calling pthread_setspecific with a key value not obtained with pthread_key_create or after key has been deleted with pthread_key_delete is undefined.

The value parameter is a pointer to thread-specific date, or NULL. value is typically a pointer to blocks of dynamically-allocated memory that have been reserved for use by the calling thread. If value is NULL, the calling thread will give up a non-NULL reference to key.

Return values

pthread_setspecific returns zero for success and an error number for failure, as described below.

pthread_getspecific returns the thread-specific data value associated with the given key. If no thread-specific data value is associated with key, then the value NULL is returned.

pthread_getspecific is not guaranteed to detect an invalid key. If pthread_getspecific returns NULL, either no value is currently bound to key, the value bound to key is NULL, or key is invalid. In this case, the caller can determine whether key is invalid by calling

   pthread_setspecific(key, NULL)

to get the applicable error number.

Diagnostics

pthread_setspecific returns the following values if their corresponding conditions are detected:

EINVAL: The key value is invalid.
ENOMEM: There is not sufficient memory available to associate value with key.

pthread_getspecific returns no errors.

Standards Compliance

The Single UNIX Specification, Version 2; The Open Group.

References

Intro(3pthread), pthread_key_create(3pthread), pthread_key_delete(3pthread), pthread(4)

Notices

Although there is no fixed limit on the number of keys in a process, a large number of keys will consume memory and slow thread exit performance.