Name

pthread_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 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.  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 initialization 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 facilities 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 undefined. 

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.