source: rtems-docs/posix-users/key.rst @ e52906b

5
Last change on this file since e52906b was e52906b, checked in by Sebastian Huber <sebastian.huber@…>, on 01/09/19 at 15:14:06

Simplify SPDX-License-Identifier comment

  • Property mode set to 100644
File size: 6.0 KB
Line 
1.. SPDX-License-Identifier: CC-BY-SA-4.0
2
3.. Copyright (C) 1988, 2002 On-Line Applications Research Corporation (OAR)
4
5Key Manager
6###########
7
8Introduction
9============
10
11The key manager allows for the creation and deletion of Data keys
12specific to threads.
13
14The directives provided by the key manager are:
15
16- pthread_key_create_ - Create Thread Specific Data Key
17
18- pthread_key_delete_ - Delete Thread Specific Data Key
19
20- pthread_setspecific_ - Set Thread Specific Key Value
21
22- pthread_getspecific_ - Get Thread Specific Key Value
23
24Background
25==========
26
27There is currently no text in this section.
28
29Operations
30==========
31
32There is currently no text in this section.
33
34Directives
35==========
36
37This section details the key manager's directives.  A subsection is dedicated
38to each of this manager's directives and describes the calling sequence,
39related constants, usage, and status codes.
40
41.. _pthread_key_create:
42
43pthread_key_create - Create Thread Specific Data Key
44----------------------------------------------------
45
46**CALLING SEQUENCE:**
47
48.. code-block:: c
49
50    #include <pthread.h>
51    int pthread_key_create(
52        pthread_key_t *key,
53        void (*destructor)( void )
54    );
55
56**STATUS CODES:**
57
58.. list-table::
59 :class: rtems-table
60
61 * - ``EAGAIN``
62   - There were not enough resources available to create another key.
63 * - ``ENOMEM``
64   - Insufficient memory exists to create the key.
65
66**DESCRIPTION**
67
68The ``pthread_key_create()`` function shall create a thread-specific data key
69visible to all threads in the process. Key values provided by
70``pthread_key_create()`` are opaque objects used to locate thread-specific
71data. Although the same key value may be used by different threads, the values
72bound to the key by ``pthread_setspecific()`` are maintained on a per-thread
73basis and persist for the life of the calling thread.
74
75Upon key creation, the value ``NULL`` shall be associated with the new key in
76all active threads. Upon thread creation, the value ``NULL`` shall be
77associated with all defined keys in the new thread.
78
79**NOTES**
80
81An optional destructor function may be associated with each key value.  At
82thread exit, if a key value has a non-``NULL`` destructor pointer, and the
83thread has a non-``NULL`` value associated with that key, the value of the key
84is set to NULL, and then the function pointed to is called with the previously
85associated value as its sole argument. The order of destructor calls is
86unspecified if more than one destructor exists for a thread when it exits.
87
88.. _pthread_key_delete:
89
90pthread_key_delete - Delete Thread Specific Data Key
91----------------------------------------------------
92
93**CALLING SEQUENCE:**
94
95.. code-block:: c
96
97    #include <pthread.h>
98    int pthread_key_delete(
99        pthread_key_t key
100    );
101
102**STATUS CODES:**
103
104.. list-table::
105 :class: rtems-table
106
107 * - ``EINVAL``
108   - The key was invalid
109
110**DESCRIPTION:**
111
112The ``pthread_key_delete()`` function shall delete a thread-specific data key
113previously returned by ``pthread_key_create()``. The thread-specific data
114values associated with key need not be NULL at the time
115``pthread_key_delete()`` is called. It is the responsibility of the application
116to free any application storage or perform any cleanup actions for data
117structures related to the deleted key or associated thread-specific data in any
118threads; this cleanup can be done either before or after
119``pthread_key_delete()`` is called. Any attempt to use key following the call
120to ``pthread_key_delete()`` results in undefined behavior.
121
122**NOTES:**
123
124The ``pthread_key_delete()`` function shall be callable from within destructor
125functions. No destructor functions shall be invoked by
126``pthread_key_delete()``. Any destructor function that may have been associated
127with key shall no longer be called upon thread exit.
128
129.. _pthread_setspecific:
130
131pthread_setspecific - Set Thread Specific Key Value
132---------------------------------------------------
133
134**CALLING SEQUENCE:**
135
136.. code-block:: c
137
138    #include <pthread.h>
139    int pthread_setspecific(
140        pthread_key_t  key,
141        const void    *value
142    );
143
144**STATUS CODES:**
145
146.. list-table::
147 :class: rtems-table
148
149 * - ``EINVAL``
150   - The specified key is invalid.
151
152**DESCRIPTION:**
153
154The ``pthread_setspecific()`` function shall associate a thread-specific value
155with a key obtained via a previous call to ``pthread_key_create()``.  Different
156threads may bind different values to the same key. These values are typically
157pointers to blocks of dynamically allocated memory that have been reserved for
158use by the calling thread.
159
160**NOTES:**
161
162The effect of calling ``pthread_setspecific()`` with a key value not obtained
163from ``pthread_key_create()`` or after key has been deleted with
164``pthread_key_delete()`` is undefined.
165
166``pthread_setspecific()`` may be called from a thread-specific data destructor
167function. Calling ``pthread_setspecific()`` from a thread-specific data
168destructor routine may result either in lost storage (after at least
169``PTHREAD_DESTRUCTOR_ITERATIONS`` attempts at destruction) or in an infinite
170loop.
171
172.. _pthread_getspecific:
173
174pthread_getspecific - Get Thread Specific Key Value
175---------------------------------------------------
176
177**CALLING SEQUENCE:**
178
179.. code-block:: c
180
181    #include <pthread.h>
182    void *pthread_getspecific(
183        pthread_key_t key
184    );
185
186**STATUS CODES:**
187
188.. list-table::
189 :class: rtems-table
190
191 * - ``NULL``
192   - There is no thread-specific data associated with the specified key.
193 * - ``non-NULL``
194   - The data associated with the specified key.
195
196**DESCRIPTION:**
197
198The ``pthread_getspecific()`` function shall return the value currently bound
199to the specified key on behalf of the calling thread.
200
201**NOTES:**
202
203The effect of calling ``pthread_getspecific()`` with a key value not obtained
204from ``pthread_key_create()`` or after key has been deleted with
205``pthread_key_delete()`` is undefined.
206
207``pthread_getspecific()`` may be called from a thread-specific data destructor
208function. A call to ``pthread_getspecific()`` for the thread-specific data key
209being destroyed shall return the value ``NULL``, unless the value is changed
210(after the destructor starts) by a call to ``pthread_setspecific()``.
Note: See TracBrowser for help on using the repository browser.