1.\" $NetBSD: pthread_key_create.3,v 1.4 2008/05/02 18:11:04 martin 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_create.3,v 1.12 2002/09/16 19:29:28 mini Exp $ 57.\" 58.Dd January 30, 2003 59.Dt PTHREAD_KEY_CREATE 3 60.Os 61.Sh NAME 62.Nm pthread_key_create 63.Nd thread-specific data key creation 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.Sh DESCRIPTION 71The 72.Fn pthread_key_create 73function creates a thread-specific data key visible to all threads in the 74process. 75Key values provided by 76.Fn pthread_key_create 77are opaque objects used to locate thread-specific data. 78Although the same 79key value may be used by different threads, the values bound to the key 80by 81.Fn pthread_setspecific 82are maintained on a per-thread basis and persist for the life of the calling 83thread. 84.Pp 85Upon key creation, the value NULL is associated with the new key in all 86active threads. 87Upon thread creation, the value NULL is associated with all 88defined keys in the new thread. 89.Pp 90An optional destructor function may be associated with each key value. 91At 92thread exit, if a key value has a non-NULL destructor pointer, and the 93thread has a non-NULL value associated with the key, the function pointed 94to is called with the current associated value as its sole argument. 95The 96order of destructor calls is unspecified if more than one destructor exists 97for a thread when it exits. 98.Pp 99If, after all the destructors have been called for all non-NULL values 100with associated destructors, there are still some non-NULL values with 101associated destructors, then the process is repeated. 102If, after at least 103.Dv PTHREAD_DESTRUCTOR_ITERATIONS 104iterations of destructor calls for 105outstanding non-NULL values, there are still some non-NULL values with 106associated destructors, the implementation stops calling destructors. 107.Sh RETURN VALUES 108If successful, the 109.Fn pthread_key_create 110function will store the newly created key value at the location specified by 111.Fa key 112and returns zero. 113Otherwise an error number will be returned to indicate 114the error. 115.Sh ERRORS 116.Fn pthread_key_create 117shall fail if: 118.Bl -tag -width Er 119.It Bq Er EAGAIN 120The system lacked the necessary resources to create another thread-specific 121data key, or the system-imposed limit on the total number of keys per process 122.Dv PTHREAD_KEYS_MAX 123would be exceeded. 124.It Bq Er ENOMEM 125Insufficient memory exists to create the key. 126.El 127.Sh SEE ALSO 128.Xr pthread_getspecific 3 , 129.Xr pthread_key_delete 3 , 130.Xr pthread_setspecific 3 131.Sh STANDARDS 132.Fn pthread_key_create 133conforms to 134.St -p1003.1-96 . 135