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