[apple/libc.git] / pthreads / pthread_setspecific.3

.\" Copyright (c) 1996 John Birrell <jb@cimlogic.com.au>.
.\" All rights reserved.
.\"
.\" Redistribution and use in source and binary forms, with or without
.\" modification, are permitted provided that the following conditions
.\" are met:
.\" 1. Redistributions of source code must retain the above copyright
.\"    notice, this list of conditions and the following disclaimer.
.\" 2. Redistributions in binary form must reproduce the above copyright
.\"    notice, this list of conditions and the following disclaimer in the
.\"    documentation and/or other materials provided with the distribution.
.\" 3. All advertising materials mentioning features or use of this software
.\"    must display the following acknowledgement:
.\"	This product includes software developed by John Birrell.
.\" 4. Neither the name of the author nor the names of any co-contributors
.\"    may be used to endorse or promote products derived from this software
.\"    without specific prior written permission.
.\"
.\" THIS SOFTWARE IS PROVIDED BY JOHN BIRRELL AND CONTRIBUTORS ``AS IS'' AND
.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
.\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
.\" SUCH DAMAGE.
.\"
.\" $FreeBSD: src/lib/libc_r/man/pthread_setspecific.3,v 1.6.2.4 2001/08/17 15:42:52 ru Exp $
.\"
.Dd April 4, 1996
.Dt PTHREAD_SETSPECIFIC 3
.Os
.Sh NAME
.Nm pthread_setspecific
.Nd set a thread-specific data value
.Sh SYNOPSIS
.Fd #include <pthread.h>
.Ft int
.Fo pthread_setspecific
.Fa "pthread_key_t key"
.Fa "const void *value"
.Fc
.Sh DESCRIPTION
The
.Fn pthread_setspecific
function associates a thread-specific value with a
.Fa key
obtained via a previous call to
.Fn pthread_key_create .
Different threads may bind different values to the same key.
These values are
typically pointers to blocks of dynamically allocated memory that have been
reserved for use by the calling thread.
.Pp
The effect of calling
.Fn pthread_setspecific
with a key value not obtained from
.Fn pthread_key_create ,
or after
.Fa key
has been deleted with
.Fn pthread_key_delete ,
is undefined.
.Pp
.Fn pthread_setspecific
may be called from a thread-specific data destructor function;
however, this may result in lost storage or infinite loops.
.Sh RETURN VALUES
If successful,  the
.Fn pthread_setspecific
function will return zero.
Otherwise, an error number will be returned to indicate the error.
.Sh ERRORS
.Fn pthread_setspecific
will fail if:
.Bl -tag -width Er
.It Bq Er EINVAL
The
.Fa key
value is invalid.
.It Bq Er ENOMEM
Insufficient memory exists to associate the value with the
.Fa key .
.El
.Sh SEE ALSO
.Xr pthread_getspecific 3 ,
.Xr pthread_key_create 3 ,
.Xr pthread_key_delete 3
.Sh STANDARDS
.Fn pthread_setspecific
conforms to
.St -p1003.1-96 .
Commit	Line	Data
5b2abdfb A	1	.\" Copyright (c) 1996 John Birrell <jb@cimlogic.com.au>.
	2	.\" All rights reserved.
	3	.\"
	4	.\" Redistribution and use in source and binary forms, with or without
	5	.\" modification, are permitted provided that the following conditions
	6	.\" are met:
	7	.\" 1. Redistributions of source code must retain the above copyright
	8	.\" notice, this list of conditions and the following disclaimer.
	9	.\" 2. Redistributions in binary form must reproduce the above copyright
	10	.\" notice, this list of conditions and the following disclaimer in the
	11	.\" documentation and/or other materials provided with the distribution.
	12	.\" 3. All advertising materials mentioning features or use of this software
	13	.\" must display the following acknowledgement:
	14	.\" This product includes software developed by John Birrell.
	15	.\" 4. Neither the name of the author nor the names of any co-contributors
	16	.\" may be used to endorse or promote products derived from this software
	17	.\" without specific prior written permission.
	18	.\"
	19	.\" THIS SOFTWARE IS PROVIDED BY JOHN BIRRELL AND CONTRIBUTORS ``AS IS'' AND
	20	.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
	21	.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
	22	.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
	23	.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
	24	.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
	25	.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
	26	.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
	27	.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
	28	.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
	29	.\" SUCH DAMAGE.
	30	.\"
	31	.\" $FreeBSD: src/lib/libc_r/man/pthread_setspecific.3,v 1.6.2.4 2001/08/17 15:42:52 ru Exp $
	32	.\"
	33	.Dd April 4, 1996
	34	.Dt PTHREAD_SETSPECIFIC 3
	35	.Os
	36	.Sh NAME
	37	.Nm pthread_setspecific
	38	.Nd set a thread-specific data value
	39	.Sh SYNOPSIS
	40	.Fd #include <pthread.h>
	41	.Ft int
224c7076 A	42	.Fo pthread_setspecific
	43	.Fa "pthread_key_t key"
	44	.Fa "const void *value"
	45	.Fc
5b2abdfb A	46	.Sh DESCRIPTION
	47	The
	48	.Fn pthread_setspecific
	49	function associates a thread-specific value with a
	50	.Fa key
	51	obtained via a previous call to
	52	.Fn pthread_key_create .
224c7076	53	Different threads may bind different values to the same key.
5b2abdfb A	54	These values are
	55	typically pointers to blocks of dynamically allocated memory that have been
	56	reserved for use by the calling thread.
	57	.Pp
	58	The effect of calling
	59	.Fn pthread_setspecific
	60	with a key value not obtained from
224c7076	61	.Fn pthread_key_create ,
5b2abdfb A	62	or after
	63	.Fa key
	64	has been deleted with
224c7076	65	.Fn pthread_key_delete ,
5b2abdfb A	66	is undefined.
	67	.Pp
	68	.Fn pthread_setspecific
224c7076 A	69	may be called from a thread-specific data destructor function;
224c7076 A	70	however, this may result in lost storage or infinite loops.
5b2abdfb A	71	.Sh RETURN VALUES
	72	If successful, the
	73	.Fn pthread_setspecific
	74	function will return zero.
224c7076	75	Otherwise, an error number will be returned to indicate the error.
5b2abdfb A	76	.Sh ERRORS
	77	.Fn pthread_setspecific
	78	will fail if:
	79	.Bl -tag -width Er
5b2abdfb A	80	.It Bq Er EINVAL
	81	The
	82	.Fa key
	83	value is invalid.
224c7076 A	84	.It Bq Er ENOMEM
	85	Insufficient memory exists to associate the value with the
	86	.Fa key .
5b2abdfb A	87	.El
	88	.Sh SEE ALSO
	89	.Xr pthread_getspecific 3 ,
	90	.Xr pthread_key_create 3 ,
	91	.Xr pthread_key_delete 3
	92	.Sh STANDARDS
	93	.Fn pthread_setspecific
	94	conforms to
	95	.St -p1003.1-96 .