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_getspecific.3p (4533B)

    

  1. '\" et
  2. .TH PTHREAD_GETSPECIFIC "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_getspecific,
  12. pthread_setspecific
  13. \(em thread-specific data management
  14. .SH SYNOPSIS
  15. .LP
  16. .nf
  17. #include <pthread.h>
  18. .P
  19. void *pthread_getspecific(pthread_key_t \fIkey\fP);
  20. int pthread_setspecific(pthread_key_t \fIkey\fP, const void *\fIvalue\fP);
  21. .fi
  22. .SH DESCRIPTION
  23. The
  24. \fIpthread_getspecific\fR()
  25. function shall return the value currently bound to the specified
  26. .IR key
  27. on behalf of the calling thread.
  28. .P
  29. The
  30. \fIpthread_setspecific\fR()
  31. function shall associate a thread-specific
  32. .IR value
  33. with a
  34. .IR key
  35. obtained via a previous call to
  36. \fIpthread_key_create\fR().
  37. Different threads may bind different values to the same key. These
  38. values are typically pointers to blocks of dynamically allocated memory
  39. that have been reserved for use by the calling thread.
  40. .P
  41. The effect of calling
  42. \fIpthread_getspecific\fR()
  43. or
  44. \fIpthread_setspecific\fR()
  45. with a
  46. .IR key
  47. value not obtained from
  48. \fIpthread_key_create\fR()
  49. or after
  50. .IR key
  51. has been deleted with
  52. \fIpthread_key_delete\fR()
  53. is undefined.
  54. .P
  55. Both
  56. \fIpthread_getspecific\fR()
  57. and
  58. \fIpthread_setspecific\fR()
  59. may be called from a thread-specific data destructor function. A call
  60. to
  61. \fIpthread_getspecific\fR()
  62. for the thread-specific data key being destroyed shall return the value
  63. NULL, unless the value is changed (after the destructor starts) by a
  64. call to
  65. \fIpthread_setspecific\fR().
  66. Calling
  67. \fIpthread_setspecific\fR()
  68. from a thread-specific data destructor routine may result either in lost
  69. storage (after at least PTHREAD_DESTRUCTOR_ITERATIONS attempts at
  70. destruction) or in an infinite loop.
  71. .P
  72. Both functions may be implemented as macros.
  73. .SH "RETURN VALUE"
  74. The
  75. \fIpthread_getspecific\fR()
  76. function shall return the thread-specific data value associated
  77. with the given
  78. .IR key .
  79. If no thread-specific data value is associated with
  80. .IR key ,
  81. then the value NULL shall be returned.
  82. .P
  83. If successful, the
  84. \fIpthread_setspecific\fR()
  85. function shall return zero; otherwise, an error number shall be
  86. returned to indicate the error.
  87. .SH ERRORS
  88. No errors are returned from
  89. \fIpthread_getspecific\fR().
  90. .P
  91. The
  92. \fIpthread_setspecific\fR()
  93. function shall fail if:
  94. .TP
  95. .BR ENOMEM
  96. Insufficient memory exists to associate the non-NULL value with the key.
  97. .P
  98. The
  99. \fIpthread_setspecific\fR()
  100. function shall not return an error code of
  101. .BR [EINTR] .
  102. .LP
  103. .IR "The following sections are informative."
  104. .SH EXAMPLES
  105. None.
  106. .SH "APPLICATION USAGE"
  107. None.
  108. .SH RATIONALE
  109. Performance and ease-of-use of
  110. \fIpthread_getspecific\fR()
  111. are critical for functions that rely on maintaining state in
  112. thread-specific data. Since no errors are required to be detected by
  113. it, and since the only error that could be detected is the use of an
  114. invalid key, the function to
  115. \fIpthread_getspecific\fR()
  116. has been designed to favor speed and simplicity over error reporting.
  117. .P
  118. If an implementation detects that the value specified by the
  119. .IR key
  120. argument to
  121. \fIpthread_setspecific\fR()
  122. does not refer to a a key value obtained from
  123. \fIpthread_key_create\fR()
  124. or refers to a key that has been deleted with
  125. \fIpthread_key_delete\fR(),
  126. it is recommended that the function should fail and report an
  127. .BR [EINVAL] 
  128. error.
  129. .SH "FUTURE DIRECTIONS"
  130. None.
  131. .SH "SEE ALSO"
  132. .IR "\fIpthread_key_create\fR\^(\|)"
  133. .P
  134. The Base Definitions volume of POSIX.1\(hy2017,
  135. .IR "\fB<pthread.h>\fP"
  136. .\"
  137. .SH COPYRIGHT
  138. Portions of this text are reprinted and reproduced in electronic form
  139. from IEEE Std 1003.1-2017, Standard for Information Technology
  140. -- Portable Operating System Interface (POSIX), The Open Group Base
  141. Specifications Issue 7, 2018 Edition,
  142. Copyright (C) 2018 by the Institute of
  143. Electrical and Electronics Engineers, Inc and The Open Group.
  144. In the event of any discrepancy between this version and the original IEEE and
  145. The Open Group Standard, the original IEEE and The Open Group Standard
  146. is the referee document. The original Standard can be obtained online at
  147. http://www.opengroup.org/unix/online.html .
  148. .PP
  149. Any typographical or formatting errors that appear
  150. in this page are most likely
  151. to have been introduced during the conversion of the source files to
  152. man page format. To report such errors, see
  153. https://www.kernel.org/doc/man-pages/reporting_bugs.html .