VMS Help DCE_THREADS, Application Routines, pthread_keycreate  *Conan The Librarian (sorry for the slow response - running on an old VAX)

  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