pthread_keycreate(3thr)pthread_keycreate(3thr)Namepthread_keycreate - Generates a unique per-thread context key value.
Syntax
#include <pthread.h>
int pthread_keycreate (key, destructor)
pthread_key_t *key;
pthread_destructor_t destructor;
Arguments
key Value of the new per-thread context key.
destructor
Procedure called to destroy a context value associated with the
created key when the thread terminates.
Description
This routine generates a unique per-thread context key value. This key
value identifies a per-thread context, which is an address of memory
generated by the client containing arbitrary data of any size.
Per-thread context is a mechanism that allows client software to asso‐
ciate context information with the current thread. (This mechanism can
be thought of as a means for a client to add unique fields to the
thread control block.)
For example, per-thread context can be used by a language run-time
library that needs to associate a language-specific thread-private data
structure with an individual thread. The per-thread context 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. The key provides a
cell within each thread. Each call to this routine creates a new cell,
and each call within a process returns a key value that is unique
within an application invocation. Keys must be generated from initial‐
ization code that is guaranteed to be called only once within each
process. (See the pthread_once Description for more information.)
When multiple facilities share access to per-thread context, the facil‐
ities must agree on the key value that is associated with the context.
The key value must be created once and should be stored in a location
known to each facility. (Encapsulate key creation and context value
setting within a special facility for that purpose.)
An implementation can choose to predefine some number of keys for
favored clients, such as certain compilers, run-time libraries, or the
debugger.
When a thread terminates, its per-thread context is automatically
destroyed; however, the key value remains. For each per-thread context
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 unde‐
fined.
Return Values
If an error condition occurs, this routine returns -1 and sets errno to
the corresponding error value. Possible return values are as follows.
Return Error Description
0 Successful comple‐
tion.
-1 [ENOMEM] An attempt is made
to allocate a key
when the key name
space is exhausted.
This is not a tem‐
porary condition.
-1 [EAGAIN] Insufficient memory
exists to create
the key.
-1 [EINVAL] Invalid argument.
pthread_keycreate(3thr)
