OSDN Git Service

Import translated manuals from JM CVS Repository.
[linuxjm/jm.git] / manual / glibc-linuxthreads / draft / man3 / pthread_key_create.3
1 .\"   Copyright (C) 1996-1999 Free Software Foundation, Inc.
2 .\"
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.
6 .\"
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.
11 .\"
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.
16 .\"
17 .\" Copyright (C) 1996 Xavier Leroy.
18 .\"
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.
23 .\"
24 .\"WORD:    thread-specific data    ¥¹¥ì¥Ã¥É¸ÇÍ­¥Ç¡¼¥¿
25 .\"WORD:    thread-specific key ¥¹¥ì¥Ã¥É¸ÇÍ­¥­¡¼
26 .\"WORD:    destructor function ¥Ç¥¹¥È¥é¥¯¥¿´Ø¿ô
27 .\"
28 .\"
29 .TH PTHREAD_SPECIFIC 3 LinuxThreads
30
31 .\"O .SH NAME
32 .SH "̾Á°"
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 \- ¥¹¥ì¥Ã¥É¸ÇÍ­¥Ç¡¼¥¿¤Î´ÉÍý
35
36 .\"O .SH SYNOPSIS
37 .SH "½ñ¼°"
38 .B #include <pthread.h>
39
40 .BI "int pthread_key_create(pthread_key_t *" key ", void (*" destr_function ") (void *));"
41
42 .BI "int pthread_key_delete(pthread_key_t " key ");"
43
44 .BI "int pthread_setspecific(pthread_key_t " key ", const void *" pointer ");"
45
46 .BI "void * pthread_getspecific(pthread_key_t " key ");"
47
48 .\"O .SH DESCRIPTION
49 .SH "ÀâÌÀ"
50
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 ¥¹¥ì¥Ã¥É¤ÎÅú¤¨¤Ç¤¢¤ë¡£
61
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 
65 .\"O .B "void *"
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) Îΰ衢
70 ά¤·¤Æ TSD Îΰè¤È¤¤¤¦
71 ¥×¥é¥¤¥Ù¡¼¥È¤Ê¥á¥â¥ê¥Ö¥í¥Ã¥¯¤òÊÝÍ­¤·¤Æ¤¤¤ë¡£
72 ¤³¤ÎÎΰè¤Ï TSD ¥­¡¼¤ò¥¤¥ó¥Ç¥Ã¥¯¥¹¤È¤·¤Æ´ÉÍý¤µ¤ì¤ë¡£
73 TSD Îΰè¤Ç¤Ï
74 .B "void *"
75 ·¿¤ÎÃͤò TSD ¥­¡¼¤Ë·ë¤ÓÉÕ¤±¤ë¡£
76 TSD ¥­¡¼¤Ï¤¹¤Ù¤Æ¤Î¥¹¥ì¥Ã¥É¤Ë¶¦Ä̤Ǥ¢¤ë¤¬¡¢
77 TSD ¥­¡¼¤Ë·ë¤ÓÉÕ¤±¤é¤ì¤ëÃͤϥ¹¥ì¥Ã¥É¤´¤È¤Ë°Û¤Ê¤ë¤è¤¦¤Ë
78 ¤¹¤ë¤³¤È¤¬¤Ç¤­¤ë¡£
79
80 .\"O For concreteness, the TSD areas can be viewed as arrays of 
81 .\"O .B "void *"
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
84 .\"O calling thread.
85 ¶ñÂÎŪ¤Ë¤¤¤¨¤Ð¡¢ TSD Îΰè¤Ï
86 .B "void *"
87 ·¿¤Î¥Ý¥¤¥ó¥¿¤ÎÇÛÎó¤È¤·¤Æ¡¢
88 TSD ¥­¡¼¤Ï¤³¤ÎÇÛÎó¤ËÂФ¹¤ëÀ°¿ôÃͤΥ¤¥ó¥Ç¥Ã¥¯¥¹¤È¤·¤Æ¡¢
89 TSD ¥­¡¼¤Ë·ë¤ÓÉÕ¤±¤é¤ì¤ëÃͤϸƤӽФ·¥¹¥ì¥Ã¥É¤ÎÂбþ¤¹¤ëÇÛÎóÍ×ÁǤȤ·¤Æ¸«¤¨¤ë¡£
90
91 .\"O When a thread is created, its TSD area initially associates 
92 .\"O .B "NULL"
93 .\"O with all keys.
94 ¥¹¥ì¥Ã¥É¤¬À¸À®¤µ¤ì¤ë¤È¡¢TSD Îΰè¤Ï¤¹¤Ù¤Æ¤Î¥­¡¼¤ËÂФ¹¤ëÃͤ¬
95 .B "NULL"
96 ¤Ë¤Ê¤ë¤è¤¦½é´ü²½¤µ¤ì¤ë¡£
97
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 
101 .\"O .IR "key" .
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 
106 .\"O .B "NULL"
107 .\"O in all currently executing
108 .\"O threads.
109 .B "pthread_key_create"
110 ¤Ï¿·¤·¤¤ TSD ¥­¡¼¤ò³ÎÊݤ¹¤ë¡£
111 ¥­¡¼¤Ï
112 .I "key"
113 ¤Ç»Ø¤·¼¨¤µ¤ì¤ëÎΰè¤Ë³ÊǼ¤µ¤ì¤ë¡£
114 ¤¢¤ë»þÅÀ¤Ç³ÎÊݤǤ­¤ë¥­¡¼¤Î¿ô¤Ë¤ÏÀ©¸Â¤¬¤¢¤ê¡¢
115 ¤½¤ÎºÇÂçÃͤÏ
116 .B "PTHREAD_KEYS_MAX"
117 ¤Ç¤¢¤ë¡£
118 ÊÖ¤µ¤ì¤¿¥­¡¼¤Ë·ë¤ÓÉÕ¤±¤é¤ì¤ë½é´üÃͤϡ¢
119 ¤½¤Î»þÅÀ¤Ç¼Â¹Ô¤µ¤ì¤Æ¤¤¤ë¥¹¥ì¥Ã¥É¤¹¤Ù¤Æ¤Ë¤ª¤¤¤Æ
120 .B "NULL"
121 ¤Ç¤¢¤ë¡£
122
123 .\"O The 
124 .\"O .I "destr_function"
125 .\"O argument, if not 
126 .\"O .BR "NULL" ,
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"
132 .\"O is called with
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 
136 .\"O .BR "NULL" .
137 .\"O The order in
138 .\"O which destructor functions are called at thread termination time is
139 .\"O unspecified.
140 °ú¿ô
141 .I "destr_function"
142 ¤Ë
143 .B "NULL"
144 °Ê³°¤ÎÃͤò»ØÄꤹ¤ë¤³¤È¤Ç¡¢
145 ¤½¤Î¥­¡¼¤ËÂбþ¤¹¤ë¥Ç¥¹¥È¥é¥¯¥¿´Ø¿ô¤òÅÐÏ¿¤¹¤ë¤³¤È¤¬¤Ç¤­¤ë¡£
146 ¥¹¥ì¥Ã¥É¤¬
147 .B "pthread_exit"
148 ¤ä¥­¥ã¥ó¥»¥ë¤Ë¤è¤Ã¤Æ½ªÎ»¤¹¤ë¤È¡¢
149 ¤½¤Î¥¹¥ì¥Ã¥ÉÃæ¤Ç¥­¡¼¤Ë·ë¤ÓÉÕ¤±¤é¤ì¤¿Ãͤò°ú¿ô¤È¤·¤Æ´Ø¿ô
150 .I "destr_function"
151 ¤¬¸Æ¤Ó½Ð¤µ¤ì¤ë¡£
152 Ãͤ¬
153 .B "NULL"
154 ¤Î¾ì¹ç¤Ë¤Ï´Ø¿ô
155 .I "destr_function"
156 ¤Ï¸Æ¤Ó½Ð¤µ¤ì¤Ê¤¤¡£
157 ¥¹¥ì¥Ã¥É½ªÎ»»þ¤Ë¥Ç¥¹¥È¥é¥¯¥¿´Ø¿ô¤¬¸Æ¤Ó½Ð¤µ¤ì¤ë½ç½ø¤ÏÉÔÄê¤Ç¤¢¤ë¡£
158
159 .\"O Before the destructor function is called, the 
160 .\"O .B "NULL"
161 .\"O value is
162 .\"O associated with the key in the current thread.  A destructor function
163 .\"O might, however, re-associate non-
164 .\"O .B "NULL"
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-
168 .\"O .B "NULL"
169 .\"O values, there are still some non-
170 .\"O .B "NULL"
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-
175 .\"O .B "NULL"
176 .\"O values with associated descriptors remain.  Other implementations may
177 .\"O loop indefinitely.
178 ¥Ç¥¹¥È¥é¥¯¥¿´Ø¿ô¤¬¸Æ¤Ó½Ð¤µ¤ì¤ëÁ°¤Ë¡¢
179 ¸½ºß¤Î¥¹¥ì¥Ã¥É¤Ë¤ª¤¤¤Æ¥­¡¼¤Ë·ë¤ÓÉÕ¤±¤é¤ì¤ëÃͤÏ
180 .B "NULL"
181 ¤Ë¤Ê¤ë¡£
182 ¤·¤«¤·¡¢¥Ç¥¹¥È¥é¥¯¥¿´Ø¿ô¤Ï
183 .B "NULL"
184 °Ê³°¤ÎÃͤò¤½¤Î¥­¡¼¤ä¤Û¤«¤Î¥­¡¼¤Ë·ë¤ÓÉÕ¤±¤ë¤«¤â¤·¤ì¤Ê¤¤¡£
185 ¤³¤ì¤ò½èÍý¤¹¤ë¤¿¤á¡¢
186 ¤¹¤Ù¤Æ¤ÎÈó
187 .B "NULL"
188 ¤ÎÃͤËÂФ¹¤ë¥Ç¥¹¥È¥é¥¯¥¿´Ø¿ô¤ò¤¹¤Ù¤Æ¸Æ¤Ó½Ð¤·¤¿¤¢¤È¤Ë
189 ¥Ç¥¹¥È¥é¥¯¥¿´Ø¿ô¤Î¤¢¤ëÈó
190 .B "NULL"
191 ¤ÎÃͤ¬¤Þ¤À»Ä¤Ã¤Æ¤¤¤ë¾ì¹ç¤Ë¤Ï¡¢
192 ¥Ç¥¹¥È¥é¥¯¥¿´Ø¿ô¤Î¸Æ¤Ó½Ð¤·½èÍý¤Ï·«¤êÊÖ¤µ¤ì¤ë¡£
193 LinuxThreads ¤Î¼ÂÁõ¤Ç¤Ï¡¢
194 .B "PTHREAD_DESTRUCTOR_ITERATIONS"
195 ²ó·«¤êÊÖ¤¹¤È¡¢¤¿¤È¤¨¥Ç¥¹¥È¥é¥¯¥¿´Ø¿ô¤Î¤¢¤ëÈó
196 .B "NULL"
197 ¤ÎÃͤ¬»Ä¤Ã¤Æ¤¤¤Æ¤â¡¢
198 ½èÍý¤ÏÃæ»ß¤µ¤ì¤ë¡£LinuxThreads °Ê³°¤Î¼ÂÁõ¤Ç¤Ï̵¸Â¥ë¡¼¥×¤Ë´Ù¤ë¤«¤â¤·¤ì¤Ê¤¤¡£
199
200 .\"O .B "pthread_key_delete"
201 .\"O deallocates a TSD key. It does not check whether
202 .\"O non-
203 .\"O .B "NULL"
204 .\"O values are associated with that key in the currently
205 .\"O executing threads, nor call the destructor function associated with
206 .\"O the key.
207 .B "pthread_key_delete"
208 ¤Ï TSD ¥­¡¼¤ò²òÊü¤¹¤ë¡£
209 ¤½¤Î»þÅÀ¤Ç¼Â¹ÔÃæ¤Î¥¹¥ì¥Ã¥É¤Ç¥­¡¼¤ËÈó
210 .B "NULL"
211 ¤ÎÃͤ¬·ë¤ÓÉÕ¤±¤é¤ì¤Æ¤¤¤ë¤«¤É¤¦¤«¤ò¥Á¥§¥Ã¥¯¤·¤¿¤ê¡¢
212 ¥­¡¼¤ËÂбþ¤¹¤ë¥Ç¥¹¥È¥é¥¯¥¿´Ø¿ô¤ò¸Æ¤Ó½Ð¤·¤¿¤ê¤Ï¤·¤Ê¤¤¡£
213
214 .\"O .B "pthread_setspecific"
215 .\"O changes the value associated with 
216 .\"O .I "key"
217 .\"O in the
218 .\"O calling thread, storing the given 
219 .\"O .I "pointer"
220 .\"O instead.
221 .B "pthread_setspecific"
222 ¤Ï¸Æ¤Ó½Ð¤·¥¹¥ì¥Ã¥É¤Ç
223 .I "key"
224 ¤Ë·ë¤ÓÉÕ¤±¤é¤ì¤ëÃͤò¡¢Í¿¤¨¤é¤ì¤¿
225 .I "pointer"
226 ¤ËÊѹ¹¤¹¤ë¡£
227
228 .\"O .B "pthread_getspecific"
229 .\"O returns the value currently associated with
230 .\"O .I "key"
231 .\"O in the calling thread.
232 .B "pthread_getspecific"
233 ¤Ï¸Æ¤Ó½Ð¤·¥¹¥ì¥Ã¥É¤Ç¤½¤Î»þÅÀ¤Ç
234 .I "key"
235 ¤Ë·ë¤ÓÉÕ¤±¤é¤ì¤Æ¤¤¤ëÃͤòÊÖ¤¹¡£
236
237 .\"O .SH "RETURN VALUE"
238 .SH "ÊÖ¤êÃÍ"
239
240 .\"O .BR "pthread_key_create" ,
241 .\"O .BR "pthread_key_delete" ,
242 .\"O and 
243 .\"O .B "pthread_setspecific"
244 .\"O return 0 on success and a non-zero error code on failure. If
245 .\"O successful, 
246 .\"O .B "pthread_key_create"
247 .\"O stores the newly allocated key in the
248 .\"O location pointed to by its 
249 .\"O .I "key"
250 .\"O argument.
251 .B "pthread_key_create"
252 ¤ª¤è¤Ó
253 .B "pthread_key_delete"
254 ¡¢
255 .B "pthread_setspecific"
256 ¤ÏÀ®¸ù¤¹¤ë¤È 0 ¤ò¡¢¼ºÇÔ¤¹¤ë¤ÈÈó 0 ¤Î¥¨¥é¡¼¥³¡¼¥É¤òÊÖ¤¹¡£
257 À®¸ù¤Î¾ì¹ç¡¢
258 .B "pthread_key_create"
259 ¤Ï¿·¤·¤¯³ÎÊݤµ¤ì¤¿¥­¡¼¤ò
260 °ú¿ô
261 .I "key"
262 ¤Ç»Ø¤·¼¨¤µ¤ì¤ëÎΰè¤Ë³ÊǼ¤¹¤ë¡£
263
264 .\"O .B "pthread_getspecific"
265 .\"O returns the value associated with 
266 .\"O .I "key"
267 .\"O on
268 .\"O success, and 
269 .\"O .B "NULL"
270 .\"O on error.
271 .B "pthread_getspecific"
272 ¤Ï¡¢À®¸ù¤¹¤ë¤È¥­¡¼
273 .I "key"
274 ¤Ë·ë¤ÓÉÕ¤±¤é¤ì¤¿Ãͤò¡¢
275 ¥¨¥é¡¼¤Î¾ì¹ç¤Ë¤Ï
276 .B "NULL"
277 ¤òÊÖ¤¹¡£
278
279 .\"O .SH ERRORS
280 .\"O .B "pthread_key_create"
281 .\"O returns the following error code on error:
282 .\"O .RS
283 .\"O .TP
284 .\"O .B "EAGAIN"
285 .\"O .B "PTHREAD_KEYS_MAX"
286 .\"O keys are already allocated
287 .\"O .RE
288 .SH "¥¨¥é¡¼"
289 .B "pthread_key_create"
290 ¤Ï¥¨¥é¡¼¤Î¾ì¹ç¤Ë¼¡¤Î¤è¤¦¤Ê¥¨¥é¡¼¥³¡¼¥É¤òÊÖ¤¹:
291 .RS
292 .TP
293 .B "EAGAIN"
294 .B "PTHREAD_KEYS_MAX"
295 ¤À¤±¤Î¥­¡¼¤¬¤¹¤Ç¤Ë³ÎÊݤµ¤ì¤Æ¤¤¤ë¡£
296 .RE
297
298 .\"O .B "pthread_key_delete"
299 .\"O and 
300 .\"O .B "pthread_setspecific"
301 .\"O return the following
302 .\"O error code on error:
303 .\"O .RS
304 .\"O .TP
305 .\"O .B "EINVAL"
306 .\"O .I "key"
307 .\"O is not a valid, allocated TSD key
308 .\"O .RE
309 .B "pthread_key_delete"
310 ¤ª¤è¤Ó 
311 .B "pthread_setspecific"
312 ¤Ï¥¨¥é¡¼¤Î¾ì¹ç¤Ë¼¡¤Î¤è¤¦¤Ê¥¨¥é¡¼¥³¡¼¥É¤òÊÖ¤¹:
313 .RS
314 .TP
315 .B "EINVAL"
316 .I "key"
317 ¤ÏÍ­¸ú¤Ê¡¢³ÎÊݤµ¤ì¤¿ TSD ¥­¡¼¤Ç¤Ï¤Ê¤¤¡£
318 .RE
319
320 .\"O .B "pthread_getspecific"
321 .\"O returns 
322 .\"O .B "NULL"
323 .\"O if 
324 .\"O .I "key"
325 .\"O is not a valid,
326 .\"O allocated TSD key.
327 .B "pthread_getspecific"
328 ¤Ï¡¢
329 .I "key"
330 ¤¬Í­¸ú¤Ê¡¢³ÎÊݤµ¤ì¤¿ TSD ¥­¡¼¤Ç¤Ê¤¤¾ì¹ç¤Ë¤Ï
331 .B "NULL"
332 ¤òÊÖ¤¹¡£
333
334 .\"O .SH AUTHOR
335 .SH "Ãø¼Ô"
336 Xavier Leroy <Xavier.Leroy@inria.fr>
337
338 .\"O .SH "SEE ALSO"
339 .SH "´ØÏ¢¹àÌÜ"
340 pthread_create(3), pthread_exit(3), pthread_testcancel(3).
341
342 .\"O .SH EXAMPLE
343 .SH "Îã"
344
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 ¥¹¥ì¥Ã¥É¤Î½ªÎ»¤È¤È¤â¤Ë¼«Æ°¤Ç²òÊü¤¹¤ë:
349
350 .RS
351 .ft 3
352 .nf
353 .sp
354 .\"O /* Key for the thread-specific buffer */
355 /* ¥¹¥ì¥Ã¥É¸ÇÍ­¥Ð¥Ã¥Õ¥¡¤Î¥­¡¼ */
356 static pthread_key_t buffer_key;
357
358 .\"O /* Once-only initialisation of the key */
359 /* 1 ²ó¸Â¤ê¤Î¥­¡¼¤Î½é´ü²½ */
360 static pthread_once_t buffer_key_once = PTHREAD_ONCE_INIT;
361
362 .\"O /* Allocate the thread-specific buffer */
363 /* ¥¹¥ì¥Ã¥É¸ÇÍ­¤Î¥Ð¥Ã¥Õ¥¡¤ò³ÎÊݤ¹¤ë */
364 void buffer_alloc(void)
365 {
366   pthread_once(&buffer_key_once, buffer_key_alloc);
367   pthread_setspecific(buffer_key, malloc(100));
368 }
369
370 .\"O /* Return the thread-specific buffer */
371 /* ¥¹¥ì¥Ã¥É¸ÇÍ­¤Î¥Ð¥Ã¥Õ¥¡¤òÊÖ¤¹ */
372 char * get_buffer(void)
373 {
374   return (char *) pthread_getspecific(buffer_key);
375 }
376
377 .\"O /* Allocate the key */
378 /* ¥­¡¼¤ò³ÎÊݤ¹¤ë */
379 static void buffer_key_alloc()
380 {
381   pthread_key_create(&buffer_key, buffer_destroy);
382 }
383
384 .\"O /* Free the thread-specific buffer */
385 /* ¥¹¥ì¥Ã¥É¸ÇÍ­¤Î¥Ð¥Ã¥Õ¥¡¤ò²òÊü¤¹¤ë */
386 static void buffer_destroy(void * buf)
387 {
388   free(buf);
389 }
390 .ft
391 .LP
392 .RE
393 .fi