TSS(3)

TSS(3) | Library Functions Manual | TSS(3)

# 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>

October 16, 2016 | NetBSD 9.0