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