diff options
Diffstat (limited to 'man3p/pthread_getspecific.3p')
| -rw-r--r-- | man3p/pthread_getspecific.3p | 109 |
1 files changed, 109 insertions, 0 deletions
diff --git a/man3p/pthread_getspecific.3p b/man3p/pthread_getspecific.3p new file mode 100644 index 000000000..d0408a15e --- /dev/null +++ b/man3p/pthread_getspecific.3p @@ -0,0 +1,109 @@ +.\" 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 . |