1.\" $NetBSD: pthread_key_create.3,v 1.8 2015/05/29 18:00:51 wiz Exp $ 2.\" 3.\" Copyright (c) 2002, 2010 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_create.3,v 1.12 2002/09/16 19:29:28 mini Exp $ 57.\" 58.Dd May 29, 2015 59.Dt PTHREAD_KEY_CREATE 3 60.Os 61.Sh NAME 62.Nm pthread_key_create 63.Nd thread-specific data 64.Sh LIBRARY 65.Lb libpthread 66.Sh SYNOPSIS 67.In pthread.h 68.Ft int 69.Fn pthread_key_create "pthread_key_t *key" "void (*destructor)(void *)" 70.Ft int 71.Fn pthread_key_delete "pthread_key_t key" 72.Sh DESCRIPTION 73The 74.Fn pthread_key_create 75function creates a thread-specific data key visible to all threads in the 76process. 77Key values are opaque objects used to locate thread-specific data. 78The same key value may be used by different threads, 79but the values bound to the key by 80.Fn pthread_setspecific 81are maintained on a per-thread basis and 82persist for the life of the calling thread. 83.Pp 84Upon key creation, the value 85.Dv NULL 86is associated with the new key in all active threads. 87Upon thread creation, the value 88.Dv NULL 89is associated with all 90defined keys in the new thread. 91.Pp 92An optional destructor function may be associated with each key value. 93At thread exit, if a key value has a 94.Pf non- Dv NULL 95destructor pointer, and the thread has a 96.Pf non- Dv NULL 97value associated with the key, the function pointed 98to is called with the current associated value as its sole argument. 99The order of destructor calls is unspecified if more 100than one destructor exists for a thread when it exits. 101.Pp 102If, after all the destructors have been called for all 103.Pf non- Dv NULL 104values with associated destructors, there are still some 105.Pf non- Dv NULL 106values with associated destructors, then the process is repeated. 107If, after at least 108.Dv PTHREAD_DESTRUCTOR_ITERATIONS 109iterations of destructor calls for outstanding 110.Pf non- Dv NULL 111values, there are still some 112.Pf non- Dv NULL 113values with 114associated destructors, the implementation stops calling destructors. 115.Pp 116The 117.Fn pthread_key_delete 118function deletes a thread-specific data key previously returned by 119.Fn pthread_key_create . 120The thread-specific data values associated with 121.Fa key 122need not be 123.Dv NULL 124at the time of the call. 125It is the responsibility of the application to free any 126application storage or perform any cleanup actions for data structures 127related to the deleted key or associated thread-specific data in any threads; 128this cleanup can be done either before or after 129.Fn pthread_key_delete 130is called. 131Any attempt to use 132.Fa key 133following the call to 134.Fn pthread_key_delete 135results in undefined behavior. 136.Pp 137The 138.Fn pthread_key_delete 139function itself is callable from within destructor functions, 140but destructor functions are not invoked by the function. 141Any destructor function that may have been associated with 142.Fa key 143will no longer be called upon thread exit. 144.Sh RETURN VALUES 145If successful, the 146.Fn pthread_key_create 147function will store the newly created key value at the location specified by 148.Fa key 149and returns zero. 150Also 151.Fn pthread_key_delete 152will return zero upon success. 153Upon failure both functions return an error number to indicate the cause. 154.Sh ENVIRONMENT 155.Bl -tag -width PTHREAD_KEYS_MAX 156.It Ev PTHREAD_KEYS_MAX 157Maximum per-process thread-specific data keys. 158This cannot be set below 159.Dv _POSIX_THREAD_KEYS_MAX . 160.El 161.Sh ERRORS 162The 163.Fn pthread_key_create 164may fail if: 165.Bl -tag -width Er 166.It Bq Er EAGAIN 167The system lacked the necessary resources to create another thread-specific 168data key, or the system-imposed limit on the total number of keys per-process 169.Dv PTHREAD_KEYS_MAX 170would be exceeded. 171.It Bq Er ENOMEM 172Insufficient memory exists to create the key. 173.El 174.Pp 175The 176.Fn pthread_key_delete 177function may fail if: 178.Bl -tag -width Er 179.It Bq Er EINVAL 180The 181.Fa key 182value is invalid. 183.El 184.Sh SEE ALSO 185.Xr pthread_getspecific 3 186.Sh STANDARDS 187These functions conform to 188.St -p1003.1-2001 . 189.Sh BUGS 190The current specifications are flawed and 191do not permit a clean implementation without potential problems. 192The current implementation in 193.Nx 194addresses these problems by not supporting key reuse. 195