xref: /titanic_50/usr/src/man/man3c/tss.3c (revision dcdfe824b3dff2df12578b936adf1daf000aa129)
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