1.\" 2.\" This file and its contents are supplied under the terms of the 3.\" Common Development and Distribution License ("CDDL"), version 1.0. 4.\" You may only use this file in accordance with the terms of version 5.\" 1.0 of the CDDL. 6.\" 7.\" A full copy of the text of the CDDL should have accompanied this 8.\" source. A copy of the CDDL is also available via the Internet at 9.\" http://www.illumos.org/license/CDDL. 10.\" 11.\" 12.\" Copyright 2016 Joyent, Inc. 13.\" 14.Dd "Jan 11, 2015" 15.Dt TSS 3C 16.Os 17.Sh NAME 18.Nm tss , 19.Nm tss_create , 20.Nm tss_destroy , 21.Nm tss_get , 22.Nm tss_set 23.Nd thread-specific storage 24.Sh SYNOPSIS 25.In threads.h 26.Vt "typedef void (*tss_dtor_t)(void *);" 27.Ft int 28.Fo tss_create 29.Fa "tss_t *key" 30.Fa "tss_dtor_t dtor" 31.Fc 32.Ft void 33.Fo tss_delete 34.Fa "tss_t key" 35.Fc 36.Ft void * 37.Fo tss_get 38.Fa "tss_t key" 39.Fc 40.Ft int 41.Fo tss_set 42.Fa "tss_t key" 43.Fa "void *val" 44.Fc 45.Sh DESCRIPTION 46The 47.Sy tss 48family of functions create, get, set, and destroy thread-specific 49storage. 50.Ss Creating and Destorying Thread-Specific Storage 51The 52.Fn tss_create 53function creates a new thread-specific data key. The key space is opaque 54and global to all threads in the process. Each thread has its own 55value-space which can be mainpulated with the 56.Fn tss_get 57and 58.Fn tss_set 59functions. A given key persists until 60.Fn tss_destroy 61is called. 62.Pp 63When a key is created, the value 64.Dv NULL 65is associated with all current threads. When a thread is created, the 66value 67.Dv NULL 68is assigned as the value for the entire key-space. 69.Pp 70A key may optionally be created with a destructor function 71.Fa dtor . 72The function 73.Fa dtor 74will run when the thread exits (see 75.Xr thrd_exit 3C ) 76if the value for the key is not 77.Dv NULL . 78The key space's destructors may be run in any order. When the destructor 79is run due to a thread exiting, all signals will be blocked. 80.Pp 81The 82.Fn tss_delete 83function deletes the key identify by 84.Fa key 85from the global name-space. When a key is deleted, no registered 86destructor is called, it is up to the calling program to free any 87storage that was associated with 88.Fa key 89across all threads. Because of this propety, it is legal to call 90.Fn tss_delete 91from inside a destructor. Any destructors that had been assocaited with 92.Fa key 93will no longer be called when a thread terminates. 94.Ss Obtaining Values 95The 96.Fn tss_get 97function may be used to obtain the value associated with 98.Fa key 99for the calling thread. Note that if the calling thread has never set a 100value, then it will receive the default value, 101.Dv NULL . 102.Fn tss_get 103may be called from a tss destructor. 104.Ss Setting Values 105The 106.Fn tss_set 107function sets the value of the key 108.Fa key 109for the callling thread to 110.Fa value , 111which may be obtained by subsequent calls to 112.Fa tss_get . 113To remove a value for a specific thread, one may pass 114.Dv NULL 115in as 116.Fa value . 117Changing the value of a key with 118.Fn tss_set 119does not cause any destructors to be invoked. This means that 120.Fn tss_set 121may be used in the context of a destructor, but special care must be 122taken to avoid leaking storage or causing an infinite loop. 123.Sh RETURN VALUES 124Upon successful completion, the 125.Fn tss_create 126and 127.Fn tss_set 128functions return 129.Sy thrd_success . 130Otherwise, they return 131.Sy thrd_error 132to indicate that an error occurred. 133.Pp 134Upon successful completion, the 135.Fn tss_get 136function returns the thread-specific value associated with the given 137.Fa key . 138If no thread-specific value is associated with the key or an invalid key 139was passed in, then 140.Dv NULL 141is returned. 142.Sh INTERFACE STABILITY 143.Sy Standard 144.Sh MT-LEVEL 145.Sy MT-Safe 146.Sh SEE ALSO 147.Xr pthread_getspecific 3C , 148.Xr pthread_key_create 3C , 149.Xr pthread_key_delete 3C , 150.Xr pthread_setspecific 3C , 151.Xr attributes 5 152