.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved 
.TH "PTHREAD_GETSPECIFIC" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual"
.\" pthread_getspecific 
.SH NAME
pthread_getspecific, pthread_setspecific \- thread-specific data management
.SH SYNOPSIS
.LP
\fB#include <pthread.h>
.br
.sp
void *pthread_getspecific(pthread_key_t\fP \fIkey\fP\fB);
.br
int pthread_setspecific(pthread_key_t\fP \fIkey\fP\fB, const void
*\fP\fIvalue\fP\fB); \fP
\fB
.br
\fP
.SH DESCRIPTION
.LP
The \fIpthread_getspecific\fP() function shall return the value currently
bound to the specified \fIkey\fP on behalf of the
calling thread.
.LP
The \fIpthread_setspecific\fP() function shall associate a thread-specific
\fIvalue\fP with a \fIkey\fP obtained via a
previous call to \fIpthread_key_create\fP(). 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.
.LP
The effect of calling \fIpthread_getspecific\fP() or \fIpthread_setspecific\fP()
with a \fIkey\fP value not obtained from \fIpthread_key_create\fP()
or after \fIkey\fP has been deleted with \fIpthread_key_delete\fP()
is undefined.
.LP
Both \fIpthread_getspecific\fP() and \fIpthread_setspecific\fP() may
be called from a thread-specific data destructor
function. A call to \fIpthread_getspecific\fP() for the thread-specific
data key being destroyed shall return the value NULL,
unless the value is changed (after the destructor starts) by a call
to \fIpthread_setspecific\fP(). Calling
\fIpthread_setspecific\fP() from a thread-specific data destructor
routine may result either in lost storage (after at least
PTHREAD_DESTRUCTOR_ITERATIONS attempts at destruction) or in an infinite
loop.
.LP
Both functions may be implemented as macros.
.SH RETURN VALUE
.LP
The \fIpthread_getspecific\fP() function shall return the thread-specific
data value associated with the given \fIkey\fP. If
no thread-specific data value is associated with \fIkey\fP, then the
value NULL shall be returned.
.LP
If successful, the \fIpthread_setspecific\fP() function shall return
zero; otherwise, an error number shall be returned to
indicate the error.
.SH ERRORS
.LP
No errors are returned from \fIpthread_getspecific\fP().
.LP
The \fIpthread_setspecific\fP() function shall fail if:
.TP 7
.B ENOMEM
Insufficient memory exists to associate the value with the key.
.sp
.LP
The \fIpthread_setspecific\fP() function may fail if:
.TP 7
.B EINVAL
The key value is invalid.
.sp
.LP
These functions shall not return an error code of [EINTR].
.LP
\fIThe following sections are informative.\fP
.SH EXAMPLES
.LP
None.
.SH APPLICATION USAGE
.LP
None.
.SH RATIONALE
.LP
Performance and ease-of-use of \fIpthread_getspecific\fP() are critical
for functions that rely on maintaining state in
thread-specific data. Since no errors are required to be detected
by it, and since the only error that could be detected is the use
of an invalid key, the function to \fIpthread_getspecific\fP() has
been designed to favor speed and simplicity over error
reporting.
.SH FUTURE DIRECTIONS
.LP
None.
.SH SEE ALSO
.LP
\fIpthread_key_create\fP() , the Base Definitions volume of
IEEE\ Std\ 1003.1-2001, \fI<pthread.h>\fP
.SH COPYRIGHT
Portions of this text are reprinted and reproduced in electronic form
from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology
-- Portable Operating System Interface (POSIX), The Open Group Base
Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of
Electrical and Electronics Engineers, Inc and The Open Group. In the
event of any discrepancy between this version and the original IEEE and
The Open Group Standard, the original IEEE and The Open Group Standard
is the referee document. The original Standard can be obtained online at
http://www.opengroup.org/unix/online.html .