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 "Jan 11, 2015"
15 .Dt TSS 3C
16 .Os
17 .Sh NAME
18 .Nm tss ,
19 .Nm tss_create ,
20 .Nm tss_destroy ,
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 Destorying 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_destroy
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 propety, it is legal to call
92 .Fn tss_delete
93 from inside a destructor.
94 Any destructors that had been assocaited 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 callling 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
|
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
|