summaryrefslogtreecommitdiffstats
path: root/posix_users/key.rst
blob: 5b16ddbd88105d8fd03a9d59e8ed43c0fe70e60c (plain) (blame)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
.. comment SPDX-License-Identifier: CC-BY-SA-4.0

.. COMMENT: COPYRIGHT (c) 1988-2002.
.. COMMENT: On-Line Applications Research Corporation (OAR).
.. COMMENT: All rights reserved.

Key Manager
###########

Introduction
============

The key manager allows for the creation and deletion of Data keys
specific to threads.

The directives provided by the key manager are:

- pthread_key_create_ - Create Thread Specific Data Key

- pthread_key_delete_ - Delete Thread Specific Data Key

- pthread_setspecific_ - Set Thread Specific Key Value

- pthread_getspecific_ - Get Thread Specific Key Value

Background
==========

There is currently no text in this section.

Operations
==========

There is currently no text in this section.

Directives
==========

This section details the key manager's directives.  A subsection is dedicated
to each of this manager's directives and describes the calling sequence,
related constants, usage, and status codes.

.. _pthread_key_create:

pthread_key_create - Create Thread Specific Data Key
----------------------------------------------------

**CALLING SEQUENCE:**

.. code-block:: c

    #include <pthread.h>
    int pthread_key_create(
        pthread_key_t *key,
        void (*destructor)( void )
    );

**STATUS CODES:**

.. list-table::
 :class: rtems-table

 * - ``EAGAIN``
   - There were not enough resources available to create another key.
 * - ``ENOMEM``
   - Insufficient memory exists to create the key.

**DESCRIPTION**

The ``pthread_key_create()`` function shall create a thread-specific data key
visible to all threads in the process. Key values provided by
``pthread_key_create()`` are opaque objects used to locate thread-specific
data. Although the same key value may be used by different threads, the values
bound to the key by ``pthread_setspecific()`` are maintained on a per-thread
basis and persist for the life of the calling thread.

Upon key creation, the value ``NULL`` shall be associated with the new key in
all active threads. Upon thread creation, the value ``NULL`` shall be
associated with all defined keys in the new thread.

**NOTES**

An optional destructor function may be associated with each key value.  At
thread exit, if a key value has a non-``NULL`` destructor pointer, and the
thread has a non-``NULL`` value associated with that key, the value of the key
is set to NULL, and then the function pointed to is called with the previously
associated value as its sole argument. The order of destructor calls is
unspecified if more than one destructor exists for a thread when it exits.

.. _pthread_key_delete:

pthread_key_delete - Delete Thread Specific Data Key
----------------------------------------------------

**CALLING SEQUENCE:**

.. code-block:: c

    #include <pthread.h>
    int pthread_key_delete(
        pthread_key_t key
    );

**STATUS CODES:**

.. list-table::
 :class: rtems-table

 * - ``EINVAL``
   - The key was invalid

**DESCRIPTION:**

The ``pthread_key_delete()`` function shall delete a thread-specific data key
previously returned by ``pthread_key_create()``. The thread-specific data
values associated with key need not be NULL at the time
``pthread_key_delete()`` is called. It is the responsibility of the application
to free any application storage or perform any cleanup actions for data
structures related to the deleted key or associated thread-specific data in any
threads; this cleanup can be done either before or after
``pthread_key_delete()`` is called. Any attempt to use key following the call
to ``pthread_key_delete()`` results in undefined behavior.

**NOTES:**

The ``pthread_key_delete()`` function shall be callable from within destructor
functions. No destructor functions shall be invoked by
``pthread_key_delete()``. Any destructor function that may have been associated
with key shall no longer be called upon thread exit.

.. _pthread_setspecific:

pthread_setspecific - Set Thread Specific Key Value
---------------------------------------------------

**CALLING SEQUENCE:**

.. code-block:: c

    #include <pthread.h>
    int pthread_setspecific(
        pthread_key_t  key,
        const void    *value
    );

**STATUS CODES:**

.. list-table::
 :class: rtems-table

 * - ``EINVAL``
   - The specified key is invalid.

**DESCRIPTION:**

The ``pthread_setspecific()`` function shall associate a thread-specific value
with a key obtained via a previous call to ``pthread_key_create()``.  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.

**NOTES:**

The effect of calling ``pthread_setspecific()`` with a key value not obtained
from ``pthread_key_create()`` or after key has been deleted with
``pthread_key_delete()`` is undefined.

``pthread_setspecific()`` may be called from a thread-specific data destructor
function. Calling ``pthread_setspecific()`` 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.

.. _pthread_getspecific:

pthread_getspecific - Get Thread Specific Key Value
---------------------------------------------------

**CALLING SEQUENCE:**

.. code-block:: c

    #include <pthread.h>
    void *pthread_getspecific(
        pthread_key_t key
    );

**STATUS CODES:**

.. list-table::
 :class: rtems-table

 * - ``NULL``
   - There is no thread-specific data associated with the specified key.
 * - ``non-NULL``
   - The data associated with the specified key.

**DESCRIPTION:**

The ``pthread_getspecific()`` function shall return the value currently bound
to the specified key on behalf of the calling thread.

**NOTES:**

The effect of calling ``pthread_getspecific()`` with a key value not obtained
from ``pthread_key_create()`` or after key has been deleted with
``pthread_key_delete()`` is undefined.

``pthread_getspecific()`` may be called from a thread-specific data destructor
function. A call to ``pthread_getspecific()`` 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 ``pthread_setspecific()``.