PTHREAD_KEY_DELETE(3)      POSIX Programmer's Manual     PTHREAD_KEY_DELETE(3)



PROLOG
       This manual page is part of the POSIX Programmer's Manual.  The OS
       implementation of this interface may differ (consult the corresponding
       OS manual page for details of OS behavior), or the interface may not be
       implemented on OS.

NAME
       pthread_key_delete -- thread-specific data key deletion

SYNOPSIS
       #include <pthread.h>

       int pthread_key_delete(pthread_key_t key);

DESCRIPTION
       The pthread__key__delete() function shall delete a thread-specific data
       key previously returned by pthread__key__create().  The thread-specific
       data values associated with key need not be NULL at the time
       pthread__key__delete() 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 pthread__key__delete() is called. Any attempt to use key
       following the call to pthread__key__delete() results in undefined
       behavior.

       The pthread__key__delete() function shall be callable from within
       destructor functions. No destructor functions shall be invoked by
       pthread__key__delete().  Any destructor function that may have been
       associated with key shall no longer be called upon thread exit.

RETURN VALUE
       If successful, the pthread__key__delete() function shall return zero;
       otherwise, an error number shall be returned to indicate the error.

ERRORS
       The pthread__key__delete() function shall not return an error code of
       [EINTR].

       The following sections are informative.

EXAMPLES
       None.

APPLICATION USAGE
       None.

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.

       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 pthread__key__delete().  In particular,
       destructor functions are not called. There are several reasons for this
       division of responsibility:

        1. 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.

        2. 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.

       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.

       If an implementation detects that the value specified by the key
       argument to pthread__key__delete() does not refer to a a key value
       obtained from pthread__key__create() or refers to a key that has been
       deleted with pthread__key__delete(), it is recommended that the function
       should fail and report an [EINVAL] error.

FUTURE DIRECTIONS
       None.

SEE ALSO
       pthread__key__create()

       The Base Definitions volume of POSIX.1-2017, <pthread.h>

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 .

       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 .



IEEE/The Open Group                  2017                PTHREAD_KEY_DELETE(3)
