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_delete.3p (5439B)


  1. '\" et
  2. .TH PTHREAD_KEY_DELETE "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_delete
  12. \(em thread-specific data key deletion
  13. .SH SYNOPSIS
  14. .LP
  15. .nf
  16. #include <pthread.h>
  17. .P
  18. int pthread_key_delete(pthread_key_t \fIkey\fP);
  19. .fi
  20. .SH DESCRIPTION
  21. The
  22. \fIpthread_key_delete\fR()
  23. function shall delete a thread-specific data key previously returned by
  24. \fIpthread_key_create\fR().
  25. The thread-specific data values associated with
  26. .IR key
  27. need not be NULL at the time
  28. \fIpthread_key_delete\fR()
  29. is called. It is the responsibility of the application to free any
  30. application storage or perform any cleanup actions for data structures
  31. related to the deleted key or associated thread-specific data in any
  32. threads; this cleanup can be done either before or after
  33. \fIpthread_key_delete\fR()
  34. is called. Any attempt to use
  35. .IR key
  36. following the call to
  37. \fIpthread_key_delete\fR()
  38. results in undefined behavior.
  39. .P
  40. The
  41. \fIpthread_key_delete\fR()
  42. function shall be callable from within destructor functions. No
  43. destructor functions shall be invoked by
  44. \fIpthread_key_delete\fR().
  45. Any destructor function that may have been associated with
  46. .IR key
  47. shall no longer be called upon thread exit.
  48. .SH "RETURN VALUE"
  49. If successful, the
  50. \fIpthread_key_delete\fR()
  51. function shall return zero; otherwise, an error number shall be
  52. returned to indicate the error.
  53. .SH ERRORS
  54. The
  55. \fIpthread_key_delete\fR()
  56. function shall not return an error code of
  57. .BR [EINTR] .
  58. .LP
  59. .IR "The following sections are informative."
  60. .SH EXAMPLES
  61. None.
  62. .SH "APPLICATION USAGE"
  63. None.
  64. .SH RATIONALE
  65. A thread-specific data key deletion function has been included in order
  66. to allow the resources associated with an unused thread-specific data
  67. key to be freed. Unused thread-specific data keys can arise, among
  68. other scenarios, when a dynamically loaded module that allocated a key
  69. is unloaded.
  70. .P
  71. Conforming applications are responsible for performing any cleanup
  72. actions needed for data structures associated with the key to be
  73. deleted, including data referenced by thread-specific data values. No
  74. such cleanup is done by
  75. \fIpthread_key_delete\fR().
  76. In particular, destructor functions are not called. There are several
  77. reasons for this division of responsibility:
  78. .IP " 1." 4
  79. The associated destructor functions used to free thread-specific data
  80. at thread exit time are only guaranteed to work correctly when called
  81. in the thread that allocated the thread-specific data. (Destructors
  82. themselves may utilize thread-specific data.) Thus, they cannot be used
  83. to free thread-specific data in other threads at key deletion time.
  84. Attempting to have them called by other threads at key deletion time
  85. would require other threads to be asynchronously interrupted. But
  86. since interrupted threads could be in an arbitrary state, including
  87. holding locks necessary for the destructor to run, this approach would
  88. fail. In general, there is no safe mechanism whereby an implementation
  89. could free thread-specific data at key deletion time.
  90. .IP " 2." 4
  91. Even if there were a means of safely freeing thread-specific data
  92. associated with keys to be deleted, doing so would require that
  93. implementations be able to enumerate the threads with non-NULL data and
  94. potentially keep them from creating more thread-specific data while the
  95. key deletion is occurring. This special case could cause extra
  96. synchronization in the normal case, which would otherwise be
  97. unnecessary.
  98. .P
  99. For an application to know that it is safe to delete a key, it has to
  100. know that all the threads that might potentially ever use the key do
  101. not attempt to use it again. For example, it could know this if all
  102. the client threads have called a cleanup procedure declaring that they
  103. are through with the module that is being shut down, perhaps by setting
  104. a reference count to zero.
  105. .P
  106. If an implementation detects that the value specified by the
  107. .IR key
  108. argument to
  109. \fIpthread_key_delete\fR()
  110. does not refer to a a key value obtained from
  111. \fIpthread_key_create\fR()
  112. or refers to a key that has been deleted with
  113. \fIpthread_key_delete\fR(),
  114. it is recommended that the function should fail and report an
  115. .BR [EINVAL]
  116. error.
  117. .SH "FUTURE DIRECTIONS"
  118. None.
  119. .SH "SEE ALSO"
  120. .IR "\fIpthread_key_create\fR\^(\|)"
  121. .P
  122. The Base Definitions volume of POSIX.1\(hy2017,
  123. .IR "\fB<pthread.h>\fP"
  124. .\"
  125. .SH COPYRIGHT
  126. Portions of this text are reprinted and reproduced in electronic form
  127. from IEEE Std 1003.1-2017, Standard for Information Technology
  128. -- Portable Operating System Interface (POSIX), The Open Group Base
  129. Specifications Issue 7, 2018 Edition,
  130. Copyright (C) 2018 by the Institute of
  131. Electrical and Electronics Engineers, Inc and The Open Group.
  132. In the event of any discrepancy between this version and the original IEEE and
  133. The Open Group Standard, the original IEEE and The Open Group Standard
  134. is the referee document. The original Standard can be obtained online at
  135. http://www.opengroup.org/unix/online.html .
  136. .PP
  137. Any typographical or formatting errors that appear
  138. in this page are most likely
  139. to have been introduced during the conversion of the source files to
  140. man page format. To report such errors, see
  141. https://www.kernel.org/doc/man-pages/reporting_bugs.html .