summaryrefslogtreecommitdiffstats
path: root/posix-users/thread.rst
diff options
context:
space:
mode:
authorChris Johns <chrisj@rtems.org>2016-11-03 16:58:08 +1100
committerChris Johns <chrisj@rtems.org>2016-11-03 16:58:08 +1100
commit72a62ad88f82fe1ffee50024db4dd0f3fa5806f7 (patch)
tree6b0e527e67141f8126ba56b8a3c1eb90aeed5849 /posix-users/thread.rst
parent6207c37d9c8a3d75e67c10671fe2c309c805bbed (diff)
downloadrtems-docs-72a62ad88f82fe1ffee50024db4dd0f3fa5806f7.tar.bz2
Rename all manuals with an _ to have a -. It helps released naming of files.
Diffstat (limited to 'posix-users/thread.rst')
-rw-r--r--posix-users/thread.rst1425
1 files changed, 1425 insertions, 0 deletions
diff --git a/posix-users/thread.rst b/posix-users/thread.rst
new file mode 100644
index 0000000..e5f47c5
--- /dev/null
+++ b/posix-users/thread.rst
@@ -0,0 +1,1425 @@
+.. 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.
+
+Thread Manager
+##############
+
+Introduction
+============
+
+The thread manager implements the functionality required of the thread manager
+as defined by POSIX 1003.1b. This standard requires that a compliant operating
+system provide the facilties to manage multiple threads of control and defines
+the API that must be provided.
+
+The services provided by the thread manager are:
+
+- pthread_attr_init_ - Initialize a Thread Attribute Set
+
+- pthread_attr_destroy_ - Destroy a Thread Attribute Set
+
+- pthread_attr_setdetachstate_ - Set Detach State
+
+- pthread_attr_getdetachstate_ - Get Detach State
+
+- pthread_attr_setstacksize_ - Set Thread Stack Size
+
+- pthread_attr_getstacksize_ - Get Thread Stack Size
+
+- pthread_attr_setstackaddr_ - Set Thread Stack Address
+
+- pthread_attr_getstackaddr_ - Get Thread Stack Address
+
+- pthread_attr_setscope_ - Set Thread Scheduling Scope
+
+- pthread_attr_getscope_ - Get Thread Scheduling Scope
+
+- pthread_attr_setinheritsched_ - Set Inherit Scheduler Flag
+
+- pthread_attr_getinheritsched_ - Get Inherit Scheduler Flag
+
+- pthread_attr_setschedpolicy_ - Set Scheduling Policy
+
+- pthread_attr_getschedpolicy_ - Get Scheduling Policy
+
+- pthread_attr_setschedparam_ - Set Scheduling Parameters
+
+- pthread_attr_getschedparam_ - Get Scheduling Parameters
+
+- pthread_attr_getaffinity_np_ - Get Thread Affinity Attribute
+
+- pthread_attr_setaffinity_np_ - Set Thread Affinity Attribute
+
+- pthread_create_ - Create a Thread
+
+- pthread_exit_ - Terminate the Current Thread
+
+- pthread_detach_ - Detach a Thread
+
+- pthread_getattr_np_ - Get Thread Attributes
+
+- pthread_join_ - Wait for Thread Termination
+
+- pthread_self_ - Get Thread ID
+
+- pthread_equal_ - Compare Thread IDs
+
+- pthread_once_ - Dynamic Package Initialization
+
+- pthread_setschedparam_ - Set Thread Scheduling Parameters
+
+- pthread_getschedparam_ - Get Thread Scheduling Parameters
+
+- pthread_getaffinity_np_ - Get Thread Affinity
+
+- pthread_setaffinity_np_ - Set Thread Affinity
+
+Background
+==========
+
+Thread Attributes
+-----------------
+
+Thread attributes are utilized only at thread creation time. A thread attribute
+structure may be initialized and passed as an argument to the
+``pthread_create`` routine.
+
+*stack address*
+ is the address of the optionally user specified stack area for this thread.
+ If this value is NULL, then RTEMS allocates the memory for the thread stack
+ from the RTEMS Workspace Area. Otherwise, this is the user specified
+ address for the memory to be used for the thread's stack. Each thread must
+ have a distinct stack area. Each processor family has different alignment
+ rules which should be followed.
+
+*stack size*
+ is the minimum desired size for this thread's stack area. If the size of
+ this area as specified by the stack size attribute is smaller than the
+ minimum for this processor family and the stack is not user specified, then
+ RTEMS will automatically allocate a stack of the minimum size for this
+ processor family.
+
+*contention scope*
+ specifies the scheduling contention scope. RTEMS only supports the
+ PTHREAD_SCOPE_PROCESS scheduling contention scope.
+
+*scheduling inheritance*
+ specifies whether a user specified or the scheduling policy and parameters
+ of the currently executing thread are to be used. When this is
+ PTHREAD_INHERIT_SCHED, then the scheduling policy and parameters of the
+ currently executing thread are inherited by the newly created thread.
+
+*scheduling policy and parameters*
+ specify the manner in which the thread will contend for the processor. The
+ scheduling parameters are interpreted based on the specified policy. All
+ policies utilize the thread priority parameter.
+
+Operations
+==========
+
+There is currently no text in this section.
+
+Services
+========
+
+This section details the thread manager's services. A subsection is dedicated
+to each of this manager's services and describes the calling sequence, related
+constants, usage, and status codes.
+
+.. _pthread_attr_init:
+
+pthread_attr_init - Initialize a Thread Attribute Set
+-----------------------------------------------------
+.. index:: pthread_attr_init
+.. index:: initialize a thread attribute set
+
+**CALLING SEQUENCE:**
+
+.. code-block:: c
+
+ #include <pthread.h>
+ int pthread_attr_init(
+ pthread_attr_t *attr
+ );
+
+**STATUS CODES:**
+
+.. list-table::
+ :class: rtems-table
+
+ * - ``EINVAL``
+ - The attribute pointer argument is invalid.
+
+**DESCRIPTION:**
+
+The ``pthread_attr_init`` routine initializes the thread attributes object
+specified by ``attr`` with the default value for all of the individual
+attributes.
+
+**NOTES:**
+
+The settings in the default attributes are implementation defined. For RTEMS,
+the default attributes are as follows:
+
+.. list-table::
+ :class: rtems-table
+
+ * - *stackadr*
+ - is not set to indicate that RTEMS is to allocate the stack memory.
+ * - *stacksize*
+ - is set to ``PTHREAD_MINIMUM_STACK_SIZE``.
+ * - *contentionscope*
+ - is set to ``PTHREAD_SCOPE_PROCESS``.
+ * - *inheritsched*
+ - is set to ``PTHREAD_INHERIT_SCHED`` to indicate that the created thread
+ inherits its scheduling attributes from its parent.
+ * - detachstate
+ - is set to ``PTHREAD_CREATE_JOINABLE``.
+
+.. _pthread_attr_destroy:
+
+pthread_attr_destroy - Destroy a Thread Attribute Set
+-----------------------------------------------------
+.. index:: pthread_attr_destroy
+.. index:: destroy a thread attribute set
+
+**CALLING SEQUENCE:**
+
+.. code-block:: c
+
+ #include <pthread.h>
+ int pthread_attr_destroy(
+ pthread_attr_t *attr
+ );
+
+**STATUS CODES:**
+
+.. list-table::
+ :class: rtems-table
+
+ * - ``EINVAL``
+ - The attribute pointer argument is invalid.
+ * - ``EINVAL``
+ - The attribute set is not initialized.
+
+**DESCRIPTION:**
+
+The ``pthread_attr_destroy`` routine is used to destroy a thread attributes
+object. The behavior of using an attributes object after it is destroyed is
+implementation dependent.
+
+**NOTES:**
+
+NONE
+
+.. _pthread_attr_setdetachstate:
+
+pthread_attr_setdetachstate - Set Detach State
+----------------------------------------------
+.. index:: pthread_attr_setdetachstate
+.. index:: set detach state
+
+**CALLING SEQUENCE:**
+
+.. code-block:: c
+
+ #include <pthread.h>
+ int pthread_attr_setdetachstate(
+ pthread_attr_t *attr,
+ int detachstate
+ );
+
+**STATUS CODES:**
+
+.. list-table::
+ :class: rtems-table
+
+ * - ``EINVAL``
+ - The attribute pointer argument is invalid.
+ * - ``EINVAL``
+ - The attribute set is not initialized.
+ * - ``EINVAL``
+ - The detachstate argument is invalid.
+
+**DESCRIPTION:**
+
+The ``pthread_attr_setdetachstate`` routine is used to value of the
+``detachstate`` attribute. This attribute controls whether the thread is
+created in a detached state.
+
+The ``detachstate`` can be either ``PTHREAD_CREATE_DETACHED`` or
+``PTHREAD_CREATE_JOINABLE``. The default value for all threads is
+``PTHREAD_CREATE_JOINABLE``.
+
+**NOTES:**
+
+If a thread is in a detached state, then the use of the ID with the
+``pthread_detach`` or ``pthread_join`` routines is an error.
+
+.. _pthread_attr_getdetachstate:
+
+pthread_attr_getdetachstate - Get Detach State
+----------------------------------------------
+.. index:: pthread_attr_getdetachstate
+.. index:: get detach state
+
+**CALLING SEQUENCE:**
+
+.. code-block:: c
+
+ #include <pthread.h>
+ int pthread_attr_getdetachstate(
+ const pthread_attr_t *attr,
+ int *detachstate
+ );
+
+**STATUS CODES:**
+
+.. list-table::
+ :class: rtems-table
+
+ * - ``EINVAL``
+ - The attribute pointer argument is invalid.
+ * - ``EINVAL``
+ - The attribute set is not initialized.
+ * - ``EINVAL``
+ - The detatchstate pointer argument is invalid.
+
+**DESCRIPTION:**
+
+The ``pthread_attr_getdetachstate`` routine is used to obtain the current value
+of the ``detachstate`` attribute as specified by the ``attr`` thread attribute
+object.
+
+**NOTES:**
+
+NONE
+
+.. _pthread_attr_setstacksize:
+
+pthread_attr_setstacksize - Set Thread Stack Size
+-------------------------------------------------
+.. index:: pthread_attr_setstacksize
+.. index:: set thread stack size
+
+**CALLING SEQUENCE:**
+
+.. code-block:: c
+
+ #include <pthread.h>
+ int pthread_attr_setstacksize(
+ pthread_attr_t *attr,
+ size_t stacksize
+ );
+
+**STATUS CODES:**
+
+.. list-table::
+ :class: rtems-table
+
+ * - ``EINVAL``
+ - The attribute pointer argument is invalid.
+ * - ``EINVAL``
+ - The attribute set is not initialized.
+
+**DESCRIPTION:**
+
+The ``pthread_attr_setstacksize`` routine is used to set the ``stacksize``
+attribute in the ``attr`` thread attribute object.
+
+**NOTES:**
+
+As required by POSIX, RTEMS defines the feature symbol
+``_POSIX_THREAD_ATTR_STACKSIZE`` to indicate that this routine is supported.
+
+If the specified stacksize is below the minimum required for this CPU
+(``PTHREAD_STACK_MIN``, then the stacksize will be set to the minimum for this
+CPU.
+
+.. _pthread_attr_getstacksize:
+
+pthread_attr_getstacksize - Get Thread Stack Size
+-------------------------------------------------
+.. index:: pthread_attr_getstacksize
+.. index:: get thread stack size
+
+**CALLING SEQUENCE:**
+
+.. code-block:: c
+
+ #include <pthread.h>
+ int pthread_attr_getstacksize(
+ const pthread_attr_t *attr,
+ size_t *stacksize
+ );
+
+**STATUS CODES:**
+
+.. list-table::
+ :class: rtems-table
+
+ * - ``EINVAL``
+ - The attribute pointer argument is invalid.
+ * - ``EINVAL``
+ - The attribute set is not initialized.
+ * - ``EINVAL``
+ - The stacksize pointer argument is invalid.
+
+**DESCRIPTION:**
+
+The ``pthread_attr_getstacksize`` routine is used to obtain the ``stacksize``
+attribute in the ``attr`` thread attribute object.
+
+**NOTES:**
+
+As required by POSIX, RTEMS defines the feature symbol
+``_POSIX_THREAD_ATTR_STACKSIZE`` to indicate that this routine is supported.
+
+.. _pthread_attr_setstackaddr:
+
+pthread_attr_setstackaddr - Set Thread Stack Address
+----------------------------------------------------
+.. index:: pthread_attr_setstackaddr
+.. index:: set thread stack address
+
+**CALLING SEQUENCE:**
+
+.. code-block:: c
+
+ #include <pthread.h>
+ int pthread_attr_setstackaddr(
+ pthread_attr_t *attr,
+ void *stackaddr
+ );
+
+**STATUS CODES:**
+
+.. list-table::
+ :class: rtems-table
+
+ * - ``EINVAL``
+ - The attribute pointer argument is invalid.
+ * - ``EINVAL``
+ - The attribute set is not initialized.
+
+**DESCRIPTION:**
+
+The ``pthread_attr_setstackaddr`` routine is used to set the ``stackaddr``
+attribute in the ``attr`` thread attribute object.
+
+**NOTES:**
+
+As required by POSIX, RTEMS defines the feature symbol
+``_POSIX_THREAD_ATTR_STACKADDR`` to indicate that this routine is supported.
+
+It is imperative to the proper operation of the system that each thread have
+sufficient stack space.
+
+.. _pthread_attr_getstackaddr:
+
+pthread_attr_getstackaddr - Get Thread Stack Address
+----------------------------------------------------
+.. index:: pthread_attr_getstackaddr
+.. index:: get thread stack address
+
+**CALLING SEQUENCE:**
+
+.. code-block:: c
+
+ #include <pthread.h>
+ int pthread_attr_getstackaddr(
+ const pthread_attr_t *attr,
+ void **stackaddr
+ );
+
+**STATUS CODES:**
+
+.. list-table::
+ :class: rtems-table
+
+ * - ``EINVAL``
+ - The attribute pointer argument is invalid.
+ * - ``EINVAL``
+ - The attribute set is not initialized.
+ * - ``EINVAL``
+ - The stackaddr pointer argument is invalid.
+
+**DESCRIPTION:**
+
+The ``pthread_attr_getstackaddr`` routine is used to obtain the ``stackaddr``
+attribute in the ``attr`` thread attribute object.
+
+**NOTES:**
+
+As required by POSIX, RTEMS defines the feature symbol
+``_POSIX_THREAD_ATTR_STACKADDR`` to indicate that this routine is supported.
+
+.. _pthread_attr_setscope:
+
+pthread_attr_setscope - Set Thread Scheduling Scope
+---------------------------------------------------
+.. index:: pthread_attr_setscope
+.. index:: set thread scheduling scope
+
+**CALLING SEQUENCE:**
+
+.. code-block:: c
+
+ #include <pthread.h>
+ int pthread_attr_setscope(
+ pthread_attr_t *attr,
+ int contentionscope
+ );
+
+**STATUS CODES:**
+
+.. list-table::
+ :class: rtems-table
+
+ * - ``EINVAL``
+ - The attribute pointer argument is invalid.
+ * - ``EINVAL``
+ - The attribute set is not initialized.
+ * - ``EINVAL``
+ - The contention scope specified is not valid.
+ * - ``ENOTSUP``
+ - The contention scope specified (``PTHREAD_SCOPE_SYSTEM``) is not supported.
+
+**DESCRIPTION:**
+
+The ``pthread_attr_setscope`` routine is used to set the contention scope field
+in the thread attribute object ``attr`` to the value specified by
+``contentionscope``.
+
+The ``contentionscope`` must be either ``PTHREAD_SCOPE_SYSTEM`` to indicate
+that the thread is to be within system scheduling contention or
+``PTHREAD_SCOPE_PROCESS`` indicating that the thread is to be within the
+process scheduling contention scope.
+
+**NOTES:**
+
+As required by POSIX, RTEMS defines the feature symbol
+``_POSIX_THREAD_PRIORITY_SCHEDULING`` to indicate that the family of routines
+to which this routine belongs is supported.
+
+.. _pthread_attr_getscope:
+
+pthread_attr_getscope - Get Thread Scheduling Scope
+---------------------------------------------------
+.. index:: pthread_attr_getscope
+.. index:: get thread scheduling scope
+
+**CALLING SEQUENCE:**
+
+.. code-block:: c
+
+ #include <pthread.h>
+ int pthread_attr_getscope(
+ const pthread_attr_t *attr,
+ int *contentionscope
+ );
+
+**STATUS CODES:**
+
+.. list-table::
+ :class: rtems-table
+
+ * - ``EINVAL``
+ - The attribute pointer argument is invalid.
+ * - ``EINVAL``
+ - The attribute set is not initialized.
+ * - ``EINVAL``
+ - The contentionscope pointer argument is invalid.
+
+**DESCRIPTION:**
+
+The ``pthread_attr_getscope`` routine is used to obtain the value of the
+contention scope field in the thread attributes object ``attr``. The current
+value is returned in ``contentionscope``.
+
+**NOTES:**
+
+As required by POSIX, RTEMS defines the feature symbol
+``_POSIX_THREAD_PRIORITY_SCHEDULING`` to indicate that the family of routines
+to which this routine belongs is supported.
+
+.. _pthread_attr_setinheritsched:
+
+pthread_attr_setinheritsched - Set Inherit Scheduler Flag
+---------------------------------------------------------
+.. index:: pthread_attr_setinheritsched
+.. index:: set inherit scheduler flag
+
+**CALLING SEQUENCE:**
+
+.. code-block:: c
+
+ #include <pthread.h>
+ int pthread_attr_setinheritsched(
+ pthread_attr_t *attr,
+ int inheritsched
+ );
+
+**STATUS CODES:**
+
+.. list-table::
+ :class: rtems-table
+
+ * - ``EINVAL``
+ - The attribute pointer argument is invalid.
+ * - ``EINVAL``
+ - The attribute set is not initialized.
+ * - ``EINVAL``
+ - The specified scheduler inheritance argument is invalid.
+
+**DESCRIPTION:**
+
+The ``pthread_attr_setinheritsched`` routine is used to set the inherit
+scheduler field in the thread attribute object ``attr`` to the value specified
+by ``inheritsched``.
+
+The ``contentionscope`` must be either ``PTHREAD_INHERIT_SCHED`` to indicate
+that the thread is to inherit the scheduling policy and parameters fromthe
+creating thread, or ``PTHREAD_EXPLICIT_SCHED`` to indicate that the scheduling
+policy and parameters for this thread are to be set from the corresponding
+values in the attributes object. If ``contentionscope`` is
+``PTHREAD_INHERIT_SCHED``, then the scheduling attributes in the ``attr``
+structure will be ignored at thread creation time.
+
+**NOTES:**
+
+As required by POSIX, RTEMS defines the feature symbol
+``_POSIX_THREAD_PRIORITY_SCHEDULING`` to indicate that the family of routines
+to which this routine belongs is supported.
+
+.. _pthread_attr_getinheritsched:
+
+pthread_attr_getinheritsched - Get Inherit Scheduler Flag
+---------------------------------------------------------
+.. index:: pthread_attr_getinheritsched
+.. index:: get inherit scheduler flag
+
+**CALLING SEQUENCE:**
+
+.. code-block:: c
+
+ #include <pthread.h>
+ int pthread_attr_getinheritsched(
+ const pthread_attr_t *attr,
+ int *inheritsched
+ );
+
+**STATUS CODES:**
+
+.. list-table::
+ :class: rtems-table
+
+ * - ``EINVAL``
+ - The attribute pointer argument is invalid.
+ * - ``EINVAL``
+ - The attribute set is not initialized.
+ * - ``EINVAL``
+ - The inheritsched pointer argument is invalid.
+
+**DESCRIPTION:**
+
+The ``pthread_attr_getinheritsched`` routine is used to object the current
+value of the inherit scheduler field in the thread attribute object ``attr``.
+
+**NOTES:**
+
+As required by POSIX, RTEMS defines the feature symbol
+``_POSIX_THREAD_PRIORITY_SCHEDULING`` to indicate that the family of routines
+to which this routine belongs is supported.
+
+.. _pthread_attr_setschedpolicy:
+
+pthread_attr_setschedpolicy - Set Scheduling Policy
+---------------------------------------------------
+.. index:: pthread_attr_setschedpolicy
+.. index:: set scheduling policy
+
+**CALLING SEQUENCE:**
+
+.. code-block:: c
+
+ #include <pthread.h>
+ int pthread_attr_setschedpolicy(
+ pthread_attr_t *attr,
+ int policy
+ );
+
+**STATUS CODES:**
+
+.. list-table::
+ :class: rtems-table
+
+ * - ``EINVAL``
+ - The attribute pointer argument is invalid.
+ * - ``EINVAL``
+ - The attribute set is not initialized.
+ * - ``ENOTSUP``
+ - The specified scheduler policy argument is invalid.
+
+**DESCRIPTION:**
+
+The ``pthread_attr_setschedpolicy`` routine is used to set the scheduler policy
+field in the thread attribute object ``attr`` to the value specified by
+``policy``.
+
+Scheduling policies may be one of the following:
+
+- ``SCHED_DEFAULT``
+
+- ``SCHED_FIFO``
+
+- ``SCHED_RR``
+
+- ``SCHED_SPORADIC``
+
+- ``SCHED_OTHER``
+
+The precise meaning of each of these is discussed elsewhere in this manual.
+
+**NOTES:**
+
+As required by POSIX, RTEMS defines the feature symbol
+``_POSIX_THREAD_PRIORITY_SCHEDULING`` to indicate that the family of routines
+to which this routine belongs is supported.
+
+.. _pthread_attr_getschedpolicy:
+
+pthread_attr_getschedpolicy - Get Scheduling Policy
+---------------------------------------------------
+.. index:: pthread_attr_getschedpolicy
+.. index:: get scheduling policy
+
+**CALLING SEQUENCE:**
+
+.. code-block:: c
+
+ #include <pthread.h>
+ int pthread_attr_getschedpolicy(
+ const pthread_attr_t *attr,
+ int *policy
+ );
+
+**STATUS CODES:**
+
+.. list-table::
+ :class: rtems-table
+
+ * - ``EINVAL``
+ - The attribute pointer argument is invalid.
+ * - ``EINVAL``
+ - The attribute set is not initialized.
+ * - ``EINVAL``
+ - The specified scheduler policy argument pointer is invalid.
+
+**DESCRIPTION:**
+
+The ``pthread_attr_getschedpolicy`` routine is used to obtain the scheduler
+policy field from the thread attribute object ``attr``. The value of this
+field is returned in ``policy``.
+
+**NOTES:**
+
+As required by POSIX, RTEMS defines the feature symbol
+``_POSIX_THREAD_PRIORITY_SCHEDULING`` to indicate that the family of routines
+to which this routine belongs is supported.
+
+.. _pthread_attr_setschedparam:
+
+pthread_attr_setschedparam - Set Scheduling Parameters
+------------------------------------------------------
+.. index:: pthread_attr_setschedparam
+.. index:: set scheduling parameters
+
+**CALLING SEQUENCE:**
+
+.. code-block:: c
+
+ #include <pthread.h>
+ int pthread_attr_setschedparam(
+ pthread_attr_t *attr,
+ const struct sched_param param
+ );
+
+**STATUS CODES:**
+
+.. list-table::
+ :class: rtems-table
+
+ * - ``EINVAL``
+ - The attribute pointer argument is invalid.
+ * - ``EINVAL``
+ - The attribute set is not initialized.
+ * - ``EINVAL``
+ - The specified scheduler parameter argument is invalid.
+
+**DESCRIPTION:**
+
+The ``pthread_attr_setschedparam`` routine is used to set the scheduler
+parameters field in the thread attribute object ``attr`` to the value specified
+by ``param``.
+
+**NOTES:**
+
+As required by POSIX, RTEMS defines the feature symbol
+``_POSIX_THREAD_PRIORITY_SCHEDULING`` to indicate that the family of routines
+to which this routine belongs is supported.
+
+.. _pthread_attr_getschedparam:
+
+pthread_attr_getschedparam - Get Scheduling Parameters
+------------------------------------------------------
+.. index:: pthread_attr_getschedparam
+.. index:: get scheduling parameters
+
+**CALLING SEQUENCE:**
+
+.. code-block:: c
+
+ #include <pthread.h>
+ int pthread_attr_getschedparam(
+ const pthread_attr_t *attr,
+ struct sched_param *param
+ );
+
+**STATUS CODES:**
+
+.. list-table::
+ :class: rtems-table
+
+ * - ``EINVAL``
+ - The attribute pointer argument is invalid.
+ * - ``EINVAL``
+ - The attribute set is not initialized.
+ * - ``EINVAL``
+ - The specified scheduler parameter argument pointer is invalid.
+
+**DESCRIPTION:**
+
+The ``pthread_attr_getschedparam`` routine is used to obtain the scheduler
+parameters field from the thread attribute object ``attr``. The value of this
+field is returned in ``param``.
+
+**NOTES:**
+
+As required by POSIX, RTEMS defines the feature symbol
+``_POSIX_THREAD_PRIORITY_SCHEDULING`` to indicate that the family of routines
+to which this routine belongs is supported.
+
+.. _pthread_attr_getaffinity_np:
+
+pthread_attr_getaffinity_np - Get Thread Affinity Attribute
+-----------------------------------------------------------
+
+**CALLING SEQUENCE:**
+
+.. code-block:: c
+
+ #define _GNU_SOURCE
+ #include <pthread.h>
+ int pthread_attr_getaffinity_np(
+ const pthread_attr_t *attr,
+ size_t cpusetsize,
+ cpu_set_t *cpuset
+ );
+
+**STATUS CODES:**
+
+.. list-table::
+ :class: rtems-table
+
+ * - ``EFAULT``
+ - The attribute pointer argument is invalid.
+ * - ``EFAULT``
+ - The cpuset pointer argument is invalid.
+ * - ``EINVAL``
+ - The ``cpusetsize`` does not match the value of ``affinitysetsize`` field
+ in the thread attribute object.
+
+**DESCRIPTION:**
+
+The ``pthread_attr_getaffinity_np`` routine is used to obtain the
+``affinityset`` field from the thread attribute object ``attr``. The value of
+this field is returned in ``cpuset``.
+
+**NOTES:**
+
+NONE
+
+.. _pthread_attr_setaffinity_np:
+
+pthread_attr_setaffinity_np - Set Thread Affinity Attribute
+-----------------------------------------------------------
+
+**CALLING SEQUENCE:**
+
+.. code-block:: c
+
+ #define _GNU_SOURCE
+ #include <pthread.h>
+ int pthread_attr_setaffinity_np(
+ pthread_attr_t *attr,
+ size_t cpusetsize,
+ const cpu_set_t *cpuset
+ );
+
+**STATUS CODES:**
+
+.. list-table::
+ :class: rtems-table
+
+ * - ``EFAULT``
+ - The attribute pointer argument is invalid.
+ * - ``EFAULT``
+ - The cpuset pointer argument is invalid.
+ * - ``EINVAL``
+ - The ``cpusetsize`` does not match the value of ``affinitysetsize`` field
+ in the thread attribute object.
+ * - ``EINVAL``
+ - The ``cpuset`` did not select a valid cpu.
+ * - ``EINVAL``
+ - The ``cpuset`` selected a cpu that was invalid.
+
+**DESCRIPTION:**
+
+The ``pthread_attr_setaffinity_np`` routine is used to set the ``affinityset``
+field in the thread attribute object ``attr``. The value of this field is
+returned in ``cpuset``.
+
+**NOTES:**
+
+NONE
+
+.. _pthread_create:
+
+pthread_create - Create a Thread
+--------------------------------
+.. index:: pthread_create
+.. index:: create a thread
+
+**CALLING SEQUENCE:**
+
+.. code-block:: c
+
+ #include <pthread.h>
+ int pthread_create(
+ pthread_t *thread,
+ const pthread_attr_t *attr,
+ void (*start_routine)( void *),
+ void *arg
+ );
+
+**STATUS CODES:**
+
+.. list-table::
+ :class: rtems-table
+
+ * - ``EINVAL``
+ - The attribute set is not initialized.
+ * - ``EINVAL``
+ - The user specified a stack address and the size of the area was not large
+ enough to meet this processor's minimum stack requirements.
+ * - ``EINVAL``
+ - The specified scheduler inheritance policy was invalid.
+ * - ``ENOTSUP``
+ - The specified contention scope was ``PTHREAD_SCOPE_PROCESS``.
+ * - ``EINVAL``
+ - The specified thread priority was invalid.
+ * - ``EINVAL``
+ - The specified scheduling policy was invalid.
+ * - ``EINVAL``
+ - The scheduling policy was ``SCHED_SPORADIC`` and the specified
+ replenishment period is less than the initial budget.
+ * - ``EINVAL``
+ - The scheduling policy was ``SCHED_SPORADIC`` and the specified low
+ priority is invalid.
+ * - ``EAGAIN``
+ - The system lacked the necessary resources to create another thread, or the
+ self imposed limit on the total number of threads in a process
+ ``PTHREAD_THREAD_MAX`` would be exceeded.
+ * - ``EINVAL``
+ - Invalid argument passed.
+
+**DESCRIPTION:**
+
+The ``pthread_create`` routine is used to create a new thread with the
+attributes specified by ``attr``. If the ``attr`` argument is ``NULL``, then
+the default attribute set will be used. Modification of the contents of
+``attr`` after this thread is created does not have an impact on this thread.
+
+The thread begins execution at the address specified by ``start_routine`` with
+``arg`` as its only argument. If ``start_routine`` returns, then it is
+functionally equivalent to the thread executing the ``pthread_exit`` service.
+
+Upon successful completion, the ID of the created thread is returned in the
+``thread`` argument.
+
+**NOTES:**
+
+There is no concept of a single main thread in RTEMS as there is in a tradition
+UNIX system. POSIX requires that the implicit return of the main thread results
+in the same effects as if there were a call to ``exit``. This does not occur in
+RTEMS.
+
+The signal mask of the newly created thread is inherited from its creator and
+the set of pending signals for this thread is empty.
+
+.. _pthread_exit:
+
+pthread_exit - Terminate the Current Thread
+-------------------------------------------
+.. index:: pthread_exit
+.. index:: terminate the current thread
+
+**CALLING SEQUENCE:**
+
+.. code-block:: c
+
+ #include <pthread.h>
+ void pthread_exit(
+ void *status
+ );
+
+**STATUS CODES:**
+
+*NONE*
+
+**DESCRIPTION:**
+
+The ``pthread_exit`` routine is used to terminate the calling thread. The
+``status`` is made available to any successful join with the terminating
+thread.
+
+When a thread returns from its start routine, it results in an implicit call to
+the ``pthread_exit`` routine with the return value of the function serving as
+the argument to ``pthread_exit``.
+
+**NOTES:**
+
+Any cancellation cleanup handlers that hace been pushed and not yet popped
+shall be popped in reverse of the order that they were pushed. After all
+cancellation cleanup handlers have been executed, if the thread has any
+thread-specific data, destructors for that data will be invoked.
+
+Thread termination does not release or free any application visible resources
+including byt not limited to mutexes, file descriptors, allocated memory,
+etc.. Similarly, exitting a thread does not result in any process-oriented
+cleanup activity.
+
+There is no concept of a single main thread in RTEMS as there is in a tradition
+UNIX system. POSIX requires that the implicit return of the main thread results
+in the same effects as if there were a call to ``exit``. This does not occur in
+RTEMS.
+
+All access to any automatic variables allocated by the threads is lost when the
+thread exits. Thus references (i.e. pointers) to local variables of a thread
+should not be used in a global manner without care. As a specific example, a
+pointer to a local variable should NOT be used as the return value.
+
+.. _pthread_detach:
+
+pthread_detach - Detach a Thread
+--------------------------------
+.. index:: pthread_detach
+.. index:: detach a thread
+
+**CALLING SEQUENCE:**
+
+.. code-block:: c
+
+ #include <pthread.h>
+ int pthread_detach(
+ pthread_t thread
+ );
+
+**STATUS CODES:**
+
+.. list-table::
+ :class: rtems-table
+
+ * - ``ESRCH``
+ - The thread specified is invalid.
+ * - ``EINVAL``
+ - The thread specified is not a joinable thread.
+
+**DESCRIPTION:**
+
+The ``pthread_detach`` routine is used to to indicate that storage for
+``thread`` can be reclaimed when the thread terminates without another thread
+joinging with it.
+
+**NOTES:**
+
+If any threads have previously joined with the specified thread, then they will
+remain joined with that thread. Any subsequent calls to ``pthread_join`` on the
+specified thread will fail.
+
+.. COMMENT: pthread_getattr_np
+
+.. _pthread_getattr_np:
+
+pthread_getattr_np - Get Thread Attributes
+------------------------------------------
+.. index:: pthread_getattr_np
+.. index:: get thread attributes
+
+**CALLING SEQUENCE:**
+
+.. code-block:: c
+
+ #define _GNU_SOURCE
+ #include <pthread.h>
+ int pthread_getattr_np(
+ pthread_t thread,
+ pthread_attr_t *attr
+ );
+
+**STATUS CODES:**
+
+.. list-table::
+ :class: rtems-table
+
+ * - ``ESRCH``
+ - The thread specified is invalid.
+ * - ``EINVAL``
+ - The attribute pointer argument is invalid.
+
+**DESCRIPTION:**
+
+The ``pthread_getattr_np`` routine is used to obtain the attributes associated
+with ``thread``.
+
+**NOTES:**
+
+Modification of the execution modes and priority through the Classic API may
+result in a combination that is not representable in the POSIX API.
+
+.. _pthread_join:
+
+pthread_join - Wait for Thread Termination
+------------------------------------------
+.. index:: pthread_join
+.. index:: wait for thread termination
+
+**CALLING SEQUENCE:**
+
+.. code-block:: c
+
+ #include <pthread.h>
+ int pthread_join(
+ pthread_t thread,
+ void **value_ptr
+ );
+
+**STATUS CODES:**
+
+.. list-table::
+ :class: rtems-table
+
+ * - ``ESRCH``
+ - The thread specified is invalid.
+ * - ``EINVAL``
+ - The thread specified is not a joinable thread.
+ * - ``EDEADLK``
+ - A deadlock was detected or thread is the calling thread.
+
+**DESCRIPTION:**
+
+The ``pthread_join`` routine suspends execution of the calling thread until
+``thread`` terminates. If ``thread`` has already terminated, then this routine
+returns immediately. The value returned by ``thread`` (i.e. passed to
+``pthread_exit`` is returned in ``value_ptr``.
+
+When this routine returns, then ``thread`` has been terminated.
+
+**NOTES:**
+
+The results of multiple simultaneous joins on the same thread is undefined.
+
+If any threads have previously joined with the specified thread, then they will
+remain joined with that thread. Any subsequent calls to ``pthread_join`` on the
+specified thread will fail.
+
+If value_ptr is NULL, then no value is returned.
+
+.. _pthread_self:
+
+pthread_self - Get Thread ID
+----------------------------
+.. index:: pthread_self
+.. index:: get thread id
+
+**CALLING SEQUENCE:**
+
+.. code-block:: c
+
+ #include <pthread.h>
+ pthread_t pthread_self( void );
+
+**STATUS CODES:**
+
+The value returned is the ID of the calling thread.
+
+**DESCRIPTION:**
+
+This routine returns the ID of the calling thread.
+
+**NOTES:**
+
+NONE
+
+.. _pthread_equal:
+
+pthread_equal - Compare Thread IDs
+----------------------------------
+.. index:: pthread_equal
+.. index:: compare thread ids
+
+**CALLING SEQUENCE:**
+
+.. code-block:: c
+
+ #include <pthread.h>
+ int pthread_equal(
+ pthread_t t1,
+ pthread_t t2
+ );
+
+**STATUS CODES:**
+
+.. list-table::
+ :class: rtems-table
+
+ * - ``zero``
+ - The thread ids are not equal.
+ * - ``non-zero``
+ - The thread ids are equal.
+
+**DESCRIPTION:**
+
+The ``pthread_equal`` routine is used to compare two thread IDs and determine
+if they are equal.
+
+**NOTES:**
+
+The behavior is undefined if the thread IDs are not valid.
+
+.. _pthread_once:
+
+pthread_once - Dynamic Package Initialization
+---------------------------------------------
+.. index:: pthread_once
+.. index:: dynamic package initialization
+
+**CALLING SEQUENCE:**
+
+.. code-block:: c
+
+ #include <pthread.h>
+ pthread_once_t once_control = PTHREAD_ONCE_INIT;
+ int pthread_once(
+ pthread_once_t *once_control,
+ void (*init_routine)(void)
+ );
+
+**STATUS CODES:**
+
+NONE
+
+**DESCRIPTION:**
+
+The ``pthread_once`` routine is used to provide controlled initialization of
+variables. The first call to ``pthread_once`` by any thread with the same
+``once_control`` will result in the ``init_routine`` being invoked with no
+arguments. Subsequent calls to ``pthread_once`` with the same ``once_control``
+will have no effect.
+
+The ``init_routine`` is guaranteed to have run to completion when this routine
+returns to the caller.
+
+**NOTES:**
+
+The behavior of ``pthread_once`` is undefined if ``once_control`` is automatic
+storage (i.e. on a task stack) or is not initialized using
+``PTHREAD_ONCE_INIT``.
+
+.. _pthread_setschedparam:
+
+pthread_setschedparam - Set Thread Scheduling Parameters
+--------------------------------------------------------
+.. index:: pthread_setschedparam
+.. index:: set thread scheduling parameters
+
+**CALLING SEQUENCE:**
+
+.. code-block:: c
+
+ #include <pthread.h>
+ int pthread_setschedparam(
+ pthread_t thread,
+ int policy,
+ struct sched_param *param
+ );
+
+**STATUS CODES:**
+
+.. list-table::
+ :class: rtems-table
+
+ * - ``EINVAL``
+ - The scheduling parameters indicated by the parameter param is invalid.
+ * - ``EINVAL``
+ - The value specified by policy is invalid.
+ * - ``EINVAL``
+ - The scheduling policy was ``SCHED_SPORADIC`` and the specified
+ replenishment period is less than the initial budget.
+ * - ``EINVAL``
+ - The scheduling policy was ``SCHED_SPORADIC`` and the specified low
+ priority is invalid.
+ * - ``ESRCH``
+ - The thread indicated was invalid.
+
+**DESCRIPTION:**
+
+The ``pthread_setschedparam`` routine is used to set the scheduler parameters
+currently associated with the thread specified by ``thread`` to the policy
+specified by ``policy``. The contents of ``param`` are interpreted based upon
+the ``policy`` argument.
+
+**NOTES:**
+
+As required by POSIX, RTEMS defines the feature symbol
+``_POSIX_THREAD_PRIORITY_SCHEDULING`` to indicate that the family of routines
+to which this routine belongs is supported.
+
+.. _pthread_getschedparam:
+
+pthread_getschedparam - Get Thread Scheduling Parameters
+--------------------------------------------------------
+.. index:: pthread_getschedparam
+.. index:: get thread scheduling parameters
+
+**CALLING SEQUENCE:**
+
+.. code-block:: c
+
+ #include <pthread.h>
+ int pthread_getschedparam(
+ pthread_t thread,
+ int *policy,
+ struct sched_param *param
+ );
+
+**STATUS CODES:**
+
+.. list-table::
+ :class: rtems-table
+
+ * - ``EINVAL``
+ - The policy pointer argument is invalid.
+ * - ``EINVAL``
+ - The scheduling parameters pointer argument is invalid.
+ * - ``ESRCH``
+ - The thread indicated by the parameter thread is invalid.
+
+**DESCRIPTION:**
+
+The ``pthread_getschedparam`` routine is used to obtain the scheduler policy
+and parameters associated with ``thread``. The current policy and associated
+parameters values returned in``policy`` and ``param``, respectively.
+
+**NOTES:**
+
+As required by POSIX, RTEMS defines the feature symbol
+``_POSIX_THREAD_PRIORITY_SCHEDULING`` to indicate that the family of routines
+to which this routine belongs is supported.
+
+.. COMMENT: pthread_getaffinity_np
+
+.. _pthread_getaffinity_np:
+
+pthread_getaffinity_np - Get Thread Affinity
+--------------------------------------------
+
+**CALLING SEQUENCE:**
+
+.. code-block:: c
+
+ #define _GNU_SOURCE
+ #include <pthread.h>
+ int pthread_getaffinity_np(
+ const pthread_t id,
+ size_t cpusetsize,
+ cpu_set_t *cpuset
+ );
+
+**STATUS CODES:**
+
+.. list-table::
+ :class: rtems-table
+
+ * - ``EFAULT``
+ - The cpuset pointer argument is invalid.
+ * - ``EINVAL``
+ - The ``cpusetsize`` does not match the value of ``affinitysetsize`` field
+ in the thread attribute object.
+
+**DESCRIPTION:**
+
+The ``pthread_getaffinity_np`` routine is used to obtain the ``affinity.set``
+field from the thread control object associated with the ``id``. The value of
+this field is returned in ``cpuset``.
+
+**NOTES:**
+
+NONE
+
+.. COMMENT: pthread_setaffinity_np
+
+.. _pthread_setaffinity_np:
+
+pthread_setaffinity_np - Set Thread Affinity
+--------------------------------------------
+
+**CALLING SEQUENCE:**
+
+.. code-block:: c
+
+ #define _GNU_SOURCE
+ #include <pthread.h>
+ int pthread_setaffinity_np(
+ pthread_t id,
+ size_t cpusetsize,
+ const cpu_set_t *cpuset
+ );
+
+**STATUS CODES:**
+
+.. list-table::
+ :class: rtems-table
+
+ * - ``EFAULT``
+ - The cpuset pointer argument is invalid.
+ * - ``EINVAL``
+ - The ``cpusetsize`` does not match the value of ``affinitysetsize`` field
+ in the thread attribute object.
+ * - ``EINVAL``
+ - The ``cpuset`` did not select a valid cpu.
+ * - ``EINVAL``
+ - The ``cpuset`` selected a cpu that was invalid.
+
+**DESCRIPTION:**
+
+The ``pthread_setaffinity_np`` routine is used to set the ``affinityset`` field
+of the thread object ``id``. The value of this field is returned in ``cpuset``
+
+**NOTES:**
+
+NONE