NAME

tss — thread-specific storage functions

LIBRARY

POSIX Threads Library (libpthread, -lpthread)

SYNOPSIS

#include <threads.h>

typedef void (*tss_dtor_t) (void *)

int
tss_create(tss_t *key, tss_dtor_t dtor);

void
tss_delete(tss_t key);

void *
tss_get(tss_t key);

int
tss_set(tss_t key, void *val);

#define TSS_DTOR_ITERATIONS /* implementation specified */

DESCRIPTION

There are two groups of storage in C programs:

• local storage,
• global storage.

Multithreaded programs in C add the third group thread-specific storage. This data is private to thread and every entry of this type has an associated tss_t opaque key that is global to all threads in the process. A thread using the tss_t * pointer accesses private data.

The tss_create() function creates a thread-specific storage with the key handler with optional destructor dtor. If the dtor parameter is not NULL, then specified appropriate destructor will be called on thread termination. The destructor is not called if a thread called the tss_delete() function for the specified key. 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 TSS_DTOR_ITERATIONS iterations of destructor calls for outstanding non-NULL values, there are still some non-NULL values with associated destructors, the NetBSD implementation stops calling further destructors. The thrd_exit(3) function must not be called from a destructor.

The tss_delete() function frees resources used by the thread-specific storage identified by the key object. This function can be called inside the dtor destructor, however the destructor is not called by tss_delete().

The tss_get() and tss_set() functions are used to get and set thread-specific storage.

RETURN VALUES

The tss_create() function returns thrd_success on success, otherwise thrd_error on failure.

The tss_delete() function returns no value.

The tss_get() returns pointer to thread-specific storage on success or NULL on failure.

The tss_set() function returns thrd_success on success, otherwise thrd_error on failure.

SEE ALSO

pthread_getspecific(3), pthread_key_create(3), threads(3)

STANDARDS

The tss interface conforms to ISO/IEC 9899:2011 (“ISO C11”).

HISTORY

This interface first appeared in NetBSD 9.

AUTHORS

Kamil Rytarowski <kamil@NetBSD.org>