Debian Codegraph @

upstream/debian-unstable/man3/pthread_key_create.3

raw
1 .\" Copyright, the authors of the Linux man-pages project
2 .\"
3 .\" SPDX-License-Identifier: Linux-man-pages-copyleft
4 .\"
5 .TH pthread_key_create 3 2025-05-17 "Linux man-pages 6.18"
6 .
7 .
8 .SH NAME
9 pthread_key_create,
10 pthread_key_delete,
11 pthread_setspecific,
12 pthread_getspecific
13 \-
14 management of thread-specific data
15 .
16 .
17 .SH SYNOPSIS
18 .nf
19 .B #include <pthread.h>
20 .P
21 .BI "int pthread_key_create(pthread_key_t *" key ,
22 .BI " typeof(void (void *)) *" destr_function ;
23 .BI "int pthread_key_delete(pthread_key_t " key );
24 .BI "int pthread_setspecific(pthread_key_t " key ", const void *" pointer );
25 .BI "void * pthread_getspecific(pthread_key_t " key );
26 .fi
27 .
28 .
29 .SH DESCRIPTION
30 Programs often need global or static variables
31 that have different values in different threads.
32 Since threads share one memory space,
33 this cannot be achieved with regular variables.
34 Thread-specific data is the POSIX threads answer to this need.
35 .P
36 Each thread possesses a private memory block,
37 the thread-specific data area,
38 or TSD area for short.
39 This area is indexed by TSD keys.
40 The TSD area associates values of type
41 .I void\ *
42 to TSD keys.
43 TSD keys are common to all threads,
44 but the value associated with a given TSD key
45 can be different in each thread.
46 .P
47 For concreteness,
48 the TSD areas can be viewed as arrays of
49 .I void\ *
50 pointers,
51 TSD keys as integer indices into these arrays,
52 and the value of a TSD key
53 as the value of the corresponding array element in the calling thread.
54 .P
55 When a thread is created,
56 its TSD area initially associates NULL with all keys.
57 .P
58 .BR pthread_key_create ()
59 allocates a new TSD key.
60 The key is stored in the location pointed to by
61 .IR key .
62 There is a limit of
63 .B PTHREAD_KEYS_MAX
64 on the number of keys allocated at a given time.
65 The value initially associated with the returned key
66 is NULL in all currently executing threads.
67 .P
68 The
69 .I destr_function
70 argument,
71 if not NULL,
72 specifies a destructor function associated with the key.
73 When a thread terminates via
74 .BR pthread_exit ()
75 or by cancelation,
76 .I destr_function
77 is called with arguments
78 the value associated with the key in that thread.
79 The
80 .I destr_function
81 is not called if that value is NULL.
82 The order in which destructor functions are called at thread termination time
83 is unspecified.
84 .P
85 Before the destructor function is called,
86 the NULL value is associated with the key in the current thread.
87 A destructor function might,
88 however,
89 re-associate non-NULL values to that key or some other key.
90 To deal with this,
91 if after all the destructors have been called
92 for all non-NULL values,
93 there are still some non-NULL values with associated destructors,
94 then the process is repeated.
95 The glibc implementation stops the process
96 after
97 .B PTHREAD_DESTRUCTOR_ITERATIONS
98 iterations,
99 even if some non-NULL values with associated descriptors remain.
100 Other implementations may loop indefinitely.
101 .P
102 .BR pthread_key_delete ()
103 deallocates a TSD key.
104 It does not check
105 whether non-NULL values are associated with that key
106 in the currently executing threads,
107 nor call the destructor function associated with the key.
108 .P
109 .BR pthread_setspecific ()
110 changes the value
111 associated with
112 .I key
113 in the calling thread,
114 storing the given
115 .I pointer
116 instead.
117 .P
118 .BR pthread_getspecific ()
119 returns the value
120 currently associated with
121 .I key
122 in the calling thread.
123 .
124 .
125 .SH "RETURN VALUE"
126 .BR pthread_key_create (),
127 .BR pthread_key_delete (),
128 and
129 .BR pthread_setspecific ()
130 return 0 on success and a non-zero error code on failure.
131 If successful,
132 .BR pthread_key_create ()
133 stores the newly allocated key
134 in the location pointed to by its
135 .I key
136 argument.
137 .P
138 .BR pthread_getspecific ()
139 returns
140 the value associated with
141 .I key
142 on success,
143 and NULL on error.
144 .
145 .
146 .SH ERRORS
147 .BR pthread_key_create ()
148 returns the following error code on error:
149 .RS
150 .TP
151 .B EAGAIN
152 .B PTHREAD_KEYS_MAX
153 keys are already allocated.
154 .RE
155 .P
156 .BR pthread_key_delete ()
157 and
158 .BR pthread_setspecific ()
159 return
160 the following error code on error:
161 .RS
162 .TP
163 .B EINVAL
164 .I key
165 is not a valid, allocated TSD key.
166 .RE
167 .P
168 .BR pthread_getspecific ()
169 returns NULL if
170 .I key
171 is not a valid,
172 allocated TSD key.
173 .
174 .
175 .SH "SEE ALSO"
176 pthread_create(3), pthread_exit(3), pthread_testcancel(3).
177 .
178 .
179 .SH EXAMPLE
180 The following code fragment
181 allocates a thread-specific array of 100 characters,
182 with automatic reclamation at thread exit:
183 .P
184 .RS
185 .ft 3
186 .nf
187 .sp
188 /* Key for the thread-specific buffer */
189 static pthread_key_t buffer_key;
190 \&
191 /* Once-only initialisation of the key */
192 static pthread_once_t buffer_key_once = PTHREAD_ONCE_INIT;
193 \&
194 /* Allocate the thread-specific buffer */
195 void buffer_alloc(void)
196 {
197 pthread_once(&buffer_key_once, buffer_key_alloc);
198 pthread_setspecific(buffer_key, malloc(100));
199 }
200 \&
201 /* Return the thread-specific buffer */
202 char * get_buffer(void)
203 {
204 return (char *) pthread_getspecific(buffer_key);
205 }
206 \&
207 /* Allocate the key */
208 static void buffer_key_alloc()
209 {
210 pthread_key_create(&buffer_key, buffer_destroy);
211 }
212 \&
213 /* Free the thread-specific buffer */
214 static void buffer_destroy(void * buf)
215 {
216 free(buf);
217 }
218 .ft
219 .RE
220 .fi