pthread_keycreate(3) — Subroutines
Digital
NAME
pthread_keycreate − Generates a unique per-thread context key value.
SYNOPSIS
#include <pthread.h>
int pthread_keycreate(
pthread_key_t ∗key ,
pthread_destructor_t destructor );
PARAMETERS
keyValue of the new per-thread context key.
destructorProcedure to be called to destroy a context value associated with the created key when the thread terminates or when the value is changed (for example, by calling pthread_setspecific.)
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 associate 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. Each call to this routine within a process returns a key value 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. (Refer to the description of pthread_once for more information.)
When multiple facilities share access to per-thread context, the facilities must agree on the key value that is associated with the context. The key value must be created only once and should 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.)
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, per-thread context is automatically destroyed. 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 undefined. Implementations can provide non-portable per-thread context attributes to control this ordering.
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 completion. | |
| −1 | [ENOMEM] | An attempt was made to allocate a key when the key name space is exhausted. This is not a temporary condition. |
| −1 | [EAGAIN] | Insufficient memory exists to create the key. |