mirror of https://github.com/mkerrisk/man-pages
115 lines
4.0 KiB
Plaintext
115 lines
4.0 KiB
Plaintext
.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved
|
|
.TH "PTHREAD_GETSPECIFIC" 3P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual"
|
|
.\" pthread_getspecific
|
|
.SH PROLOG
|
|
This manual page is part of the POSIX Programmer's Manual.
|
|
The Linux implementation of this interface may differ (consult
|
|
the corresponding Linux manual page for details of Linux behavior),
|
|
or the interface may not be implemented on Linux.
|
|
.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 .
|