pthread_keycreate(3-thr) — Reliant

pthread_keycreate(3-thr)                           pthread_keycreate(3-thr)

NAME
     pthreadkeycreate - generates a unique thread-specific data key value

SYNOPSIS
     #include <pthread.h>

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

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 pthreadkeycreate() 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 contain-
     ing 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 pthreadkeycreate() must occur in
     initialization code guaranteed to execute only once in each process.
     The pthreadonce() 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
     context. 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 con-
     text 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.




Page 1                       Reliant UNIX 5.44                Printed 11/98

pthread_keycreate(3-thr)                           pthread_keycreate(3-thr)

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

     EINVAL    The value specified by key is invalid.

     EAGAIN    An attempt was made to allocate a key when the key name
               space is exhausted. This is not a temporary condition.

     ENOMEM    Insufficient memory exists to create the key.

SEE ALSO
     pthreadgetspecific(3-thr), pthreadsetspecific(3-thr).









































Page 2                       Reliant UNIX 5.44                Printed 11/98

Museum