summaryrefslogtreecommitdiffstats
path: root/posix_users/key.rst
diff options
context:
space:
mode:
authorAmar Takhar <amar@rtems.org>2016-01-17 00:55:21 -0500
committerAmar Takhar <verm@darkbeer.org>2016-05-02 20:51:23 -0400
commit1264a8f1089fad85cabb024c930b19b0a36864b4 (patch)
treef95424251f62abd513babf47148828ca402dc893 /posix_users/key.rst
parentec76eca9cc967e0d8990316eee1d1841387f5210 (diff)
downloadrtems-docs-1264a8f1089fad85cabb024c930b19b0a36864b4.tar.bz2
Split document into seperate files by section.
Diffstat (limited to 'posix_users/key.rst')
-rw-r--r--posix_users/key.rst195
1 files changed, 195 insertions, 0 deletions
diff --git a/posix_users/key.rst b/posix_users/key.rst
new file mode 100644
index 0000000..1ce6c2a
--- /dev/null
+++ b/posix_users/key.rst
@@ -0,0 +1,195 @@
+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 - Create Thread Specific Data Key
+----------------------------------------------------
+
+**CALLING SEQUENCE:**
+
+.. code:: c
+
+ #include <pthread.h>
+ int pthread_key_create(
+ pthread_key_t \*key,
+ void (\*destructor)( void )
+ );
+
+**STATUS CODES:**
+
+*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 - Delete Thread Specific Data Key
+----------------------------------------------------
+
+**CALLING SEQUENCE:**
+
+.. code:: c
+
+ #include <pthread.h>
+ int pthread_key_delete(
+ pthread_key_t key);
+
+**STATUS CODES:**
+
+*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 - Set Thread Specific Key Value
+---------------------------------------------------
+
+**CALLING SEQUENCE:**
+
+.. code:: c
+
+ #include <pthread.h>
+ int pthread_setspecific(
+ pthread_key_t key,
+ const void \*value
+ );
+
+**STATUS CODES:**
+
+*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 - Get Thread Specific Key Value
+---------------------------------------------------
+
+**CALLING SEQUENCE:**
+
+.. code:: c
+
+ #include <pthread.h>
+ void \*pthread_getspecific(
+ pthread_key_t key
+ );
+
+**STATUS CODES:**
+
+*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().
+
+.. COMMENT: COPYRIGHT (c) 1988-2002.
+
+.. COMMENT: On-Line Applications Research Corporation (OAR).
+
+.. COMMENT: All rights reserved.
+