NAME    [Toc]    [Back]

     pthread_key_create - thread-specific data key creation

SYNOPSIS    [Toc]    [Back]

     #include <pthread.h>

     int
     pthread_key_create(pthread_key_t         *key,          void
(*destructor)(void *));

DESCRIPTION    [Toc]    [Back]

     The  pthread_key_create() function creates a thread-specific
data key visible
 to all threads in the process.  Key values provided by
     pthread_key_create()  are  opaque  objects  used  to  locate
thread-specific
     data.   Although the same key value may be used by different
threads, the
     values bound to the key by pthread_setspecific()  are  maintained on a perthread
 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  the  key,  the
function pointed
     to  is  called with the current associated value as its sole
argument.  The
     order of destructor calls is unspecified if  more  than  one
destructor exists
 for a thread when it exits.

     If,  after all the destructors have been called for all nonNULL values
     with associated destructors, there are still  some  non-NULL
values with
     associated  destructors,  then the process is repeated.  If,
after at least
     [PTHREAD_DESTRUCTOR_ITERATIONS]  iterations  of   destructor
calls for outstanding
 non-NULL values, there are still some non-NULL values with associated
 destructors, the  implementation  stops  calling  destructors.

RETURN VALUES    [Toc]    [Back]

     If  successful, the pthread_key_create() function will store
the newly
     created key value at the location specified by key  and  returns zero.
     Otherwise  an  error number will be returned to indicate the
error.

ERRORS    [Toc]    [Back]

     pthread_key_create() will fail if:

     [EAGAIN]      The system lacked the necessary  resources  to
create another
                   thread-specific  data  key,  or the system-imposed limit on
                   the  total  number   of   keys   per   process
[PTHREAD_KEYS_MAX]
                   would be exceeded.

     [ENOMEM]       Insufficient memory exists to create the key.

SEE ALSO    [Toc]    [Back]

     pthread_getspecific(3), pthread_key_delete(3),  pthread_setspecific(3)

STANDARDS    [Toc]    [Back]

     pthread_key_create()   conforms   to   ISO/IEC   9945-1:1996
(``POSIX'').

OpenBSD     3.6                           April      4,      1996