PTHREAD_KEYCREATE(3P)                BSD                 PTHREAD_KEYCREATE(3P)



NAME
     pthread_keycreate - Creates a key to be used with thread-specific data

SYNOPSIS
     #include <pthread.h>

     int pthread_keycreate (key, destructor, value)
     pthread_key_t *key;
     void (*destructor)(void *value);

DESCRIPTION
     The pthread_keycreate function creates a key. A key is an opaque object
     that can be seen by all of the threads in a process. Each thread can bind
     its own value to that key using the pthread_setspecific() function; the
     value is maintained by the thread until the thread exits.

     The arguments specify the following:

     destructor
            Specifies the address of an optional destructor function.

     value  Specifies the value associated with the key.

     key    Specifies the address in which the new key will be stored.

     Ordinarily, the value that a thread binds to a key will be a pointer to
     storage allocated dynamically on behalf of that thread. To have this
     storage freed when the thread exits, use the destructor function. If the
     old value needs to be destroyed before the new value is bound, then the
     calling thread must use the pthread_getspecific(3P) function and call the
     destructor explicitly itself.  The destructor function is also called
     when the thread exits if the value bound is not null.  If you do not
     specify destructor, no destructor function is called.

NOTES
     This interface is based on draft 4 of the IEEE P1003.4a standard, and
     will be changed to conform to the final version.

DIAGNOSTICS
     Upon successful completion, the newly created key is stored at *key, and
     a value of 0 (zero) is returned. Otherwise, no key is created, -1 is
     returned, and errno is set to indicate the error.

ERRORS
     If the pthread_keycreate function fails, errno may be set to one of the
     following values:

     [EAGAIN]  There is not enough memory to create the key.

     [ENOMEM]  The key name space is exhausted, so the key cannot be
               allocated. This is not a temporary condition.

     [EINVAL]  The value specified by the destructor, value, or key argument
               is invalid.

SEE ALSO
     pthread_getspecific(3P), pthread_setspecific(3P)