1PTHREAD_GETSPECIFIC(3P)    POSIX Programmer's Manual   PTHREAD_GETSPECIFIC(3P)
2
3
4

PROLOG

6       This  manual  page is part of the POSIX Programmer's Manual.  The Linux
7       implementation of this interface may differ (consult the  corresponding
8       Linux  manual page for details of Linux behavior), or the interface may
9       not be implemented on Linux.
10
11

NAME

13       pthread_getspecific, pthread_setspecific — thread-specific data manage‐
14       ment
15

SYNOPSIS

17       #include <pthread.h>
18
19       void *pthread_getspecific(pthread_key_t key);
20       int pthread_setspecific(pthread_key_t key, const void *value);
21

DESCRIPTION

23       The  pthread_getspecific()  function  shall  return the value currently
24       bound to the specified key on behalf of the calling thread.
25
26       The pthread_setspecific() function shall  associate  a  thread-specific
27       value  with a key obtained via a previous call to pthread_key_create().
28       Different threads may bind different values to the same key. These val‐
29       ues  are  typically  pointers to blocks of dynamically allocated memory
30       that have been reserved for use by the calling thread.
31
32       The effect of calling  pthread_getspecific()  or  pthread_setspecific()
33       with  a  key  value not obtained from pthread_key_create() or after key
34       has been deleted with pthread_key_delete() is undefined.
35
36       Both pthread_getspecific() and pthread_setspecific() may be called from
37       a  thread-specific  data destructor function. A call to pthread_getspe‐
38       cific() for the thread-specific data key being destroyed  shall  return
39       the  value  NULL,  unless  the  value  is changed (after the destructor
40       starts) by a call to  pthread_setspecific().   Calling  pthread_setspe‐
41       cific()  from  a  thread-specific  data  destructor  routine may result
42       either in lost storage (after  at  least  PTHREAD_DESTRUCTOR_ITERATIONS
43       attempts at destruction) or in an infinite loop.
44
45       Both functions may be implemented as macros.
46

RETURN VALUE

48       The  pthread_getspecific()  function  shall  return the thread-specific
49       data value associated with the given key.  If no  thread-specific  data
50       value is associated with key, then the value NULL shall be returned.
51
52       If  successful,  the  pthread_setspecific() function shall return zero;
53       otherwise, an error number shall be returned to indicate the error.
54

ERRORS

56       No errors are returned from pthread_getspecific().
57
58       The pthread_setspecific() function shall fail if:
59
60       ENOMEM Insufficient memory exists to associate the non-NULL value  with
61              the key.
62
63       The  pthread_setspecific()  function  shall not return an error code of
64       [EINTR].
65
66       The following sections are informative.
67

EXAMPLES

69       None.
70

APPLICATION USAGE

72       None.
73

RATIONALE

75       Performance and ease-of-use of pthread_getspecific() are  critical  for
76       functions that rely on maintaining state in thread-specific data. Since
77       no errors are required to be detected by it, and since the  only  error
78       that  could  be  detected is the use of an invalid key, the function to
79       pthread_getspecific() has been designed to favor speed  and  simplicity
80       over error reporting.
81
82       If  an implementation detects that the value specified by the key argu‐
83       ment to pthread_setspecific() does not refer to a a key value  obtained
84       from pthread_key_create() or refers to a key that has been deleted with
85       pthread_key_delete(), it is recommended that the function  should  fail
86       and report an [EINVAL] error.
87

FUTURE DIRECTIONS

89       None.
90

SEE ALSO

92       pthread_key_create()
93
94       The Base Definitions volume of POSIX.1‐2008, <pthread.h>
95
97       Portions  of  this text are reprinted and reproduced in electronic form
98       from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology
99       --  Portable  Operating  System  Interface (POSIX), The Open Group Base
100       Specifications Issue 7, Copyright (C) 2013 by the Institute of Electri‐
101       cal  and  Electronics  Engineers,  Inc  and  The  Open Group.  (This is
102       POSIX.1-2008 with the 2013 Technical Corrigendum  1  applied.)  In  the
103       event of any discrepancy between this version and the original IEEE and
104       The Open Group Standard, the original IEEE and The Open Group  Standard
105       is  the  referee document. The original Standard can be obtained online
106       at http://www.unix.org/online.html .
107
108       Any typographical or formatting errors that appear  in  this  page  are
109       most likely to have been introduced during the conversion of the source
110       files to man page format. To report such errors,  see  https://www.ker
111       nel.org/doc/man-pages/reporting_bugs.html .
112
113
114
115IEEE/The Open Group                  2013              PTHREAD_GETSPECIFIC(3P)
Impressum