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.

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 .