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