PTHREAD_KEY(3) BSD Programmer's Manual PTHREAD_KEY(3)NAME
pthread_key_create, pthread_key_delete - thread specific data key func-
tions
SYNOPSIS
#include <pthread.h>
int
pthread_key_create(pthread_key_t *key, void (*func)(void *));
int
pthread_key_delete(pthread_key_t key);
DESCRIPTION
This interface is defined by IEEE Std1003.1c (``POSIX'').
The pthread_key_create() and pthread_key_delete() functions maintain data
keys used to locate thread-specific data. While the same data key may be
used by multiple threads, the values bound to the data key are maintained
per-thread. When a key is initially created a NULL value is associated
with the new key in all threads until a data value is associated with it
using pthread_setspecific().
The pthread_key_create() function creates a new data key and optionally
associates the destructor func with it. The newly created data key may
be used to locate thread-specific data items in the calling thread using
pthread_setspecific(). If a destructor function was registered upon key
creation with func, it is called upon thread exit for all non-NULL data
values with the thread-specific data value as its single argument. This
process is repeated for non-NULL data values up to
PTHREAD_DESTRUCTOR_ITERATIONS or until there are no more non-NULL data
values remaining.
The pthread_key_delete() function deletes a previously created data key.
It is the responsibility of the application to free any allocated storage
and/or clean up data structures related to the deleted key. No destruc-
tor functions are called from pthread_key_delete(). It is safe to call
pthread_key_delete() from a destructor function and any destructor func-
tions associated with the deleted data key will no longer be called from
pthread_exit().
RETURN VALUES
On success the pthread_key_create and pthread_key_delete functions return
0. A non-zero result indicates that an error occurred.
ERRORS
The pthread_key_create and pthread_key_delete functions may fail and re-
turn one of the following errors:
[EAGAIN] The system lacked the necessary resources (other than memo-
ry) to create another pthread data key.
[EINVAL] The value of a function argument is invalid.
[ENOMEM] Insufficient memory exists to fulfill the requested opera-
tion.
SEE ALSOpthreads(3), pthread_exit(3), pthread_setspecific(3), pthread_getspe-
cific(3)STANDARDS
The pthread_key_create and pthread_key_delete functions conform to IEEE
Std1003.1c (``POSIX'').
HISTORY
The pthread_key_create and pthread_key_delete functions first appeared in
BSD/OS 3.0.
4th Berkeley Distribution June 3, 1996 2