NAME
pthread_key_create,
pthread_key_delete —
thread-specific data
LIBRARY
library “libpthread”
SYNOPSIS
#include
<pthread.h>
int
pthread_key_create(pthread_key_t
*key, void
(*destructor)(void *));
int
pthread_key_delete(pthread_key_t
key);
DESCRIPTION
Thepthread_key_create()
function creates a thread-specific data key visible to all threads in the
process. Key values are opaque objects used to locate thread-specific data.
The same key value may be used by different threads, but the values bound to
the key by
pthread_setspecific()
are maintained on a per-thread basis and persist for the life of the calling
thread.
Upon key creation, the value NULL is
associated with the new key in all active threads. Upon thread creation, the
value NULL is associated with all defined keys in
the new thread.
An optional destructor function may be associated with each key
value. At thread exit, if a key value has a non-NULL
destructor pointer, and the thread has a non-NULL
value associated with the key, the function pointed to is called with the
current associated value as its sole argument. The order of destructor calls
is unspecified if more than one destructor exists for a thread when it
exits.
If, after all the destructors have been called for all
non-NULL values with associated destructors, there
are still some non-NULL values with associated
destructors, then the process is repeated. If, after at least
PTHREAD_DESTRUCTOR_ITERATIONS iterations of
destructor calls for outstanding non-NULL values,
there are still some non-NULL values with associated
destructors, the implementation stops calling destructors.
The
pthread_key_delete()
function deletes a thread-specific data key previously returned by
pthread_key_create(). The thread-specific data
values associated with key need not be
NULL at the time of the call. It is the
responsibility of the application to free any application storage or perform
any cleanup actions for data structures related to the deleted key or
associated thread-specific data in any threads; this cleanup can be done
either before or after pthread_key_delete() is
called. Any attempt to use key following the call to
pthread_key_delete() results in undefined
behavior.
The
pthread_key_delete()
function itself is callable from within destructor functions, but destructor
functions are not invoked by the function. Any destructor function that may
have been associated with key will no longer be called
upon thread exit.
RETURN VALUES
If successful, the pthread_key_create()
function will store the newly created key value at the location specified by
key and returns zero. Also
pthread_key_delete() will return zero upon success.
Upon failure both functions return an error number to indicate the
cause.
ENVIRONMENT
PTHREAD_KEYS_MAX- Maximum per-process thread-specific data keys. This cannot be set below
_POSIX_THREAD_KEYS_MAX.
ERRORS
The pthread_key_create() may fail if:
- [
EAGAIN] - The system lacked the necessary resources to create another
thread-specific data key, or the system-imposed limit on the total number
of keys per-process
PTHREAD_KEYS_MAXwould be exceeded. - [
ENOMEM] - Insufficient memory exists to create the key.
The pthread_key_delete() function may fail
if:
- [
EINVAL] - The key value is invalid.
SEE ALSO
STANDARDS
These functions conform to IEEE Std 1003.1-2001 (“POSIX.1”).
BUGS
The current specifications are flawed and do not permit a clean implementation without potential problems. The current implementation in NetBSD addresses these problems by not supporting key reuse.