The Open Group Base Specifications Issue 8
IEEE Std 1003.1-2024
Copyright © 2001-2024 The IEEE and The Open Group

NAME

tss_create — thread-specific data key creation

SYNOPSIS

#include <threads.h>

int tss_create(tss_t *
key, tss_dtor_t dtor);

DESCRIPTION

[CX] [Option Start] 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. [Option End]

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] [Option Start] The tss_create() function shall not be affected if the calling thread executes a signal handler during the call. [Option End]

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.


The following sections are informative.

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.

End of informative text.

 

return to top of page

UNIX® is a registered Trademark of The Open Group.
POSIX™ is a Trademark of The IEEE.
Copyright © 2001-2024 The IEEE and The Open Group, All Rights Reserved
[ Main Index | XBD | XSH | XCU | XRAT ]