diff options
Diffstat (limited to 'man-pages-posix-2017/man3p/pthread_key_delete.3p')
-rw-r--r-- | man-pages-posix-2017/man3p/pthread_key_delete.3p | 141 |
1 files changed, 141 insertions, 0 deletions
diff --git a/man-pages-posix-2017/man3p/pthread_key_delete.3p b/man-pages-posix-2017/man3p/pthread_key_delete.3p new file mode 100644 index 0000000..6576f7f --- /dev/null +++ b/man-pages-posix-2017/man3p/pthread_key_delete.3p @@ -0,0 +1,141 @@ +'\" et +.TH PTHREAD_KEY_DELETE "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +pthread_key_delete +\(em thread-specific data key deletion +.SH SYNOPSIS +.LP +.nf +#include <pthread.h> +.P +int pthread_key_delete(pthread_key_t \fIkey\fP); +.fi +.SH DESCRIPTION +The +\fIpthread_key_delete\fR() +function shall delete a thread-specific data key previously returned by +\fIpthread_key_create\fR(). +The thread-specific data values associated with +.IR key +need not be NULL at the time +\fIpthread_key_delete\fR() +is called. It is the responsibility of the application to free any +application storage or perform any cleanup actions for data structures +related to the deleted key or associated thread-specific data in any +threads; this cleanup can be done either before or after +\fIpthread_key_delete\fR() +is called. Any attempt to use +.IR key +following the call to +\fIpthread_key_delete\fR() +results in undefined behavior. +.P +The +\fIpthread_key_delete\fR() +function shall be callable from within destructor functions. No +destructor functions shall be invoked by +\fIpthread_key_delete\fR(). +Any destructor function that may have been associated with +.IR key +shall no longer be called upon thread exit. +.SH "RETURN VALUE" +If successful, the +\fIpthread_key_delete\fR() +function shall return zero; otherwise, an error number shall be +returned to indicate the error. +.SH ERRORS +The +\fIpthread_key_delete\fR() +function shall not return an error code of +.BR [EINTR] . +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +A thread-specific data key deletion function has been included in order +to allow the resources associated with an unused thread-specific data +key to be freed. Unused thread-specific data keys can arise, among +other scenarios, when a dynamically loaded module that allocated a key +is unloaded. +.P +Conforming applications are responsible for performing any cleanup +actions needed for data structures associated with the key to be +deleted, including data referenced by thread-specific data values. No +such cleanup is done by +\fIpthread_key_delete\fR(). +In particular, destructor functions are not called. There are several +reasons for this division of responsibility: +.IP " 1." 4 +The associated destructor functions used to free thread-specific data +at thread exit time are only guaranteed to work correctly when called +in the thread that allocated the thread-specific data. (Destructors +themselves may utilize thread-specific data.) Thus, they cannot be used +to free thread-specific data in other threads at key deletion time. +Attempting to have them called by other threads at key deletion time +would require other threads to be asynchronously interrupted. But +since interrupted threads could be in an arbitrary state, including +holding locks necessary for the destructor to run, this approach would +fail. In general, there is no safe mechanism whereby an implementation +could free thread-specific data at key deletion time. +.IP " 2." 4 +Even if there were a means of safely freeing thread-specific data +associated with keys to be deleted, doing so would require that +implementations be able to enumerate the threads with non-NULL data and +potentially keep them from creating more thread-specific data while the +key deletion is occurring. This special case could cause extra +synchronization in the normal case, which would otherwise be +unnecessary. +.P +For an application to know that it is safe to delete a key, it has to +know that all the threads that might potentially ever use the key do +not attempt to use it again. For example, it could know this if all +the client threads have called a cleanup procedure declaring that they +are through with the module that is being shut down, perhaps by setting +a reference count to zero. +.P +If an implementation detects that the value specified by the +.IR key +argument to +\fIpthread_key_delete\fR() +does not refer to a a key value obtained from +\fIpthread_key_create\fR() +or refers to a key that has been deleted with +\fIpthread_key_delete\fR(), +it is recommended that the function should fail and report an +.BR [EINVAL] +error. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIpthread_key_create\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2017, +.IR "\fB<pthread.h>\fP" +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . |