~ubuntu-branches/ubuntu/maverick/manpages-posix/maverick

.\" 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 .