1.\" $NetBSD: pthread_getspecific.3,v 1.5 2010/07/09 10:49:48 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_getspecific.3,v 1.11 2002/09/16 19:29:28 mini Exp $ 57.\" 58.Dd July 9, 2010 59.Dt PTHREAD_GETSPECIFIC 3 60.Os 61.Sh NAME 62.Nm pthread_getspecific 63.Nd thread-specific data value 64.Sh LIBRARY 65.Lb libpthread 66.Sh SYNOPSIS 67.In pthread.h 68.Ft void * 69.Fn pthread_getspecific "pthread_key_t key" 70.Ft int 71.Fn pthread_setspecific "pthread_key_t key" "const void *value" 72.Sh DESCRIPTION 73The 74.Fn pthread_getspecific 75function returns the value currently bound to the specified 76.Fa key 77on behalf of the calling thread. 78Conversely, the 79.Fn pthread_setspecific 80function associates a thread-specific value with a 81.Fa key 82obtained via a previous call to 83.Xr pthread_key_create 3 . 84Different threads have different values bound to each key. 85These values are typically pointers to blocks of dynamically 86allocated memory that have been reserved for use by the calling thread. 87.Pp 88Undefined behavior may follow if either function is called with a 89.Fa key 90value not obtained from 91.Xr pthread_key_create 3 , 92or if the call is made after 93.Fa key 94has been deleted with 95.Xr pthread_key_delete 3 . 96It is possible to call either function from 97a thread-specific data destructor function. 98Note however that this is not well defined for the 99.Fn pthread_setspecific 100function; 101lost storage or infinite loops may occur. 102.Sh RETURN VALUES 103The 104.Fn pthread_getspecific 105function will return the thread-specific data value associated with the given 106.Fa key . 107If no thread-specific data value is associated with 108.Fa key , 109then the value 110.Dv NULL 111is returned. 112If successful, the 113.Fn pthread_setspecific 114function will return zero. 115Otherwise an error number will be returned to 116indicate the error. 117.Sh ERRORS 118No errors are defined for either function. 119.Sh SEE ALSO 120.Xr pthread_key_create 3 121.Sh STANDARDS 122These functions conform to 123.St -p1003.1-2001 . 124