pthread_getspecific or pthread_setspecific Subroutine

Purpose

Returns and sets the thread-specific data associated with the specified key.

Library

Threads Library (libpthreads.a)

Syntax

#include <pthread.h>
void *pthread_getspecific (key)
pthread_key_t key;
int pthread_setspecific (key, value)
pthread_key_t key; 
const void *value;

Description

The pthread_setspecific function associates a thread-specific value with a key obtained via a previous call to pthread_key_create. Different threads may bind different values to the same key. These values are typically pointers to blocks of dynamically allocated memory that have been reserved for use by the calling thread.

The pthread_getspecific function returns the value currently bound to the specified key on behalf of the calling thread.

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

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.

Parameters

Item Description
key Specifies the key to which the value is bound.
value Specifies the new thread-specific value.

Return Values

The function 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. If successful, the pthread_setspecific function returns zero. Otherwise, an error number is returned to indicate the error.

Error Codes

The pthread_setspecific function will fail if:

Item Description
ENOMEM Insufficient memory exists to associate the value with the key.

The pthread_setspecific function may fail if:

Item Description
EINVAL The key value is invalid.

No errors are returned from pthread_getspecific.

These functions will not return an error code of EINTR.