pthread_key_delete

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 appli-
       cation  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 asso-
       ciated 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
           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-spe-
           cific 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 .



IEEE/The Open Group                  2003                PTHREAD_KEY_DELETE(P)