diff options
Diffstat (limited to 'posix_users/key.rst')
| -rw-r--r-- | posix_users/key.rst | 187 |
1 files changed, 101 insertions, 86 deletions
diff --git a/posix_users/key.rst b/posix_users/key.rst index 71b04c7..2c6af32 100644 --- a/posix_users/key.rst +++ b/posix_users/key.rst @@ -1,3 +1,7 @@ +.. COMMENT: COPYRIGHT (c) 1988-2002. +.. COMMENT: On-Line Applications Research Corporation (OAR). +.. COMMENT: All rights reserved. + Key Manager ########### @@ -9,13 +13,13 @@ specific to threads. The directives provided by the key manager are: -- ``pthread_key_create`` - Create Thread Specific Data Key +- pthread_key_create_ - Create Thread Specific Data Key -- ``pthread_key_delete`` - Delete Thread Specific Data Key +- pthread_key_delete_ - Delete Thread Specific Data Key -- ``pthread_setspecific`` - Set Thread Specific Key Value +- pthread_setspecific_ - Set Thread Specific Key Value -- ``pthread_getspecific`` - Get Thread Specific Key Value +- pthread_getspecific_ - Get Thread Specific Key Value Background ========== @@ -30,166 +34,177 @@ 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. +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:: c +.. code-block:: c #include <pthread.h> int pthread_key_create( - pthread_key_t \*key, - void (\*destructor)( void ) + pthread_key_t *key, + void (*destructor)( void ) ); **STATUS CODES:** -*EAGAIN* - There were not enough resources available to create another key. +.. list-table:: + :class: rtems-table -*ENOMEM* - Insufficient memory exists to create the key. + * - ``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. +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 +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. +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:: c +.. code-block:: c #include <pthread.h> int pthread_key_delete( - pthread_key_t key); + pthread_key_t key + ); **STATUS CODES:** -*EINVAL* - The key was invalid +.. 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 +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. +``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. +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:: c +.. code-block:: c #include <pthread.h> int pthread_setspecific( - pthread_key_t key, - const void \*value + pthread_key_t key, + const void *value ); **STATUS CODES:** -*EINVAL* - The specified key is invalid. +.. 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. +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. +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_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:: c +.. code-block:: c #include <pthread.h> - void \*pthread_getspecific( - pthread_key_t key + void *pthread_getspecific( + pthread_key_t key ); **STATUS CODES:** -*NULL* - There is no thread-specific data associated with the specified key. +.. list-table:: + :class: rtems-table -*non-NULL* - The data associated with the specified key. + * - ``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. +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. +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()``. |