pthread_keycreate(3)
NAME
pthread_keycreate - Generates a unique thread-specific data key value
SYNOPSIS
#include <pthread.h> int pthread_keycreate( pthread_key_t *key, void (*destructor) (void *value));
PARAMETERS
keyValue of the new thread-specific data key.
destructorProcedure 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 initialization 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 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 context values for that key, within a special facility created for that purpose.) When a thread terminates, thread-specific data is automatically destroyed. 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(3), pthread_setspecific(3).
Hewlett-Packard Company — OSF DCE 1.1/HP DCE 1.5