pthread_key_create(3T)            SDK R4.11           pthread_key_create(3T)


NAME
       pthreadkeycreate - create a thread-specific data key

SYNOPSIS
       #include <pthread.h>

       int pthreadkeycreate(pthreadkeyt *key,
                              void (*destructor)(void *value));

   where:
       key         A pointer to the location to receive the new thread-
                   specific data key
       destructor  A pointer to an optional destructor function, or NULL

DESCRIPTION
       This function creates a key visible to all threads in the process.
       Keys returned by pthreadkeycreate() are opaque objects used to
       locate thread-specific data in a portable way.  Although the same key
       value may be used by different threads, the values bound to the key
       by pthreadsetspecific() are maintained on a per-thread basis and
       persist for the life of the calling thread.

       Upon key creation, the value NULL is associated with the new key in
       all active threads.  Upon thread creation, the value NULL is
       associated with all defined keys in the new thread.

       An optional destructor function may be associated with each key
       value.  At thread exit, if a key value has a non-NULL destructor
       pointer, and the thread has a non-NULL value associated with that
       key, the function pointed to is called with the currently associated
       value.  The order of destructor calls is unspecified if more than one
       destructor exists for a thread when it exits.  Destructor functions
       are invoked after any cancellation handlers.

DIAGNOSTICS
   Return Value
       If successful, pthreadkeycreate() stores the newly created key at
       the location pointed by key and returns 0.  Otherwise it returns -1,
       creates no key, and sets errno to indicate the error.

   Errors
       For each of the following conditions, pthreadkeycreate() returns -1
       and sets errno to the corresponding value:

       [EAGAIN]  The function tried to allocate a key when the key name
                 space was exhausted.

       [ENOMEM]  Insufficient memory exists to create the key.   DG/UX does
                 not currently return this error.

SEE ALSO
       pthreadsetspecific(3T), pthreadgetspecific(3T), pthreadexit(3T),
       threads(5).

NOTES
       A key can best be thought of as a "variable name." Each thread's
       value for the key is just an instance of the variable.  Without
       standard compiler support for private data, thread-specific data must
       be specified with this procedural interface.

       Typically, keys are allocated during program initialization.

       The maximum number of keys per-process is defined by
       POSIXDATAKEYSMAX.  If an application requires more thread-specific
       data variables than allowed keys, it can group its variables together
       into a single structure or array that is dynamically allocated on a
       per-thread basis and associated with a single data key.  The C
       library uses one key which reduces the number of keys available for
       most programs to POSIXDATAKEYSMAX-1.

       The final standard will likely include pthreadkeydelete for freeing
       a key that is no longer in use.

       A thread can only gain access to its own values associated with the
       per-process keys and destructors.

       The effect of simultaneous calls to pthreadkeycreate() by different
       threads that specify the same key address is undefined.


Licensed material--property of copyright holder(s)