logo

oasis-root

Compiled tree of Oasis Linux based on own branch at <https://hacktivis.me/git/oasis/> git clone https://anongit.hacktivis.me/git/oasis-root.git

pthread_key_create.3p (8647B)


  1. '\" et
  2. .TH PTHREAD_KEY_CREATE "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual"
  3. .\"
  4. .SH PROLOG
  5. This manual page is part of the POSIX Programmer's Manual.
  6. The Linux implementation of this interface may differ (consult
  7. the corresponding Linux manual page for details of Linux behavior),
  8. or the interface may not be implemented on Linux.
  9. .\"
  10. .SH NAME
  11. pthread_key_create
  12. \(em thread-specific data key creation
  13. .SH SYNOPSIS
  14. .LP
  15. .nf
  16. #include <pthread.h>
  17. .P
  18. int pthread_key_create(pthread_key_t *\fIkey\fP, void (*\fIdestructor\fP)(void*));
  19. .fi
  20. .SH DESCRIPTION
  21. The
  22. \fIpthread_key_create\fR()
  23. function shall create a thread-specific data key visible to all threads
  24. in the process. Key values provided by
  25. \fIpthread_key_create\fR()
  26. are opaque objects used to locate thread-specific data. Although the
  27. same key value may be used by different threads, the values bound to
  28. the key by
  29. \fIpthread_setspecific\fR()
  30. are maintained on a per-thread basis and persist for the life of the
  31. calling thread.
  32. .P
  33. Upon key creation, the value NULL shall be associated with the new key
  34. in all active threads. Upon thread creation, the value NULL shall be
  35. associated with all defined keys in the new thread.
  36. .P
  37. An optional destructor function may be associated with each key value.
  38. At thread exit, if a key value has a non-NULL destructor pointer, and
  39. the thread has a non-NULL value associated with that key, the value of
  40. the key is set to NULL, and then the function pointed to is called with
  41. the previously associated value as its sole argument. The order of
  42. destructor calls is unspecified if more than one destructor exists for
  43. a thread when it exits.
  44. .P
  45. If, after all the destructors have been called for all non-NULL values
  46. with associated destructors, there are still some non-NULL values with
  47. associated destructors, then the process is repeated. If, after at
  48. least
  49. {PTHREAD_DESTRUCTOR_ITERATIONS}
  50. iterations of destructor calls for outstanding non-NULL values, there
  51. are still some non-NULL values with associated destructors,
  52. implementations may stop calling destructors, or they may continue
  53. calling destructors until no non-NULL values with associated
  54. destructors exist, even though this might result in an infinite loop.
  55. .SH "RETURN VALUE"
  56. If successful, the
  57. \fIpthread_key_create\fR()
  58. function shall store the newly created key value at *\fIkey\fP and
  59. shall return zero. Otherwise, an error number shall be returned to
  60. indicate the error.
  61. .SH ERRORS
  62. The
  63. \fIpthread_key_create\fR()
  64. function shall fail if:
  65. .TP
  66. .BR EAGAIN
  67. The system lacked the necessary resources to create another
  68. thread-specific data key, or the system-imposed limit on the total
  69. number of keys per process
  70. {PTHREAD_KEYS_MAX}
  71. has been exceeded.
  72. .TP
  73. .BR ENOMEM
  74. Insufficient memory exists to create the key.
  75. .P
  76. The
  77. \fIpthread_key_create\fR()
  78. function shall not return an error code of
  79. .BR [EINTR] .
  80. .LP
  81. .IR "The following sections are informative."
  82. .SH EXAMPLES
  83. The following example demonstrates a function that initializes a
  84. thread-specific data key when it is first called, and associates a
  85. thread-specific object with each calling thread, initializing this
  86. object when necessary.
  87. .sp
  88. .RS 4
  89. .nf
  90. static pthread_key_t key;
  91. static pthread_once_t key_once = PTHREAD_ONCE_INIT;
  92. .P
  93. static void
  94. make_key()
  95. {
  96. (void) pthread_key_create(&key, NULL);
  97. }
  98. .P
  99. func()
  100. {
  101. void *ptr;
  102. .P
  103. (void) pthread_once(&key_once, make_key);
  104. if ((ptr = pthread_getspecific(key)) == NULL) {
  105. ptr = malloc(OBJECT_SIZE);
  106. ...
  107. (void) pthread_setspecific(key, ptr);
  108. }
  109. ...
  110. }
  111. .fi
  112. .P
  113. .RE
  114. .P
  115. Note that the key has to be initialized before
  116. \fIpthread_getspecific\fR()
  117. or
  118. \fIpthread_setspecific\fR()
  119. can be used. The
  120. \fIpthread_key_create\fR()
  121. call could either be explicitly made in a module initialization
  122. routine, or it can be done implicitly by the first call to a module as
  123. in this example. Any attempt to use the key before it is initialized
  124. is a programming error, making the code below incorrect.
  125. .sp
  126. .RS 4
  127. .nf
  128. static pthread_key_t key;
  129. .P
  130. func()
  131. {
  132. void *ptr;
  133. .P
  134. /* KEY NOT INITIALIZED!!! THIS WILL NOT WORK!!! */
  135. if ((ptr = pthread_getspecific(key)) == NULL &&
  136. pthread_setspecific(key, NULL) != 0) {
  137. pthread_key_create(&key, NULL);
  138. ...
  139. }
  140. }
  141. .fi
  142. .P
  143. .RE
  144. .SH "APPLICATION USAGE"
  145. None.
  146. .br
  147. .SH RATIONALE
  148. .SS "Destructor Functions"
  149. .P
  150. Normally, the value bound to a key on behalf of a particular thread is
  151. a pointer to storage allocated dynamically on behalf of the calling
  152. thread. The destructor functions specified with
  153. \fIpthread_key_create\fR()
  154. are intended to be used to free this storage when the thread exits.
  155. Thread
  156. cancellation cleanup handlers cannot be used for this purpose because
  157. thread-specific data may persist outside the lexical scope in which the
  158. cancellation cleanup handlers operate.
  159. .P
  160. If the value associated with a key needs to be updated during the
  161. lifetime of the thread, it may be necessary to release the storage
  162. associated with the old value before the new value is bound. Although
  163. the
  164. \fIpthread_setspecific\fR()
  165. function could do this automatically, this feature is not needed often
  166. enough to justify the added complexity. Instead, the programmer is
  167. responsible for freeing the stale storage:
  168. .sp
  169. .RS 4
  170. .nf
  171. pthread_getspecific(key, &old);
  172. new = allocate();
  173. destructor(old);
  174. pthread_setspecific(key, new);
  175. .fi
  176. .P
  177. .RE
  178. .TP 10
  179. .BR Note:
  180. The above example could leak storage if run with asynchronous
  181. cancellation enabled. No such problems occur in the default cancellation
  182. state if no cancellation points occur between the get and set.
  183. .P
  184. .P
  185. There is no notion of a destructor-safe function. If an application
  186. does not call
  187. \fIpthread_exit\fR()
  188. from a signal handler, or if it blocks any signal whose handler may
  189. call
  190. \fIpthread_exit\fR()
  191. while calling async-unsafe functions, all functions may be safely
  192. called from destructors.
  193. .SS "Non-Idempotent Data Key Creation"
  194. .P
  195. There were requests to make
  196. \fIpthread_key_create\fR()
  197. idempotent with respect to a given
  198. .IR key
  199. address parameter. This would allow applications to call
  200. \fIpthread_key_create\fR()
  201. multiple times for a given
  202. .IR key
  203. address and be guaranteed that only one key would be created. Doing so
  204. would require the key value to be previously initialized (possibly at
  205. compile time) to a known null value and would require that implicit
  206. mutual-exclusion be performed based on the address and contents of the
  207. .IR key
  208. parameter in order to guarantee that exactly one key would be created.
  209. .P
  210. Unfortunately, the implicit mutual-exclusion would not be limited to
  211. only
  212. \fIpthread_key_create\fR().
  213. On many implementations, implicit mutual-exclusion would also have to
  214. be performed by
  215. \fIpthread_getspecific\fR()
  216. and
  217. \fIpthread_setspecific\fR()
  218. in order to guard against using incompletely stored or not-yet-visible
  219. key values. This could significantly increase the cost of important
  220. operations, particularly
  221. \fIpthread_getspecific\fR().
  222. .P
  223. Thus, this proposal was rejected. The
  224. \fIpthread_key_create\fR()
  225. function performs no implicit synchronization. It is the
  226. responsibility of the programmer to ensure that it is called exactly
  227. once per key before use of the key. Several straightforward mechanisms
  228. can already be used to accomplish this, including calling explicit
  229. module initialization functions, using mutexes, and using
  230. \fIpthread_once\fR().
  231. This places no significant burden on the programmer, introduces no
  232. possibly confusing \fIad hoc\fP implicit synchronization mechanism, and
  233. potentially allows commonly used thread-specific data operations to be
  234. more efficient.
  235. .SH "FUTURE DIRECTIONS"
  236. None.
  237. .SH "SEE ALSO"
  238. .IR "\fIpthread_getspecific\fR\^(\|)",
  239. .IR "\fIpthread_key_delete\fR\^(\|)"
  240. .P
  241. The Base Definitions volume of POSIX.1\(hy2017,
  242. .IR "\fB<pthread.h>\fP"
  243. .\"
  244. .SH COPYRIGHT
  245. Portions of this text are reprinted and reproduced in electronic form
  246. from IEEE Std 1003.1-2017, Standard for Information Technology
  247. -- Portable Operating System Interface (POSIX), The Open Group Base
  248. Specifications Issue 7, 2018 Edition,
  249. Copyright (C) 2018 by the Institute of
  250. Electrical and Electronics Engineers, Inc and The Open Group.
  251. In the event of any discrepancy between this version and the original IEEE and
  252. The Open Group Standard, the original IEEE and The Open Group Standard
  253. is the referee document. The original Standard can be obtained online at
  254. http://www.opengroup.org/unix/online.html .
  255. .PP
  256. Any typographical or formatting errors that appear
  257. in this page are most likely
  258. to have been introduced during the conversion of the source files to
  259. man page format. To report such errors, see
  260. https://www.kernel.org/doc/man-pages/reporting_bugs.html .