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