NAME

    pthread_keycreate - Generates a unique thread-specific data
                        key value

 SYNOPSIS

     #include <pthread.h>

     int pthread_keycreate( pthread_key_t        *key,
                            pthread_destructor_t destructor );

 PARAMETERS

     key                Value of the new thread-specific data key.

     destructor         Procedure to be called to destroy a data value
                        associated with the created key when the thread
                        terminates.

 DESCRIPTION

 The pthread_keycreate()  routine generates a unique thread-specific
 data key value.  This key value identifies a thread-specific data
 value, which is an address of memory generated by the client containing
 arbitrary data of any size.

 Thread-specific data allows client software to associate information
 with the current thread.

 For example, thread-specific data can be used by a language runtime
 library that needs to associate a language-specific thread-private data
 structure with an individual thread. The thread-specific data routines
 also provide a portable means of implementing the class of storage
 called thread-private static, which is needed  to support parallel
 decomposition in the FORTRAN language.

 This routine generates and returns a new key value. Each call to this
 routine within a process returns a key value that is unique within an
 application invocation. Calls to pthread_keycreate() must occur in ini-
 tialization code guaranteed to execute only once in each process.  The
 pthread_once() routine provides a way of specifying such code.

 When multiple facilities share access to thread-specific data, the
 facilities must agree on the key value that is associated with the con-
 text. The key value must be created only once and needs to be stored in
 a location known to each facility. (It may be desirable to encapsulate
 the creation of a key, and the setting and getting of context values for
 that key, within a special facility created for that purpose.)

 When a thread terminates, thread-specific data is automatically des-
 troyed. For each thread-specific data currently associated with the
 thread, the destructor routine associated with the key value of that
 context is called. The order in which per-thread context destructors are
 called at thread termination is undefined.

 RETURN VALUES

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

    Return   Error      Description
    _________________________________________________________________
     0                  Successful completion.

    -1      [EINVAL]    The value specified by key is invalid.

    -1      [EAGAIN]    An attempt was made to allocate a key when
                        the key namespace is exhausted.  This is not
                        a temporary condition.

    -1      [ENOMEM]    Insufficient memory exists to create the key.

 RELATED INFORMATION

     FUNCTIONS: pthread_getspecific
                pthread_setspecific