NAME

tss_create — thread-specific data key creation

SYNOPSIS

#include <threads.h>

int tss_create(tss_t *key, tss_dtor_t dtor);


DESCRIPTION

^[CX] The functionality described on this reference page is aligned with the ISO C standard. Any conflict between the requirements described here and the ISO C standard is unintentional. This volume of POSIX.1-2024 defers to the ISO C standard.

The tss_create() function shall create a thread-specific storage pointer with destructor dtor, which can be null.

A null pointer value shall be associated with the newly created key in all existing threads. Upon subsequent thread creation, the value associated with all keys shall be initialized to a null pointer value in the new thread.

Destructors associated with thread-specific storage shall not be invoked at process termination.

The behavior is undefined if the tss_create() function is called from within a destructor.

^[CX] The tss_create() function shall not be affected if the calling thread executes a signal handler during the call.

RETURN VALUE

If the tss_create() function is successful, it shall set the thread-specific storage pointed to by key to a value that uniquely identifies the newly created pointer and shall return thrd_success; otherwise, thrd_error shall be returned and the thread-specific storage pointed to by key has an indeterminate value.

ERRORS

No errors are defined.

EXAMPLES

None.

APPLICATION USAGE

The tss_create() function performs no implicit synchronization. It is the responsibility of the application writer to ensure that it is called exactly once per key before use of the key.

RATIONALE

If the value associated with a key needs to be updated during the lifetime of the thread, it may be necessary to release the storage associated with the old value before the new value is bound. Although the tss_set() function could do this automatically, this feature is not needed often enough to justify the added complexity. Instead, the application is responsible for freeing the stale storage:

old = tss_get(key);
new = allocate();
destructor(old);
tss_set(key, new);

There is no notion of a destructor-safe function. If an application does not call thrd_exit() or pthread_exit() from a signal handler, or if, while calling async-unsafe functions, it blocks any signal whose handler might call thrd_exit() or pthread_exit(), all functions can be safely called from destructors.

The tss_create() function is not affected by signal handlers for the reasons stated in XRAT B.2.3 Error Numbers.

FUTURE DIRECTIONS

None.

SEE ALSO

pthread_exit, pthread_key_create, thrd_exit , tss_delete, tss_get

XBD <threads.h>

CHANGE HISTORY

First released in Issue 8. Included for alignment with the ISO/IEC 9899:2018 standard.