# pthread_getspecific

## PROLOG



           This manual page is part of the POSIX Programmer's Manual.  The
           Linux implementation of this interface may differ (consult the
           corresponding Linux manual page for details of Linux behavior), or
           the interface may not be implemented on Linux.
    


## NAME



           pthread_getspecific, pthread_setspecific — thread-specific data
           management
    


## SYNOPSIS



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


## DESCRIPTION



           The _pthread_getspecific_() function shall return the value
           currently bound to the specified _key_ on behalf of the calling
           thread.
    
           The _pthread_setspecific_() function shall associate 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 effect of calling _pthread_getspecific_() or
           _pthread_setspecific_() with a _key_ value not obtained from
           _pthread_key_create_() or after _key_ has been deleted with
           _pthread_key_delete_() is undefined.
    
           Both _pthread_getspecific_() and _pthread_setspecific_() may be called
           from a thread-specific data destructor function. A call to
           _pthread_getspecific_() for the thread-specific data key being
           destroyed shall return the value NULL, unless the value is changed
           (after the destructor starts) by a call to _pthread_setspecific_().
           Calling _pthread_setspecific_() from a thread-specific data
           destructor routine may result either in lost storage (after at
           least PTHREAD_DESTRUCTOR_ITERATIONS attempts at destruction) or in
           an infinite loop.
    
           Both functions may be implemented as macros.
    


## RETURN VALUE



           The _pthread_getspecific_() function shall return the thread-
           specific data value associated with the given _key_.  If no thread-
           specific data value is associated with _key_ , then the value NULL
           shall be returned.
    
           If successful, the _pthread_setspecific_() function shall return
           zero; otherwise, an error number shall be returned to indicate the
           error.
    


## ERRORS



           No errors are returned from _pthread_getspecific_().
    
           The _pthread_setspecific_() function shall fail if:
    
           **ENOMEM** Insufficient memory exists to associate the non-NULL value
                  with the key.
    
           The _pthread_setspecific_() function shall not return an error code
           of **[EINTR]**.
    
           _The following sections are informative._
    


## EXAMPLES



           None.
    


## APPLICATION USAGE



           None.
    


## RATIONALE



           Performance and ease-of-use of _pthread_getspecific_() are critical
           for functions that rely on maintaining state in thread-specific
           data. Since no errors are required to be detected by it, and since
           the only error that could be detected is the use of an invalid
           key, the function to _pthread_getspecific_() has been designed to
           favor speed and simplicity over error reporting.
    
           If an implementation detects that the value specified by the _key_
           argument to _pthread_setspecific_() does not refer to a a key value
           obtained from _pthread_key_create_() or refers to a key that has
           been deleted with _pthread_key_delete_(), it is recommended that the
           function should fail and report an **[EINVAL]** error.
    


## FUTURE DIRECTIONS



           None.
    


* * *