pthread_key_create(3T)pthread_key_create(3T)NAMEpthread_key_create(), pthread_key_delete() - create or delete a thread-
specific data key
SYNOPSISPARAMETERS
key This is either a pointer to the location where the new
key value will to be returned (create function) or the
thread-specific data key to be deleted (delete func‐
tion).
destructor
Function to be called to destroy a data value associ‐
ated with key when the thread terminates.
DESCRIPTION
creates a unique thread-specific data key. The key may be used by
threads within the process to maintain thread-specific data. The same
key is used by all threads, but each thread has its own thread-specific
value associated with key. For each thread, the value associated with
key persists for the life of the thread.
By default, the system allows a process to create up to number of
thread-specific data keys. If the process needs more keys, the envi‐
ronment variable can set the number of keys up to a maximum of 16384.
If a value outside the range of and 16384 is specified, or if the envi‐
ronment variable is not set at all, the default value is considered.
When a new thread-specific data key is created, each thread will ini‐
tially have the value NULL associated with the new key. Each time a
thread is created, the new thread will have the value NULL for each
thread-specific data key that has been created in the process. A
thread may use to change the value associated with a thread-specific
data key. Note: is an opaque data type.
When a thread terminates, it may have non-NULL values associated with
some or all of its thread-specific data keys. Typically, these values
will be pointers to dynamically allocated memory. If this memory is
not released when the thread terminates, memory leaks in the process
occur. An optional function may be provided at key creation time to
destroy the thread-specific data of a terminating thread. When a
thread terminates, the thread-specific data values associated with the
thread will be examined. For each key that has a non-NULL thread-spe‐
cific data value and a destructor function, the destructor function
will be called with the thread-specific data value as its sole argu‐
ment. The order in which destructor functions are called is unspeci‐
fied.
Once all the destructor functions have been called, the thread-specific
data values for the terminating thread are examined again. If there
are still non-NULL values in which the associated keys have destructor
functions, the process of calling destructor functions is repeated. If
after iterations of this loop there are still some non-NULL values with
associated destructors, the system may stop calling the destructors or
continue calling the destructors until there are no non-NULL values.
Note: This may result in an infinite loop.
If a destructor function is not desired for key, the value NULL may be
passed in the destructor parameter.
The function deletes a thread-specific data key. The key must have
been previously created by The thread-specific data values associated
with key are not required to be NULL when this function is called.
Using key after it has been deleted results in undefined behavior.
If a destructor function is associated with key, it will not be invoked
by the function. Once key has been deleted, any function that was
associated with key is not called when a thread exits. It is the
responsibility of the application to free any application storage for
each of the threads using key.
The function can be called from a destructor function.
RETURN VALUE
If successful, and return zero. Otherwise, an error number is returned
to indicate the error (the variable is not set).
ERRORS
If any of the following occur, the function returns the corresponding
error number:
The value specified by
key is invalid.
The necessary resources to create another thread-specific
data key are not available, or the total number
of keys per process has exceeded or an invalid
value was specified with the environment variable
There is insufficient memory available in which to create
key.
For each of the following conditions, if the condition is detected, the
function returns the corresponding error number:
The value specified by
key is invalid.
AUTHOR
and were derived from the IEEE POSIX P1003.1c standard.
SEE ALSOpthread_getspecific(3T), pthread_setspecific(3T).
STANDARDS CONFORMANCE
Pthread Library pthread_key_create(3T)
