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 may fail if:

       EINVAL The key value is invalid.

       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.

FUTURE DIRECTIONS

       None.

SEE ALSO

       pthread_key_create() , the Base Definitions volume of IEEE Std 1003.1-2001, <pthread.h>

COPYRIGHT

       Portions of this text are reprinted and reproduced in electronic form from IEEE Std 1003.1, 2003 Edition,
       Standard for Information Technology -- Portable Operating System Interface (POSIX), The Open  Group  Base
       Specifications Issue 6, Copyright (C) 2001-2003 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 .