NAME
pthread_key_create —
thread-specific
data
LIBRARY
POSIX Threads Library (libpthread, -lpthread)
SYNOPSIS
#include <pthread.h>
int
pthread_key_create(
pthread_key_t
*key,
void
(*destructor)(void *));
int
pthread_key_delete(
pthread_key_t
key);
DESCRIPTION
The
pthread_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_MAX
would 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
pthread_getspecific(3)
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.