lib/libpthread/pthread_key_delete.3

   1 .\" $NetBSD: pthread_key_delete.3,v 1.5 2005/06/17 18:26:53 wiz Exp $
   2 .\"
   3 .\" Copyright (c) 2002 The NetBSD Foundation, Inc.
   4 .\" All rights reserved.
   5 .\" Redistribution and use in source and binary forms, with or without
   6 .\" modification, are permitted provided that the following conditions
   7 .\" are met:
   8 .\" 1. Redistributions of source code must retain the above copyright
   9 .\"    notice, this list of conditions and the following disclaimer.
  10 .\" 2. Redistributions in binary form must reproduce the above copyright
  11 .\"    notice, this list of conditions and the following disclaimer in the
  12 .\"    documentation and/or other materials provided with the distribution.
  13 .\"
  14 .\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS
  15 .\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
  16 .\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
  17 .\" PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS
  18 .\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
  19 .\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
  20 .\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
  21 .\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
  22 .\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
  23 .\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
  24 .\" POSSIBILITY OF SUCH DAMAGE.
  25 .\"
  26 .\" Copyright (c) 1996 John Birrell <jb@cimlogic.com.au>.
  27 .\" All rights reserved.
  28 .\"
  29 .\" Redistribution and use in source and binary forms, with or without
  30 .\" modification, are permitted provided that the following conditions
  31 .\" are met:
  32 .\" 1. Redistributions of source code must retain the above copyright
  33 .\"    notice, this list of conditions and the following disclaimer.
  34 .\" 2. Redistributions in binary form must reproduce the above copyright
  35 .\"    notice, this list of conditions and the following disclaimer in the
  36 .\"    documentation and/or other materials provided with the distribution.
  37 .\" 3. All advertising materials mentioning features or use of this software
  38 .\"    must display the following acknowledgement:
  39 .\"     This product includes software developed by John Birrell.
  40 .\" 4. Neither the name of the author nor the names of any co-contributors
  41 .\"    may be used to endorse or promote products derived from this software
  42 .\"    without specific prior written permission.
  43 .\"
  44 .\" THIS SOFTWARE IS PROVIDED BY JOHN BIRRELL AND CONTRIBUTORS ``AS IS'' AND
  45 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  46 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  47 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
  48 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  49 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  50 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  51 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  52 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  53 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  54 .\" SUCH DAMAGE.
  55 .\"
  56 .\" $FreeBSD: src/lib/libpthread/man/pthread_key_delete.3,v 1.12 2002/09/16 19:29:28 mini Exp $
  57 .\"
  58 .Dd January 30, 2003
  59 .Dt PTHREAD_KEY_DELETE 3
  60 .Os
  61 .Sh NAME
  62 .Nm pthread_key_delete
  63 .Nd delete a thread-specific data key
  64 .Sh LIBRARY
  65 .Lb libpthread
  66 .Sh SYNOPSIS
  67 .In pthread.h
  68 .Ft int
  69 .Fn pthread_key_delete "pthread_key_t key"
  70 .Sh DESCRIPTION
  71 The
  72 .Fn pthread_key_delete
  73 function deletes a thread-specific data key previously returned by
  74 .Fn pthread_key_create .
  75 The thread-specific data values associated with
  76 .Fa key
  77 need not be NULL at the time that
  78 .Fn pthread_key_delete
  79 is called.
  80 It is the responsibility of the application to free any
  81 application storage or perform any cleanup actions for data structures
  82 related to the deleted key or associated thread-specific data in any threads;
  83 this cleanup can be done either before or after
  84 .Fn pthread_key_delete
  85 is called.
  86 Any attempt to use
  87 .Fa key
  88 following the call to
  89 .Fn pthread_key_delete
  90 results in undefined behavior.
  91 .Pp
  92 The
  93 .Fn pthread_key_delete
  94 function is callable from within destructor functions.
  95 Destructor functions
  96 are not invoked by
  97 .Fn pthread_key_delete .
  98 Any destructor function that may have been associated with
  99 .Fa key
 100 will no longer be called upon thread exit.
 101 .Sh RETURN VALUES
 102 If successful, the
 103 .Fn pthread_key_delete
 104 function will return zero.
 105 Otherwise an error number will be returned to
 106 indicate the error.
 107 .Sh ERRORS
 108 .Fn pthread_key_delete
 109 may fail if:
 110 .Bl -tag -width Er
 111 .It Bq Er EINVAL
 112 The
 113 .Fa key
 114 value is invalid.
 115 .El
 116 .Sh SEE ALSO
 117 .Xr pthread_getspecific 3 ,
 118 .Xr pthread_key_create 3 ,
 119 .Xr pthread_setspecific 3
 120 .Sh STANDARDS
 121 .Fn pthread_key_delete
 122 conforms to
 123 .St -p1003.1-96 .
 124 .Sh BUGS
 125 The current specifications of
 126 .Fn pthread_key_create
 127 and
 128 .Fn pthread_key_delete
 129 are flawed and do not permit a clean implementation without
 130 potential problems.
 131 The current implementation of these functions
 132 .Nx
 133 in addresses these problems by not supporting key reuse.