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



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


NNAAMMEE
       pthread_key_delete -- thread-specific data key deletion

SSYYNNOOPPSSIISS
       #include <pthread.h>

       int pthread_key_delete(pthread_key_t _k_e_y);

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

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

RREETTUURRNN VVAALLUUEE
       If successful, the _p_t_h_r_e_a_d___k_e_y___d_e_l_e_t_e() function shall return zero;
       otherwise, an error number shall be returned to indicate the error.

EERRRROORRSS
       The _p_t_h_r_e_a_d___k_e_y___d_e_l_e_t_e() function shall not return an error code of
       [[EEIINNTTRR]].

       _T_h_e _f_o_l_l_o_w_i_n_g _s_e_c_t_i_o_n_s _a_r_e _i_n_f_o_r_m_a_t_i_v_e_.

EEXXAAMMPPLLEESS
       None.

AAPPPPLLIICCAATTIIOONN UUSSAAGGEE
       None.

RRAATTIIOONNAALLEE
       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 _p_t_h_r_e_a_d___k_e_y___d_e_l_e_t_e().  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 _k_e_y
       argument to _p_t_h_r_e_a_d___k_e_y___d_e_l_e_t_e() does not refer to a a key value
       obtained from _p_t_h_r_e_a_d___k_e_y___c_r_e_a_t_e() or refers to a key that has been
       deleted with _p_t_h_r_e_a_d___k_e_y___d_e_l_e_t_e(), it is recommended that the function
       should fail and report an [[EEIINNVVAALL]] error.

FFUUTTUURREE DDIIRREECCTTIIOONNSS
       None.

SSEEEE AALLSSOO
       _p_t_h_r_e_a_d___k_e_y___c_r_e_a_t_e()

       The Base Definitions volume of POSIX.1-2008, <<pptthhrreeaadd..hh>>

CCOOPPYYRRIIGGHHTT
       Portions of this text are reprinted and reproduced in electronic form
       from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology
       -- Portable Operating System Interface (POSIX), The Open Group Base
       Specifications Issue 7, Copyright (C) 2013 by the Institute of
       Electrical and Electronics Engineers, Inc and The Open Group.  (This is
       POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) 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.unix.org/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                  2013                PTHREAD_KEY_DELETE(3)
