1 .\" Copyright (C) 1996-1999 Free Software Foundation, Inc.
3 .\" Permission is granted to make and distribute verbatim copies of
4 .\" this manual provided the copyright notice and this permission notice are
5 .\" preserved on all copies.
7 .\" Permission is granted to copy and distribute modified versions of
8 .\" this manual under the conditions for verbatim copying, provided that
9 .\" the entire resulting derived work is distributed under the terms of a
10 .\" permission notice identical to this one.
12 .\" Permission is granted to copy and distribute translations of this
13 .\" manual into another language, under the above conditions for modified
14 .\" versions, except that this permission notice may be stated in a
15 .\" translation approved by the Foundation.
17 .\" Copyright (C) 1996 Xavier Leroy.
19 .\" Japanese Version Copyright (C) 2002-2003 Suzuki Takashi
20 .\" all rights reserved.
21 .\" Translated Tue Dec 31 23:11:09 JST 2002
22 .\" by Suzuki Takashi.
24 .\"WORD: thread-specific data ¥¹¥ì¥Ã¥É¸Çͥǡ¼¥¿
25 .\"WORD: thread-specific key ¥¹¥ì¥Ã¥É¸ÇÍ¥¡¼
26 .\"WORD: destructor function ¥Ç¥¹¥È¥é¥¯¥¿´Ø¿ô
29 .TH PTHREAD_SPECIFIC 3 LinuxThreads
33 .\"O pthread_key_create, pthread_key_delete, pthread_setspecific, pthread_getspecific \- management of thread-specific data
34 pthread_key_create, pthread_key_delete, pthread_setspecific, pthread_getspecific \- ¥¹¥ì¥Ã¥É¸Çͥǡ¼¥¿¤Î´ÉÍý
38 .B #include <pthread.h>
40 .BI "int pthread_key_create(pthread_key_t *" key ", void (*" destr_function ") (void *));"
42 .BI "int pthread_key_delete(pthread_key_t " key ");"
44 .BI "int pthread_setspecific(pthread_key_t " key ", const void *" pointer ");"
46 .BI "void * pthread_getspecific(pthread_key_t " key ");"
51 .\"O Programs often need global or static variables that have different
52 .\"O values in different threads. Since threads share one memory space,
53 .\"O this cannot be achieved with regular variables. Thread-specific data
54 .\"O is the POSIX threads answer to this need.
55 ¥×¥í¥°¥é¥à¤Ç¤Ï¥¹¥ì¥Ã¥É¤´¤È¤ËÃͤΰۤʤë
56 ¥°¥í¡¼¥Ð¥ëÊÑ¿ô¤äÀÅŪÊÑ¿ô¤¬¤·¤Ð¤·¤ÐɬÍפȤʤ롣
57 Ê£¿ô¤Î¥¹¥ì¥Ã¥É¤Ï 1 ¤Ä¤Î¥á¥â¥ê¶õ´Ö¤ò¶¦Í¤¹¤ë¤¿¤á¡¢
58 Ä̾ï¤ÎÊÑ¿ô¤Ç¤Ï¤³¤ì¤ò¼Â¸½¤¹¤ë¤³¤È¤¬¤Ç¤¤Ê¤¤¡£
59 ¥¹¥ì¥Ã¥É¸Çͥǡ¼¥¿¤Ï¡¢
60 ¤³¤ÎɬÍ×À¤Ø¤Î POSIX ¥¹¥ì¥Ã¥É¤ÎÅú¤¨¤Ç¤¢¤ë¡£
62 .\"O Each thread possesses a private memory block, the thread-specific data
63 .\"O area, or TSD area for short. This area is indexed by TSD keys. The TSD
64 .\"O area associates values of type
66 .\"O to TSD keys. TSD keys are
67 .\"O common to all threads, but the value associated with a given TSD key
68 .\"O can be different in each thread.
69 ¤½¤ì¤¾¤ì¤Î¥¹¥ì¥Ã¥É¤Ï¥¹¥ì¥Ã¥É¸Çͥǡ¼¥¿ (thread-specific data) Îΰ衢
71 ¥×¥é¥¤¥Ù¡¼¥È¤Ê¥á¥â¥ê¥Ö¥í¥Ã¥¯¤òÊÝͤ·¤Æ¤¤¤ë¡£
72 ¤³¤ÎÎΰè¤Ï TSD ¥¡¼¤ò¥¤¥ó¥Ç¥Ã¥¯¥¹¤È¤·¤Æ´ÉÍý¤µ¤ì¤ë¡£
75 ·¿¤ÎÃͤò TSD ¥¡¼¤Ë·ë¤ÓÉÕ¤±¤ë¡£
76 TSD ¥¡¼¤Ï¤¹¤Ù¤Æ¤Î¥¹¥ì¥Ã¥É¤Ë¶¦Ä̤Ǥ¢¤ë¤¬¡¢
77 TSD ¥¡¼¤Ë·ë¤ÓÉÕ¤±¤é¤ì¤ëÃͤϥ¹¥ì¥Ã¥É¤´¤È¤Ë°Û¤Ê¤ë¤è¤¦¤Ë
80 .\"O For concreteness, the TSD areas can be viewed as arrays of
82 .\"O pointers, TSD keys as integer indices into these arrays, and the value
83 .\"O of a TSD key as the value of the corresponding array element in the
85 ¶ñÂÎŪ¤Ë¤¤¤¨¤Ð¡¢ TSD Îΰè¤Ï
87 ·¿¤Î¥Ý¥¤¥ó¥¿¤ÎÇÛÎó¤È¤·¤Æ¡¢
88 TSD ¥¡¼¤Ï¤³¤ÎÇÛÎó¤ËÂФ¹¤ëÀ°¿ôÃͤΥ¤¥ó¥Ç¥Ã¥¯¥¹¤È¤·¤Æ¡¢
89 TSD ¥¡¼¤Ë·ë¤ÓÉÕ¤±¤é¤ì¤ëÃͤϸƤӽФ·¥¹¥ì¥Ã¥É¤ÎÂбþ¤¹¤ëÇÛÎóÍ×ÁǤȤ·¤Æ¸«¤¨¤ë¡£
91 .\"O When a thread is created, its TSD area initially associates
94 ¥¹¥ì¥Ã¥É¤¬À¸À®¤µ¤ì¤ë¤È¡¢TSD Îΰè¤Ï¤¹¤Ù¤Æ¤Î¥¡¼¤ËÂФ¹¤ëÃͤ¬
96 ¤Ë¤Ê¤ë¤è¤¦½é´ü²½¤µ¤ì¤ë¡£
98 .\"O .B "pthread_key_create"
99 .\"O allocates a new TSD key. The key is stored in the
100 .\"O location pointed to by
102 .\"O There is a limit of
103 .\"O .B "PTHREAD_KEYS_MAX"
104 .\"O on the number of keys allocated at a given time. The value initially
105 .\"O associated with the returned key is
107 .\"O in all currently executing
109 .B "pthread_key_create"
110 ¤Ï¿·¤·¤¤ TSD ¥¡¼¤ò³ÎÊݤ¹¤ë¡£
113 ¤Ç»Ø¤·¼¨¤µ¤ì¤ëÎΰè¤Ë³ÊǼ¤µ¤ì¤ë¡£
114 ¤¢¤ë»þÅÀ¤Ç³ÎÊݤǤ¤ë¥¡¼¤Î¿ô¤Ë¤ÏÀ©¸Â¤¬¤¢¤ê¡¢
116 .B "PTHREAD_KEYS_MAX"
118 ÊÖ¤µ¤ì¤¿¥¡¼¤Ë·ë¤ÓÉÕ¤±¤é¤ì¤ë½é´üÃͤϡ¢
119 ¤½¤Î»þÅÀ¤Ç¼Â¹Ô¤µ¤ì¤Æ¤¤¤ë¥¹¥ì¥Ã¥É¤¹¤Ù¤Æ¤Ë¤ª¤¤¤Æ
124 .\"O .I "destr_function"
125 .\"O argument, if not
127 .\"O specifies a destructor
128 .\"O function associated with the key. When a thread terminates via
129 .\"O .B "pthread_exit"
130 .\"O or by cancellation,
131 .\"O .I "destr_function"
133 .\"O arguments the value associated with the key in that thread. The
134 .\"O .I "destr_function"
135 .\"O is not called if that value is
138 .\"O which destructor functions are called at thread termination time is
144 °Ê³°¤ÎÃͤò»ØÄꤹ¤ë¤³¤È¤Ç¡¢
145 ¤½¤Î¥¡¼¤ËÂбþ¤¹¤ë¥Ç¥¹¥È¥é¥¯¥¿´Ø¿ô¤òÅÐÏ¿¤¹¤ë¤³¤È¤¬¤Ç¤¤ë¡£
148 ¤ä¥¥ã¥ó¥»¥ë¤Ë¤è¤Ã¤Æ½ªÎ»¤¹¤ë¤È¡¢
149 ¤½¤Î¥¹¥ì¥Ã¥ÉÃæ¤Ç¥¡¼¤Ë·ë¤ÓÉÕ¤±¤é¤ì¤¿Ãͤò°ú¿ô¤È¤·¤Æ´Ø¿ô
157 ¥¹¥ì¥Ã¥É½ªÎ»»þ¤Ë¥Ç¥¹¥È¥é¥¯¥¿´Ø¿ô¤¬¸Æ¤Ó½Ð¤µ¤ì¤ë½ç½ø¤ÏÉÔÄê¤Ç¤¢¤ë¡£
159 .\"O Before the destructor function is called, the
162 .\"O associated with the key in the current thread. A destructor function
163 .\"O might, however, re-associate non-
165 .\"O values to that key or some
166 .\"O other key. To deal with this, if after all the destructors have been
167 .\"O called for all non-
169 .\"O values, there are still some non-
171 .\"O values with associated destructors, then the process is repeated. The
172 .\"O LinuxThreads implementation stops the process after
173 .\"O .B "PTHREAD_DESTRUCTOR_ITERATIONS"
174 .\"O iterations, even if some non-
176 .\"O values with associated descriptors remain. Other implementations may
177 .\"O loop indefinitely.
178 ¥Ç¥¹¥È¥é¥¯¥¿´Ø¿ô¤¬¸Æ¤Ó½Ð¤µ¤ì¤ëÁ°¤Ë¡¢
179 ¸½ºß¤Î¥¹¥ì¥Ã¥É¤Ë¤ª¤¤¤Æ¥¡¼¤Ë·ë¤ÓÉÕ¤±¤é¤ì¤ëÃͤÏ
182 ¤·¤«¤·¡¢¥Ç¥¹¥È¥é¥¯¥¿´Ø¿ô¤Ï
184 °Ê³°¤ÎÃͤò¤½¤Î¥¡¼¤ä¤Û¤«¤Î¥¡¼¤Ë·ë¤ÓÉÕ¤±¤ë¤«¤â¤·¤ì¤Ê¤¤¡£
188 ¤ÎÃͤËÂФ¹¤ë¥Ç¥¹¥È¥é¥¯¥¿´Ø¿ô¤ò¤¹¤Ù¤Æ¸Æ¤Ó½Ð¤·¤¿¤¢¤È¤Ë
189 ¥Ç¥¹¥È¥é¥¯¥¿´Ø¿ô¤Î¤¢¤ëÈó
191 ¤ÎÃͤ¬¤Þ¤À»Ä¤Ã¤Æ¤¤¤ë¾ì¹ç¤Ë¤Ï¡¢
192 ¥Ç¥¹¥È¥é¥¯¥¿´Ø¿ô¤Î¸Æ¤Ó½Ð¤·½èÍý¤Ï·«¤êÊÖ¤µ¤ì¤ë¡£
193 LinuxThreads ¤Î¼ÂÁõ¤Ç¤Ï¡¢
194 .B "PTHREAD_DESTRUCTOR_ITERATIONS"
195 ²ó·«¤êÊÖ¤¹¤È¡¢¤¿¤È¤¨¥Ç¥¹¥È¥é¥¯¥¿´Ø¿ô¤Î¤¢¤ëÈó
198 ½èÍý¤ÏÃæ»ß¤µ¤ì¤ë¡£LinuxThreads °Ê³°¤Î¼ÂÁõ¤Ç¤Ï̵¸Â¥ë¡¼¥×¤Ë´Ù¤ë¤«¤â¤·¤ì¤Ê¤¤¡£
200 .\"O .B "pthread_key_delete"
201 .\"O deallocates a TSD key. It does not check whether
204 .\"O values are associated with that key in the currently
205 .\"O executing threads, nor call the destructor function associated with
207 .B "pthread_key_delete"
208 ¤Ï TSD ¥¡¼¤ò²òÊü¤¹¤ë¡£
209 ¤½¤Î»þÅÀ¤Ç¼Â¹ÔÃæ¤Î¥¹¥ì¥Ã¥É¤Ç¥¡¼¤ËÈó
211 ¤ÎÃͤ¬·ë¤ÓÉÕ¤±¤é¤ì¤Æ¤¤¤ë¤«¤É¤¦¤«¤ò¥Á¥§¥Ã¥¯¤·¤¿¤ê¡¢
212 ¥¡¼¤ËÂбþ¤¹¤ë¥Ç¥¹¥È¥é¥¯¥¿´Ø¿ô¤ò¸Æ¤Ó½Ð¤·¤¿¤ê¤Ï¤·¤Ê¤¤¡£
214 .\"O .B "pthread_setspecific"
215 .\"O changes the value associated with
218 .\"O calling thread, storing the given
221 .B "pthread_setspecific"
224 ¤Ë·ë¤ÓÉÕ¤±¤é¤ì¤ëÃͤò¡¢Í¿¤¨¤é¤ì¤¿
228 .\"O .B "pthread_getspecific"
229 .\"O returns the value currently associated with
231 .\"O in the calling thread.
232 .B "pthread_getspecific"
233 ¤Ï¸Æ¤Ó½Ð¤·¥¹¥ì¥Ã¥É¤Ç¤½¤Î»þÅÀ¤Ç
235 ¤Ë·ë¤ÓÉÕ¤±¤é¤ì¤Æ¤¤¤ëÃͤòÊÖ¤¹¡£
237 .\"O .SH "RETURN VALUE"
240 .\"O .BR "pthread_key_create" ,
241 .\"O .BR "pthread_key_delete" ,
243 .\"O .B "pthread_setspecific"
244 .\"O return 0 on success and a non-zero error code on failure. If
246 .\"O .B "pthread_key_create"
247 .\"O stores the newly allocated key in the
248 .\"O location pointed to by its
251 .B "pthread_key_create"
253 .B "pthread_key_delete"
255 .B "pthread_setspecific"
256 ¤ÏÀ®¸ù¤¹¤ë¤È 0 ¤ò¡¢¼ºÇÔ¤¹¤ë¤ÈÈó 0 ¤Î¥¨¥é¡¼¥³¡¼¥É¤òÊÖ¤¹¡£
258 .B "pthread_key_create"
259 ¤Ï¿·¤·¤¯³ÎÊݤµ¤ì¤¿¥¡¼¤ò
262 ¤Ç»Ø¤·¼¨¤µ¤ì¤ëÎΰè¤Ë³ÊǼ¤¹¤ë¡£
264 .\"O .B "pthread_getspecific"
265 .\"O returns the value associated with
271 .B "pthread_getspecific"
274 ¤Ë·ë¤ÓÉÕ¤±¤é¤ì¤¿Ãͤò¡¢
280 .\"O .B "pthread_key_create"
281 .\"O returns the following error code on error:
285 .\"O .B "PTHREAD_KEYS_MAX"
286 .\"O keys are already allocated
289 .B "pthread_key_create"
290 ¤Ï¥¨¥é¡¼¤Î¾ì¹ç¤Ë¼¡¤Î¤è¤¦¤Ê¥¨¥é¡¼¥³¡¼¥É¤òÊÖ¤¹:
294 .B "PTHREAD_KEYS_MAX"
295 ¤À¤±¤Î¥¡¼¤¬¤¹¤Ç¤Ë³ÎÊݤµ¤ì¤Æ¤¤¤ë¡£
298 .\"O .B "pthread_key_delete"
300 .\"O .B "pthread_setspecific"
301 .\"O return the following
302 .\"O error code on error:
307 .\"O is not a valid, allocated TSD key
309 .B "pthread_key_delete"
311 .B "pthread_setspecific"
312 ¤Ï¥¨¥é¡¼¤Î¾ì¹ç¤Ë¼¡¤Î¤è¤¦¤Ê¥¨¥é¡¼¥³¡¼¥É¤òÊÖ¤¹:
317 ¤Ï͸ú¤Ê¡¢³ÎÊݤµ¤ì¤¿ TSD ¥¡¼¤Ç¤Ï¤Ê¤¤¡£
320 .\"O .B "pthread_getspecific"
326 .\"O allocated TSD key.
327 .B "pthread_getspecific"
330 ¤¬Í¸ú¤Ê¡¢³ÎÊݤµ¤ì¤¿ TSD ¥¡¼¤Ç¤Ê¤¤¾ì¹ç¤Ë¤Ï
336 Xavier Leroy <Xavier.Leroy@inria.fr>
340 pthread_create(3), pthread_exit(3), pthread_testcancel(3).
345 .\"O The following code fragment allocates a thread-specific array of 100
346 .\"O characters, with automatic reclaimation at thread exit:
347 ¼¡¤Î¥³¡¼¥É¤Ç¤Ï¡¢100 ¥Ð¥¤¥È¤Î¥¹¥ì¥Ã¥É¸ÇͤÎÇÛÎó¤ò³ÎÊݤ·¡¢
348 ¥¹¥ì¥Ã¥É¤Î½ªÎ»¤È¤È¤â¤Ë¼«Æ°¤Ç²òÊü¤¹¤ë:
354 .\"O /* Key for the thread-specific buffer */
355 /* ¥¹¥ì¥Ã¥É¸ÇͥХåե¡¤Î¥¡¼ */
356 static pthread_key_t buffer_key;
358 .\"O /* Once-only initialisation of the key */
359 /* 1 ²ó¸Â¤ê¤Î¥¡¼¤Î½é´ü²½ */
360 static pthread_once_t buffer_key_once = PTHREAD_ONCE_INIT;
362 .\"O /* Allocate the thread-specific buffer */
363 /* ¥¹¥ì¥Ã¥É¸ÇͤΥХåե¡¤ò³ÎÊݤ¹¤ë */
364 void buffer_alloc(void)
366 pthread_once(&buffer_key_once, buffer_key_alloc);
367 pthread_setspecific(buffer_key, malloc(100));
370 .\"O /* Return the thread-specific buffer */
371 /* ¥¹¥ì¥Ã¥É¸ÇͤΥХåե¡¤òÊÖ¤¹ */
372 char * get_buffer(void)
374 return (char *) pthread_getspecific(buffer_key);
377 .\"O /* Allocate the key */
379 static void buffer_key_alloc()
381 pthread_key_create(&buffer_key, buffer_destroy);
384 .\"O /* Free the thread-specific buffer */
385 /* ¥¹¥ì¥Ã¥É¸ÇͤΥХåե¡¤ò²òÊü¤¹¤ë */
386 static void buffer_destroy(void * buf)