NAME    [Toc]    [Back]

       pthread_key_create  -  Generates  a unique thread-specific
       data key

SYNOPSIS    [Toc]    [Back]

       #include <pthread.h>

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

LIBRARY    [Toc]    [Back]

       DECthreads POSIX 1003.1c Library (libpthread.so)

STANDARDS    [Toc]    [Back]

       Interfaces documented on this reference  page  conform  to
       industry standards as follows:

       IEEE  Std  1003.1c-1995,  POSIX System Application Program
       Interface

PARAMETERS    [Toc]    [Back]

       Location where the new thread-specific data  key  will  be
       stored.   Procedure  called  to  destroy a thread-specific
       data value associated with the created key when  a  thread
       terminates.  Note  that the argument to the destructor for
       the user-specified routine is the non-NULL  value  associated
 with a key.

DESCRIPTION    [Toc]    [Back]

       This  routine generates a unique, thread-specific data key
       that is visible to all threads in the process.  The  variable
 key provided by this routine is an opaque object used
       to locate thread-specific data.   Although  the  same  key
       value  can  be used by different threads, the values bound
       to the key by pthread_setspecific(3) are maintained  on  a
       per-thread  basis  and persist for the life of the calling
       thread.

       DECthreads imposes a  maximum  number  of  thread-specific
       data    keys,    equal    to    the    symbolic   constant
       PTHREAD_KEYS_MAX.

       Thread-specific data allows client software  to  associate
       "static" information with the current thread. For example,
       where a routine declares a variable static  in  a  singlethreaded
  program,  a multithreaded version of the program
       might create a thread-specific data key to store the  same
       variable.

       This  routine  generates  and returns a new key value. The
       key reserves a cell within each thread. Each call to  this
       routine creates a new cell that is unique within an application
 invocation. Keys must be generated from initialization
 code that is guaranteed to be called only once within
       each process. (See  the  pthread_once(3)  description  for
       more information.)

       When  a  thread  terminates,  its  thread-specific data is
       automatically destroyed; however, the key  remains  unless
       destroyed  by a call to pthread_key_delete(3). An optional
       destructor function can be associated with  each  key.  At
       thread  exit,  if a key has a non-NULL destructor pointer,
       and the thread has a non-NULL value associated  with  that
       key,  the  destructor  function is called with the current
       associated value as its sole argument. Note that the order
       in  which  thread-specific  data destructors are called at
       thread termination is undefined.

       Before each destructor is called, the thread's  value  for
       the  corresponding  key is set to NULL. After the destructors
 have been called for all non-NULL values with associated
  destructors, if there are still some non-NULL values
       with associated destructors, then this sequence of actions
       is  repeated.  If  there are still non-NULL values for any
       key with a  destructor  after  four  repetitions  of  this
       sequence, DECthreads terminates the thread. At this point,
       any key values that represent allocated heap will be lost.
       Note that this occurs only when a destructor performs some
       action that creates a new value for some key.   Your  program's
  destructor  code should attempt to avoid this sort
       of circularity.

RETURN VALUES    [Toc]    [Back]

       If an error condition  occurs,  this  routine  returns  an
       integer  value  indicating  the  type  of  error. Possible
       return values are as follows: Successful completion.   The
       system  lacked  the  necessary resources to create another
       thread-specific data key, or the limit on the total number
       of  keys per process (PTHREAD_KEYS_MAX) has been exceeded.
       Insufficient memory exists to create the key.

ERRORS    [Toc]    [Back]

       None

SEE ALSO    [Toc]    [Back]

       Functions: pthread_getspecific(3),  pthread_key_delete(3),
       pthread_once(3), pthread_setspecific(3)

       Manuals: Guide to DECthreads and Programmer's Guide



                                            pthread_key_create(3)