1 TSS(3C) Standard C Library Functions TSS(3C)
2
3 NAME
4 tss, tss_create, tss_destroy, tss_get, tss_set - thread-specific storage
5
6 SYNOPSIS
7 #include <threads.h>
8
9 typedef void (*tss_dtor_t)(void *);
10
11 int
12 tss_create(tss_t *key, tss_dtor_t dtor);
13
14 void
15 tss_delete(tss_t key);
16
17 void *
18 tss_get(tss_t key);
19
20 int
21 tss_set(tss_t key, void *val);
22
23 DESCRIPTION
24 The tss family of functions create, get, set, and destroy thread-specific
25 storage.
26
27 Creating and Destorying Thread-Specific Storage
28 The tss_create() function creates a new thread-specific data key. The
29 key space is opaque and global to all threads in the process. Each
30 thread has its own value-space which can be manipulated with the
31 tss_get() and tss_set() functions. A given key persists until
32 tss_destroy() is called.
33
34 When a key is created, the value NULL is associated with all current
35 threads. When a thread is created, the value NULL is assigned as the
36 value for the entire key-space.
37
38 A key may optionally be created with a destructor function dtor. The
39 function dtor will run when the thread exits (see thrd_exit(3C)) if the
40 value for the key is not NULL. The key space's destructors may be run in
41 any order. When the destructor is run due to a thread exiting, all
42 signals will be blocked.
43
44 The tss_delete() function deletes the key identify by key from the global
45 name-space. When a key is deleted, no registered destructor is called,
46 it is up to the calling program to free any storage that was associated
47 with key across all threads. Because of this propety, it is legal to
48 call tss_delete() from inside a destructor. Any destructors that had
49 been assocaited with key will no longer be called when a thread
50 terminates.
51
52 Obtaining Values
53 The tss_get() function may be used to obtain the value associated with
54 key for the calling thread. Note that if the calling thread has never
55 set a value, then it will receive the default value, NULL. tss_get() may
56 be called from a tss destructor.
57
58 Setting Values
59 The tss_set() function sets the value of the key key for the callling
60 thread to value, which may be obtained by subsequent calls to tss_get.
61 To remove a value for a specific thread, one may pass NULL in as value.
62 Changing the value of a key with tss_set() does not cause any destructors
63 to be invoked. This means that tss_set() may be used in the context of a
64 destructor, but special care must be taken to avoid leaking storage or
65 causing an infinite loop.
66
67 RETURN VALUES
68 Upon successful completion, the tss_create() and tss_set() functions
69 return thrd_success. Otherwise, they return thrd_error to indicate that
70 an error occurred.
71
72 Upon successful completion, the tss_get() function returns the thread-
73 specific value associated with the given key. If no thread-specific
74 value is associated with the key or an invalid key was passed in, then
75 NULL is returned.
76
77 INTERFACE STABILITY
78 Standard
79
80 MT-LEVEL
81 MT-Safe
82
83 SEE ALSO
84 pthread_getspecific(3C), pthread_key_create(3C), pthread_key_delete(3C),
85 pthread_setspecific(3C), attributes(5)
86
87 illumos January 11, 2015 illumos
|
1 TSS(3C) Standard C Library Functions TSS(3C)
2
3 NAME
4 tss, tss_create, tss_delete, tss_get, tss_set - thread-specific storage
5
6 SYNOPSIS
7 #include <threads.h>
8
9 typedef void (*tss_dtor_t)(void *);
10
11 int
12 tss_create(tss_t *key, tss_dtor_t dtor);
13
14 void
15 tss_delete(tss_t key);
16
17 void *
18 tss_get(tss_t key);
19
20 int
21 tss_set(tss_t key, void *val);
22
23 DESCRIPTION
24 The tss family of functions create, get, set, and destroy thread-specific
25 storage.
26
27 Creating and Destroying Thread-Specific Storage
28 The tss_create() function creates a new thread-specific data key. The
29 key space is opaque and global to all threads in the process. Each
30 thread has its own value-space which can be manipulated with the
31 tss_get() and tss_set() functions. A given key persists until
32 tss_delete() is called.
33
34 When a key is created, the value NULL is associated with all current
35 threads. When a thread is created, the value NULL is assigned as the
36 value for the entire key-space.
37
38 A key may optionally be created with a destructor function dtor. The
39 function dtor will run when the thread exits (see thrd_exit(3C)) if the
40 value for the key is not NULL. The key space's destructors may be run in
41 any order. When the destructor is run due to a thread exiting, all
42 signals will be blocked.
43
44 The tss_delete() function deletes the key identify by key from the global
45 name-space. When a key is deleted, no registered destructor is called,
46 it is up to the calling program to free any storage that was associated
47 with key across all threads. Because of this property, it is legal to
48 call tss_delete() from inside a destructor. Any destructors that had
49 been associated with key will no longer be called when a thread
50 terminates.
51
52 Obtaining Values
53 The tss_get() function may be used to obtain the value associated with
54 key for the calling thread. Note that if the calling thread has never
55 set a value, then it will receive the default value, NULL. tss_get() may
56 be called from a tss destructor.
57
58 Setting Values
59 The tss_set() function sets the value of the key key for the calling
60 thread to value, which may be obtained by subsequent calls to tss_get.
61 To remove a value for a specific thread, one may pass NULL in as value.
62 Changing the value of a key with tss_set() does not cause any destructors
63 to be invoked. This means that tss_set() may be used in the context of a
64 destructor, but special care must be taken to avoid leaking storage or
65 causing an infinite loop.
66
67 RETURN VALUES
68 Upon successful completion, the tss_create() and tss_set() functions
69 return thrd_success. Otherwise, they return thrd_error to indicate that
70 an error occurred.
71
72 Upon successful completion, the tss_get() function returns the thread-
73 specific value associated with the given key. If no thread-specific
74 value is associated with the key or an invalid key was passed in, then
75 NULL is returned.
76
77 INTERFACE STABILITY
78 Standard
79
80 MT-LEVEL
81 MT-Safe
82
83 SEE ALSO
84 pthread_getspecific(3C), pthread_key_create(3C), pthread_key_delete(3C),
85 pthread_setspecific(3C), attributes(5)
86
87 illumos August 20, 2019 illumos
|