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 "November 8, 2020" 15.Dt TSS 3C 16.Os 17.Sh NAME 18.Nm tss , 19.Nm tss_create , 20.Nm tss_delete , 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 Destroying Thread-Specific Storage 51The 52.Fn tss_create 53function creates a new thread-specific data key. 54The key space is opaque and global to all threads in the process. 55Each thread has its own value-space which can be manipulated with the 56.Fn tss_get 57and 58.Fn tss_set 59functions. 60A given key persists until 61.Fn tss_delete 62is called. 63.Pp 64When a key is created, the value 65.Dv NULL 66is associated with all current threads. 67When a thread is created, the value 68.Dv NULL 69is assigned as the value for the entire key-space. 70.Pp 71A key may optionally be created with a destructor function 72.Fa dtor . 73The function 74.Fa dtor 75will run when the thread exits (see 76.Xr thrd_exit 3C ) 77if the value for the key is not 78.Dv NULL . 79The key space's destructors may be run in any order. 80When the destructor is run due to a thread exiting, all signals will be blocked. 81.Pp 82The 83.Fn tss_delete 84function deletes the key identified by 85.Fa key 86from the global name-space. 87When a key is deleted, no registered destructor is called, it is up to the 88calling program to free any storage that was associated with 89.Fa key 90across all threads. 91Because of this property, it is legal to call 92.Fn tss_delete 93from inside a destructor. 94Any destructors that had been associated with 95.Fa key 96will no longer be called when a thread terminates. 97.Ss Obtaining Values 98The 99.Fn tss_get 100function may be used to obtain the value associated with 101.Fa key 102for the calling thread. 103Note that if the calling thread has never set a value, then it will receive the 104default value, 105.Dv NULL . 106.Fn tss_get 107may be called from a tss destructor. 108.Ss Setting Values 109The 110.Fn tss_set 111function sets the value of the key 112.Fa key 113for the calling thread to 114.Fa value , 115which may be obtained by subsequent calls to 116.Fa tss_get . 117To remove a value for a specific thread, one may pass 118.Dv NULL 119in as 120.Fa value . 121Changing the value of a key with 122.Fn tss_set 123does not cause any destructors to be invoked. 124This means that 125.Fn tss_set 126may be used in the context of a destructor, but special care must be 127taken to avoid leaking storage or causing an infinite loop. 128.Sh RETURN VALUES 129Upon successful completion, the 130.Fn tss_create 131and 132.Fn tss_set 133functions return 134.Sy thrd_success . 135Otherwise, they return 136.Sy thrd_error 137to indicate that an error occurred. 138.Pp 139Upon successful completion, the 140.Fn tss_get 141function returns the thread-specific value associated with the given 142.Fa key . 143If no thread-specific value is associated with the key or an invalid key 144was passed in, then 145.Dv NULL 146is returned. 147.Sh INTERFACE STABILITY 148.Sy Standard 149.Sh MT-LEVEL 150.Sy MT-Safe 151.Sh SEE ALSO 152.Xr pthread_getspecific 3C , 153.Xr pthread_key_create 3C , 154.Xr pthread_key_delete 3C , 155.Xr pthread_setspecific 3C , 156.Xr attributes 7 157