1*86f9d4cdStedu.\" $OpenBSD: pthread_key_create.3,v 1.9 2013/06/05 03:44:50 tedu Exp $ 282d2d131Sfgsch.\" 3a278733dSd.\" Copyright (c) 1996 John Birrell <jb@cimlogic.com.au>. 4a278733dSd.\" All rights reserved. 5a278733dSd.\" 6a278733dSd.\" Redistribution and use in source and binary forms, with or without 7a278733dSd.\" modification, are permitted provided that the following conditions 8a278733dSd.\" are met: 9a278733dSd.\" 1. Redistributions of source code must retain the above copyright 10a278733dSd.\" notice, this list of conditions and the following disclaimer. 11a278733dSd.\" 2. Redistributions in binary form must reproduce the above copyright 12a278733dSd.\" notice, this list of conditions and the following disclaimer in the 13a278733dSd.\" documentation and/or other materials provided with the distribution. 14a278733dSd.\" 3. All advertising materials mentioning features or use of this software 15a278733dSd.\" must display the following acknowledgement: 16a278733dSd.\" This product includes software developed by John Birrell. 17a278733dSd.\" 4. Neither the name of the author nor the names of any co-contributors 18a278733dSd.\" may be used to endorse or promote products derived from this software 19a278733dSd.\" without specific prior written permission. 20a278733dSd.\" 21a278733dSd.\" THIS SOFTWARE IS PROVIDED BY JOHN BIRRELL AND CONTRIBUTORS ``AS IS'' AND 22a278733dSd.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 23a278733dSd.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 24a278733dSd.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE 25a278733dSd.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 26a278733dSd.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 27a278733dSd.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 28a278733dSd.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 29a278733dSd.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 30a278733dSd.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 31a278733dSd.\" SUCH DAMAGE. 32a278733dSd.\" 3374493c91Sd.\" $FreeBSD: pthread_key_create.3,v 1.5 1999/08/28 00:03:06 peter Exp $ 3474493c91Sd.\" 35*86f9d4cdStedu.Dd $Mdocdate: June 5 2013 $ 36a278733dSd.Dt PTHREAD_KEY_CREATE 3 37c043c0f7Sd.Os 38a278733dSd.Sh NAME 39a278733dSd.Nm pthread_key_create 40a278733dSd.Nd thread-specific data key creation 41a278733dSd.Sh SYNOPSIS 42*86f9d4cdStedu.In pthread.h 43a278733dSd.Ft int 44a278733dSd.Fn pthread_key_create "pthread_key_t *key" "void (*destructor)(void *)" 45a278733dSd.Sh DESCRIPTION 46a278733dSdThe 47a278733dSd.Fn pthread_key_create 48a278733dSdfunction creates a thread-specific data key visible to all threads in the 49ee997aeaSmpechprocess. 50ee997aeaSmpechKey values provided by 51a278733dSd.Fn pthread_key_create 52ee997aeaSmpechare opaque objects used to locate thread-specific data. 53ee997aeaSmpechAlthough the same 54a278733dSdkey value may be used by different threads, the values bound to the key 55a278733dSdby 56a278733dSd.Fn pthread_setspecific 57a278733dSdare maintained on a per-thread basis and persist for the life of the calling 58a278733dSdthread. 59a278733dSd.Pp 60a278733dSdUpon key creation, the value NULL is associated with the new key in all 61ee997aeaSmpechactive threads. 62ee997aeaSmpechUpon thread creation, the value NULL is associated with all 63a278733dSddefined keys in the new thread. 64a278733dSd.Pp 65ee997aeaSmpechAn optional destructor function may be associated with each key value. 66ee997aeaSmpechAt thread exit, if a key value has a non-NULL destructor pointer, and the 67a278733dSdthread has a non-NULL value associated with the key, the function pointed 68ee997aeaSmpechto is called with the current associated value as its sole argument. 69ee997aeaSmpechThe order of destructor calls is unspecified if more than one destructor exists 70a278733dSdfor a thread when it exits. 71a278733dSd.Pp 72a278733dSdIf, after all the destructors have been called for all non-NULL values 73a278733dSdwith associated destructors, there are still some non-NULL values with 74ee997aeaSmpechassociated destructors, then the process is repeated. 75ee997aeaSmpechIf, after at least 76a278733dSd[PTHREAD_DESTRUCTOR_ITERATIONS] iterations of destructor calls for 77a278733dSdoutstanding non-NULL values, there are still some non-NULL values with 78a278733dSdassociated destructors, the implementation stops calling destructors. 79a278733dSd.Sh RETURN VALUES 80a278733dSdIf successful, the 81a278733dSd.Fn pthread_key_create 82a278733dSdfunction will store the newly created key value at the location specified by 83a278733dSd.Fa key 84ee997aeaSmpechand returns zero. 85ee997aeaSmpechOtherwise an error number will be returned to indicate the error. 86a278733dSd.Sh ERRORS 87a278733dSd.Fn pthread_key_create 88a278733dSdwill fail if: 89a278733dSd.Bl -tag -width Er 90a278733dSd.It Bq Er EAGAIN 91a278733dSdThe system lacked the necessary resources to create another thread-specific 92a278733dSddata key, or the system-imposed limit on the total number of keys per process 93a278733dSd[PTHREAD_KEYS_MAX] would be exceeded. 94a278733dSd.It Bq Er ENOMEM 95a278733dSdInsufficient memory exists to create the key. 96a278733dSd.El 97a278733dSd.Sh SEE ALSO 98a278733dSd.Xr pthread_getspecific 3 , 99a278733dSd.Xr pthread_key_delete 3 , 100a278733dSd.Xr pthread_setspecific 3 101a278733dSd.Sh STANDARDS 102a278733dSd.Fn pthread_key_create 10382d2d131Sfgschconforms to 10482d2d131Sfgsch.St -p1003.1-96 . 105