POSIX User clean up.

posix_users/clock.rst

@@ -1,32 +1,33 @@
+.. COMMENT: This is the chapter from the RTEMS POSIX 1003.1b API User's Guide that
+.. COMMENT: documents the services provided by the timer @c  manager.
+
 Clock Manager
 #############
 
 Introduction
 ============
 
-The clock manager provides services two primary classes
+The clock manager provides services two primary classes of services.  The first
-of services.  The first focuses on obtaining and setting
+focuses on obtaining and setting the current date and time.  The other category
-the current date and time.  The other category of services
+of services focus on allowing a thread to delay for a specific length of time.
-focus on allowing a thread to delay for a specific length
-of time.
 
 The directives provided by the clock manager are:
 
-- ``clock_gettime`` - Obtain Time of Day
+- clock_gettime_ - Obtain Time of Day
 
-- ``clock_settime`` - Set Time of Day
+- clock_settime_ - Set Time of Day
 
-- ``clock_getres`` - Get Clock Resolution
+- clock_getres_ - Get Clock Resolution
 
-- ``sleep`` - Delay Process Execution
+- sleep_ - Delay Process Execution
 
-- ``usleep`` - Delay Process Execution in Microseconds
+- usleep_ - Delay Process Execution in Microseconds
 
-- ``nanosleep`` - Delay with High Resolution
+- nanosleep_ - Delay with High Resolution
 
-- ``gettimeofday`` - Get the Time of Day
+- gettimeofday_ - Get the Time of Day
 
-- ``time`` - Get time in seconds
+- time_ - Get time in seconds
 
 Background
 ==========
@@ -41,10 +42,11 @@ There is currently no text in this section.
 Directives
 ==========
 
-This section details the clock manager's directives.
+This section details the clock manager's directives.  A subsection is dedicated
-A subsection is dedicated to each of this manager's directives
+to each of this manager's directives and describes the calling sequence,
-and describes the calling sequence, related constants, usage,
+related constants, usage, and status codes.
-and status codes.
+
+.. _clock_gettime:
 
 clock_gettime - Obtain Time of Day
 ----------------------------------
@@ -53,23 +55,25 @@ clock_gettime - Obtain Time of Day
 
 **CALLING SEQUENCE:**
 
-.. code:: c
+.. code-block:: c
 
     #include <time.h>
     int clock_gettime(
-    clockid_t        clock_id,
+        clockid_t        clock_id,
-    struct timespec \*tp
+        struct timespec *tp
     );
 
 **STATUS CODES:**
 
-On error, this routine returns -1 and sets errno to one of the following:
+On error, this routine returns -1 and sets ``errno`` to one of the following:
 
-*EINVAL*
+.. list-table::
-    The tp pointer parameter is invalid.
+ :class: rtems-table
 
-*EINVAL*
+ * - ``EINVAL``
-    The clock_id specified is invalid.
+   - The tp pointer parameter is invalid.
+ * - ``EINVAL``
+   - The clock_id specified is invalid.
 
 **DESCRIPTION:**
 
@@ -77,6 +81,8 @@ On error, this routine returns -1 and sets errno to one of the following:
 
 NONE
 
+.. _clock_settime:
+
 clock_settime - Set Time of Day
 -------------------------------
 .. index:: clock_settime
@@ -84,26 +90,27 @@ clock_settime - Set Time of Day
 
 **CALLING SEQUENCE:**
 
-.. code:: c
+.. code-block:: c
 
     #include <time.h>
     int clock_settime(
-    clockid_t              clock_id,
+        clockid_t              clock_id,
-    const struct timespec \*tp
+        const struct timespec *tp
     );
 
 **STATUS CODES:**
 
-On error, this routine returns -1 and sets errno to one of the following:
+On error, this routine returns -1 and sets ``errno`` to one of the following:
 
-*EINVAL*
+.. list-table::
-    The tp pointer parameter is invalid.
+ :class: rtems-table
 
-*EINVAL*
+ * - ``EINVAL``
-    The clock_id specified is invalid.
+   - The tp pointer parameter is invalid.
-
+ * - ``EINVAL``
-*EINVAL*
+   - The clock_id specified is invalid.
-    The contents of the tp structure are invalid.
+ * - ``EINVAL``
+   - The contents of the tp structure are invalid.
 
 **DESCRIPTION:**
 
@@ -111,6 +118,8 @@ On error, this routine returns -1 and sets errno to one of the following:
 
 NONE
 
+.. _clock_getres:
+
 clock_getres - Get Clock Resolution
 -----------------------------------
 .. index:: clock_getres
@@ -118,29 +127,33 @@ clock_getres - Get Clock Resolution
 
 **CALLING SEQUENCE:**
 
-.. code:: c
+.. code-block:: c
 
     #include <time.h>
     int clock_getres(
-    clockid_t        clock_id,
+        clockid_t        clock_id,
-    struct timespec \*res
+        struct timespec *res
     );
 
 **STATUS CODES:**
 
-On error, this routine returns -1 and sets errno to one of the following:
+On error, this routine returns -1 and sets ``errno`` to one of the following:
 
-*EINVAL*
+.. list-table::
-    The res pointer parameter is invalid.
+ :class: rtems-table
 
-*EINVAL*
+ * - ``EINVAL``
-    The clock_id specified is invalid.
+   - The res pointer parameter is invalid.
+ * - ``EINVAL``
+   - The clock_id specified is invalid.
 
 **DESCRIPTION:**
 
 **NOTES:**
 
-If res is NULL, then the resolution is not returned.
+If ``res`` is ``NULL``, then the resolution is not returned.
+
+.. _sleep:
 
 sleep - Delay Process Execution
 -------------------------------
@@ -149,11 +162,11 @@ sleep - Delay Process Execution
 
 **CALLING SEQUENCE:**
 
-.. code:: c
+.. code-block:: c
 
     #include <unistd.h>
     unsigned int sleep(
-    unsigned int seconds
+        unsigned int seconds
     );
 
 **STATUS CODES:**
@@ -162,13 +175,15 @@ This routine returns the number of unslept seconds.
 
 **DESCRIPTION:**
 
-The ``sleep()`` function delays the calling thread by the specified
+The ``sleep()`` function delays the calling thread by the specified number of
-number of ``seconds``.
+``seconds``.
 
 **NOTES:**
 
 This call is interruptible by a signal.
 
+.. _usleep:
+
 usleep - Delay Process Execution in Microseconds
 ------------------------------------------------
 .. index:: usleep
@@ -179,11 +194,11 @@ usleep - Delay Process Execution in Microseconds
 
 **CALLING SEQUENCE:**
 
-.. code:: c
+.. code-block:: c
 
     #include <time.h>
     useconds_t usleep(
-    useconds_t useconds
+        useconds_t useconds
     );
 
 **STATUS CODES:**
@@ -192,26 +207,27 @@ This routine returns the number of unslept seconds.
 
 **DESCRIPTION:**
 
-The ``sleep()`` function delays the calling thread by the specified
+The ``sleep()`` function delays the calling thread by the specified number of
-number of ``seconds``.
+``seconds``.
 
-The ``usleep()`` function suspends the calling thread from execution
+The ``usleep()`` function suspends the calling thread from execution until
-until either the number of microseconds specified by the``useconds`` argument has elapsed or a signal is delivered to the
+either the number of microseconds specified by the ``useconds`` argument has
-calling thread and its action is to invoke a signal-catching function
+elapsed or a signal is delivered to the calling thread and its action is to
-or to terminate the process.
+invoke a signal-catching function or to terminate the process.
 
-Because of other activity, or because of the time spent in
+Because of other activity, or because of the time spent in processing the call,
-processing the call, the actual length of time the thread is
+the actual length of time the thread is blocked may be longer than the amount
-blocked may be longer than
+of time specified.
-the amount of time specified.
 
 **NOTES:**
 
 This call is interruptible by a signal.
 
-The Single UNIX Specification allows this service to be implemented using
+The Single UNIX Specification allows this service to be implemented using the
-the same timer as that used by the ``alarm()`` service.  This is*NOT* the case for *RTEMS* and this call has no interaction with
+same timer as that used by the ``alarm()`` service.  This is *NOT* the case for
-the ``SIGALRM`` signal.
+*RTEMS* and this call has no interaction with the ``SIGALRM`` signal.
+
+.. _nanosleep:
 
 nanosleep - Delay with High Resolution
 --------------------------------------
@@ -220,27 +236,28 @@ nanosleep - Delay with High Resolution
 
 **CALLING SEQUENCE:**
 
-.. code:: c
+.. code-block:: c
 
     #include <time.h>
     int nanosleep(
-    const struct timespec \*rqtp,
+        const struct timespec *rqtp,
-    struct timespec       \*rmtp
+        struct timespec       *rmtp
     );
 
 **STATUS CODES:**
 
-On error, this routine returns -1 and sets errno to one of the following:
+On error, this routine returns -1 and sets ``errno`` to one of the following:
 
-*EINTR*
+.. list-table::
-    The routine was interrupted by a signal.
+ :class: rtems-table
 
-*EAGAIN*
+ * - ``EINTR``
-    The requested sleep period specified negative seconds or nanoseconds.
+   - The routine was interrupted by a signal.
-
+ * - ``EAGAIN``
-*EINVAL*
+   - The requested sleep period specified negative seconds or nanoseconds.
-    The requested sleep period specified an invalid number for the nanoseconds
+ * - ``EINVAL``
-    field.
+   - The requested sleep period specified an invalid number for the nanoseconds
+     field.
 
 **DESCRIPTION:**
 
@@ -248,6 +265,8 @@ On error, this routine returns -1 and sets errno to one of the following:
 
 This call is interruptible by a signal.
 
+.. _gettimeofday:
+
 gettimeofday - Get the Time of Day
 ----------------------------------
 .. index:: gettimeofday
@@ -255,28 +274,28 @@ gettimeofday - Get the Time of Day
 
 **CALLING SEQUENCE:**
 
-.. code:: c
+.. code-block:: c
 
     #include <sys/time.h>
     #include <unistd.h>
     int gettimeofday(
-    struct timeval  \*tp,
+        struct timeval  *tp,
-    struct timezone \*tzp
+        struct timezone *tzp
     );
 
 **STATUS CODES:**
 
 On error, this routine returns -1 and sets ``errno`` as appropriate.
 
-*EPERM*
+.. list-table::
-    ``settimeofdat`` is called by someone other than the superuser.
+ :class: rtems-table
 
-*EINVAL*
+ * - ``EPERM``
-    Timezone (or something else) is invalid.
+   - ``settimeofdat`` is called by someone other than the superuser.
-
+ * - ``EINVAL``
-*EFAULT*
+   - Timezone (or something else) is invalid.
-    One of ``tv`` or ``tz`` pointed outside your accessible address
+ * - ``EFAULT``
-    space
+   - One of ``tv`` or ``tz`` pointed outside your accessible address space
 
 **DESCRIPTION:**
 
@@ -284,8 +303,10 @@ This routine returns the current time of day in the ``tp`` structure.
 
 **NOTES:**
 
-Currently, the timezone information is not supported. The ``tzp``
+Currently, the timezone information is not supported. The ``tzp`` argument is
-argument is ignored.
+ignored.
+
+.. _time:
 
 time - Get time in seconds
 --------------------------
@@ -294,11 +315,11 @@ time - Get time in seconds
 
 **CALLING SEQUENCE:**
 
-.. code:: c
+.. code-block:: c
 
     #include <time.h>
     int time(
-    time_t \*tloc
+        time_t *tloc
     );
 
 **STATUS CODES:**
@@ -307,17 +328,12 @@ This routine returns the number of seconds since the Epoch.
 
 **DESCRIPTION:**
 
-``time`` returns the time since 00:00:00 GMT, January 1, 1970,
+``time`` returns the time since 00:00:00 GMT, January 1, 1970, measured in
-measured in seconds
+seconds
 
-If ``tloc`` in non null, the return value is also stored in the
+If ``tloc`` in non null, the return value is also stored in the memory pointed
-memory pointed to by ``t``.
+to by ``t``.
 
 **NOTES:**
 
 NONE
-
-.. COMMENT: This is the chapter from the RTEMS POSIX 1003.1b API User's Guide that
-
-.. COMMENT: documents the services provided by the timer @c  manager.
-

posix_users/condition_variable.rst

@@ -1,3 +1,7 @@
+.. COMMENT: COPYRIGHT (c) 1988-2002.
+.. COMMENT: On-Line Applications Research Corporation (OAR).
+.. COMMENT: All rights reserved.
+
 Condition Variable Manager
 ##########################
 
@@ -8,25 +12,25 @@ The condition variable manager ...
 
 The directives provided by the condition variable manager are:
 
-- ``pthread_condattr_init`` - Initialize a Condition Variable Attribute Set
+- pthread_condattr_init_ - Initialize a Condition Variable Attribute Set
 
-- ``pthread_condattr_destroy`` - Destroy a Condition Variable Attribute Set
+- pthread_condattr_destroy_ - Destroy a Condition Variable Attribute Set
 
-- ``pthread_condattr_setpshared`` - Set Process Shared Attribute
+- pthread_condattr_setpshared_ - Set Process Shared Attribute
 
-- ``pthread_condattr_getpshared`` - Get Process Shared Attribute
+- pthread_condattr_getpshared_ - Get Process Shared Attribute
 
-- ``pthread_cond_init`` - Initialize a Condition Variable
+- pthread_cond_init_ - Initialize a Condition Variable
 
-- ``pthread_cond_destroy`` - Destroy a Condition Variable
+- pthread_cond_destroy_ - Destroy a Condition Variable
 
-- ``pthread_cond_signal`` - Signal a Condition Variable
+- pthread_cond_signal_ - Signal a Condition Variable
 
-- ``pthread_cond_broadcast`` - Broadcast a Condition Variable
+- pthread_cond_broadcast_ - Broadcast a Condition Variable
 
-- ``pthread_cond_wait`` - Wait on a Condition Variable
+- pthread_cond_wait_ - Wait on a Condition Variable
 
-- ``pthread_cond_timedwait`` - With with Timeout a Condition Variable
+- pthread_cond_timedwait_ - With with Timeout a Condition Variable
 
 Background
 ==========
@@ -41,10 +45,11 @@ There is currently no text in this section.
 Directives
 ==========
 
-This section details the condition variable manager's directives.
+This section details the condition variable manager's directives.  A subsection
-A subsection is dedicated to each of this manager's directives
+is dedicated to each of this manager's directives and describes the calling
-and describes the calling sequence, related constants, usage,
+sequence, related constants, usage, and status codes.
-and status codes.
+
+.. _pthread_condattr_init:
 
 pthread_condattr_init - Initialize a Condition Variable Attribute Set
 ---------------------------------------------------------------------
@@ -53,23 +58,25 @@ pthread_condattr_init - Initialize a Condition Variable Attribute Set
 
 **CALLING SEQUENCE:**
 
-.. code:: c
+.. code-block:: c
 
     #include <pthread.h>
     int pthread_condattr_init(
-    pthread_condattr_t \*attr
+        pthread_condattr_t *attr
     );
 
 **STATUS CODES:**
 
-*ENOMEM*
+ * - ``ENOMEM``
-    Insufficient memory is available to initialize the condition variable
+   - Insufficient memory is available to initialize the condition variable
-    attributes object.
+     attributes object.
 
 **DESCRIPTION:**
 
 **NOTES:**
 
+.. _pthread_condattr_destroy:
+
 pthread_condattr_destroy - Destroy a Condition Variable Attribute Set
 ---------------------------------------------------------------------
 .. index:: pthread_condattr_destroy
@@ -77,22 +84,27 @@ pthread_condattr_destroy - Destroy a Condition Variable Attribute Set
 
 **CALLING SEQUENCE:**
 
-.. code:: c
+.. code-block:: c
 
     #include <pthread.h>
     int pthread_condattr_destroy(
-    pthread_condattr_t \*attr
+        pthread_condattr_t *attr
     );
 
 **STATUS CODES:**
 
-*EINVAL*
+.. list-table::
-    The attribute object specified is invalid.
+ :class: rtems-table
+
+ * - ``EINVAL``
+   - The attribute object specified is invalid.
 
 **DESCRIPTION:**
 
 **NOTES:**
 
+.. _pthread_condattr_setpshared:
+
 pthread_condattr_setpshared - Set Process Shared Attribute
 ----------------------------------------------------------
 .. index:: pthread_condattr_setpshared
@@ -100,23 +112,28 @@ pthread_condattr_setpshared - Set Process Shared Attribute
 
 **CALLING SEQUENCE:**
 
-.. code:: c
+.. code-block:: c
 
     #include <pthread.h>
     int pthread_condattr_setpshared(
-    pthread_condattr_t \*attr,
+        pthread_condattr_t *attr,
-    int                 pshared
+        int                 pshared
     );
 
 **STATUS CODES:**
 
-*EINVAL*
+.. list-table::
-    Invalid argument passed.
+ :class: rtems-table
+
+ * - ``EINVAL``
+   - Invalid argument passed.
 
 **DESCRIPTION:**
 
 **NOTES:**
 
+.. _pthread_condattr_getpshared:
+
 pthread_condattr_getpshared - Get Process Shared Attribute
 ----------------------------------------------------------
 .. index:: pthread_condattr_getpshared
@@ -124,23 +141,28 @@ pthread_condattr_getpshared - Get Process Shared Attribute
 
 **CALLING SEQUENCE:**
 
-.. code:: c
+.. code-block:: c
 
     #include <pthread.h>
     int pthread_condattr_getpshared(
-    const pthread_condattr_t \*attr,
+        const pthread_condattr_t *attr,
-    int                      \*pshared
+        int                      *pshared
     );
 
 **STATUS CODES:**
 
-*EINVAL*
+.. list-table::
-    Invalid argument passed.
+ :class: rtems-table
+
+ * - ``EINVAL``
+   - Invalid argument passed.
 
 **DESCRIPTION:**
 
 **NOTES:**
 
+.. _pthread_cond_init:
+
 pthread_cond_init - Initialize a Condition Variable
 ---------------------------------------------------
 .. index:: pthread_cond_init
@@ -148,33 +170,36 @@ pthread_cond_init - Initialize a Condition Variable
 
 **CALLING SEQUENCE:**
 
-.. code:: c
+.. code-block:: c
 
     #include <pthread.h>
     int pthread_cond_init(
-    pthread_cond_t           \*cond,
+        pthread_cond_t           *cond,
-    const pthread_condattr_t \*attr
+        const pthread_condattr_t *attr
     );
 
 **STATUS CODES:**
 
-*EAGAIN*
+.. list-table::
-    The system lacked a resource other than memory necessary to create the
+ :class: rtems-table
-    initialize the condition variable object.
 
-*ENOMEM*
+ * - ``EAGAIN``
-    Insufficient memory is available to initialize the condition variable object.
+   - The system lacked a resource other than memory necessary to create the
-
+     initialize the condition variable object.
-*EBUSY*
+ * - ``ENOMEM``
-    The specified condition variable has already been initialized.
+   - Insufficient memory is available to initialize the condition variable
-
+     object.
-*EINVAL*
+ * - ``EBUSY``
-    The specified attribute value is invalid.
+   - The specified condition variable has already been initialized.
+ * - ``EINVAL``
+   - The specified attribute value is invalid.
 
 **DESCRIPTION:**
 
 **NOTES:**
 
+.. _pthread_cond_destroy:
+
 pthread_cond_destroy - Destroy a Condition Variable
 ---------------------------------------------------
 .. index:: pthread_cond_destroy
@@ -182,25 +207,29 @@ pthread_cond_destroy - Destroy a Condition Variable
 
 **CALLING SEQUENCE:**
 
-.. code:: c
+.. code-block:: c
 
     #include <pthread.h>
     int pthread_cond_destroy(
-    pthread_cond_t \*cond
+        pthread_cond_t *cond
     );
 
 **STATUS CODES:**
 
-*EINVAL*
+.. list-table::
-    The specified condition variable is invalid.
+ :class: rtems-table
 
-*EBUSY*
+ * - ``EINVAL``
-    The specified condition variable is currently in use.
+   - The specified condition variable is invalid.
+ * - ``EBUSY``
+   - The specified condition variable is currently in use.
 
 **DESCRIPTION:**
 
 **NOTES:**
 
+.. _pthread_cond_signal:
+
 pthread_cond_signal - Signal a Condition Variable
 -------------------------------------------------
 .. index:: pthread_cond_signal
@@ -208,17 +237,20 @@ pthread_cond_signal - Signal a Condition Variable
 
 **CALLING SEQUENCE:**
 
-.. code:: c
+.. code-block:: c
 
     #include <pthread.h>
     int pthread_cond_signal(
-    pthread_cond_t \*cond
+        pthread_cond_t *cond
     );
 
 **STATUS CODES:**
 
-*EINVAL*
+.. list-table::
-    The specified condition variable is not valid.
+ :class: rtems-table
+
+ * - ``EINVAL``
+   - The specified condition variable is not valid.
 
 **DESCRIPTION:**
 
@@ -227,6 +259,8 @@ pthread_cond_signal - Signal a Condition Variable
 This routine should not be invoked from a handler from an asynchronous signal
 handler or an interrupt service routine.
 
+.. _pthread_cond_broadcast:
+
 pthread_cond_broadcast - Broadcast a Condition Variable
 -------------------------------------------------------
 .. index:: pthread_cond_broadcast
@@ -234,17 +268,20 @@ pthread_cond_broadcast - Broadcast a Condition Variable
 
 **CALLING SEQUENCE:**
 
-.. code:: c
+.. code-block:: c
 
     #include <pthread.h>
     int pthread_cond_broadcast(
-    pthread_cond_t \*cond
+        pthread_cond_t *cond
     );
 
 **STATUS CODES:**
 
-*EINVAL*
+.. list-table::
-    The specified condition variable is not valid.
+ :class: rtems-table
+
+ * - ``EINVAL``
+   - The specified condition variable is not valid.
 
 **DESCRIPTION:**
 
@@ -253,6 +290,8 @@ pthread_cond_broadcast - Broadcast a Condition Variable
 This routine should not be invoked from a handler from an asynchronous signal
 handler or an interrupt service routine.
 
+.. _pthread_cond_wait:
+
 pthread_cond_wait - Wait on a Condition Variable
 ------------------------------------------------
 .. index:: pthread_cond_wait
@@ -260,26 +299,31 @@ pthread_cond_wait - Wait on a Condition Variable
 
 **CALLING SEQUENCE:**
 
-.. code:: c
+.. code-block:: c
 
     #include <pthread.h>
     int pthread_cond_wait(
-    pthread_cond_t \*cond,
+        pthread_cond_t *cond,
-    pthread_mutex_t \*mutex
+        pthread_mutex_t *mutex
     );
 
 **STATUS CODES:**
 
-*EINVAL*
+.. list-table::
-    The specified condition variable or mutex is not initialized OR different
+ :class: rtems-table
-    mutexes were specified for concurrent pthread_cond_wait() and
+
-    pthread_cond_timedwait() operations on the same condition variable OR
+ * - ``EINVAL``
-    the mutex was not owned by the current thread at the time of the call.
+   - The specified condition variable or mutex is not initialized OR different
+     mutexes were specified for concurrent ``pthread_cond_wait()`` and
+     ``pthread_cond_timedwait()`` operations on the same condition variable OR
+     the mutex was not owned by the current thread at the time of the call.
 
 **DESCRIPTION:**
 
 **NOTES:**
 
+.. _pthread_cond_timedwait:
+
 pthread_cond_timedwait - Wait with Timeout a Condition Variable
 ---------------------------------------------------------------
 .. index:: pthread_cond_timedwait
@@ -287,34 +331,29 @@ pthread_cond_timedwait - Wait with Timeout a Condition Variable
 
 **CALLING SEQUENCE:**
 
-.. code:: c
+.. code-block:: c
 
     #include <pthread.h>
     int pthread_cond_timedwait(
-    pthread_cond_t        \*cond,
+        pthread_cond_t        *cond,
-    pthread_mutex_t       \*mutex,
+        pthread_mutex_t       *mutex,
-    const struct timespec \*abstime
+        const struct timespec *abstime
     );
 
 **STATUS CODES:**
 
-*EINVAL*
+.. list-table::
-    The specified condition variable or mutex is not initialized OR different
+ :class: rtems-table
-    mutexes were specified for concurrent pthread_cond_wait() and
-    pthread_cond_timedwait() operations on the same condition variable OR
-    the mutex was not owned by the current thread at the time of the call.
 
-*ETIMEDOUT*
+ * - ``EINVAL``
-    The specified time has elapsed without the condition variable being
+   - The specified condition variable or mutex is not initialized OR different
-    satisfied.
+     mutexes were specified for concurrent ``pthread_cond_wait()`` and
+     ``pthread_cond_timedwait()`` operations on the same condition variable OR
+     the mutex was not owned by the current thread at the time of the call.
+ * - ``ETIMEDOUT``
+   - The specified time has elapsed without the condition variable being
+     satisfied.
 
 **DESCRIPTION:**
 
 **NOTES:**
-
-.. COMMENT: COPYRIGHT (c) 1988-2002.
-
-.. COMMENT: On-Line Applications Research Corporation (OAR).
-
-.. COMMENT: All rights reserved.
-

posix_users/device_and_class_specific.rst

@@ -1,3 +1,7 @@
+.. COMMENT: COPYRIGHT (c) 1988-2002.
+.. COMMENT: On-Line Applications Research Corporation (OAR).
+.. COMMENT: All rights reserved.
+
 Device- and Class- Specific Functions Manager
 #############################################
 
@@ -6,32 +10,32 @@ Introduction
 
 The device- and class- specific functions manager is ...
 
-The directives provided by the device- and class- specific functions
+The directives provided by the device- and class- specific functions manager
-manager are:
+are:
 
-- ``cfgetispeed`` - Reads terminal input baud rate
+- cfgetispeed_ - Reads terminal input baud rate
 
-- ``cfgetospeed`` - Reads terminal output baud rate
+- cfgetospeed_ - Reads terminal output baud rate
 
-- ``cfsetispeed`` - Sets terminal input baud rate
+- cfsetispeed_ - Sets terminal input baud rate
 
-- ``cfsetospeed`` - Set terminal output baud rate
+- cfsetospeed_ - Set terminal output baud rate
 
-- ``tcgetattr`` - Gets terminal attributes
+- tcgetattr_ - Gets terminal attributes
 
-- ``tcsetattr`` - Set terminal attributes
+- tcsetattr_ - Set terminal attributes
 
-- ``tcsendbreak`` - Sends a break to a terminal
+- tcsendbreak_ - Sends a break to a terminal
 
-- ``tcdrain`` - Waits for all output to be transmitted to the terminal
+- tcdrain_ - Waits for all output to be transmitted to the terminal
 
-- ``tcflush`` - Discards terminal data
+- tcflush_ - Discards terminal data
 
-- ``tcflow`` - Suspends/restarts terminal output
+- tcflow_ - Suspends/restarts terminal output
 
-- ``tcgetpgrp`` - Gets foreground process group ID
+- tcgetpgrp_ - Gets foreground process group ID
 
-- ``tcsetpgrp`` - Sets foreground process group ID
+- tcsetpgrp_ - Sets foreground process group ID
 
 Background
 ==========
@@ -51,6 +55,8 @@ directives. A subsection is dedicated to each of this manager's directives
 and describes the calling sequence, related constants, usage,
 and status codes.
 
+.. _cfgetispeed:
+
 cfgetispeed - Reads terminal input baud rate
 --------------------------------------------
 .. index:: cfgetispeed
@@ -58,11 +64,11 @@ cfgetispeed - Reads terminal input baud rate
 
 **CALLING SEQUENCE:**
 
-.. code:: c
+.. code-block:: c
 
     #include <termios.h>
     int cfgetispeed(
-    const struct termios \*p
+        const struct termios *p
     );
 
 **STATUS CODES:**
@@ -71,18 +77,21 @@ The ``cfgetispeed()`` function returns a code for baud rate.
 
 **DESCRIPTION:**
 
-The ``cfsetispeed()`` function stores a code for the terminal speed
+The ``cfsetispeed()`` function stores a code for the terminal speed stored in a
-stored in a struct termios. The codes are defined in ``<termios.h>``
+struct termios. The codes are defined in ``<termios.h>`` by the macros ``BO``,
-by the macros BO, B50, B75, B110, B134, B150, B200, B300, B600, B1200,
+``B50``, ``B75``, ``B110``, ``B134``, ``B150``, ``B200``, ``B300``, ``B600``,
-B1800, B2400, B4800, B9600, B19200, and B38400.
+``B1200``, ``B1800``, ``B2400``, ``B4800``, ``B9600``, ``B19200``, and
+``B38400``.
 
-The ``cfsetispeed()`` function does not do anything to the hardware.
+The ``cfsetispeed()`` function does not do anything to the hardware.  It merely
-It merely stores a value for use by ``tcsetattr()``.
+stores a value for use by ``tcsetattr()``.
 
 **NOTES:**
 
-Baud rates are defined by symbols, such as B110, B1200, B2400. The actual
+Baud rates are defined by symbols, such as ``B110``, ``B1200``, ``B2400``. The
-number returned for any given speed may change from system to system.
+actual number returned for any given speed may change from system to system.
+
+.. _cfgetospeed:
 
 cfgetospeed - Reads terminal output baud rate
 ---------------------------------------------
@@ -91,11 +100,11 @@ cfgetospeed - Reads terminal output baud rate
 
 **CALLING SEQUENCE:**
 
-.. code:: c
+.. code-block:: c
 
     #include <termios.h>
-    int cfgetospeed(
+        int cfgetospeed(
-    const struct termios \*p
+        const struct termios *p
     );
 
 **STATUS CODES:**
@@ -104,18 +113,21 @@ The ``cfgetospeed()`` function returns the termios code for the baud rate.
 
 **DESCRIPTION:**
 
-The ``cfgetospeed()`` function returns a code for the terminal speed
+The ``cfgetospeed()`` function returns a code for the terminal speed stored in
-stored in a ``struct termios``. The codes are defined in ``<termios.h>``
+a ``struct termios``. The codes are defined in ``<termios.h>`` by the macros
-by the macros BO, B50, B75, B110, B134, B150, B200, B300, B600, B1200, B1800,
+``BO``, ``B50``, ``B75``, ``B110``, ``B134``, ``B150``, ``B200``, ``B300``,
-B2400, B4800, B9600, B19200, and B38400.
+``B600``, ``B1200``, ``B1800``, ``B2400``, ``B4800``, ``B9600``, ``B19200``,
+and ``B38400``.
 
-The ``cfgetospeed()`` function does not do anything to the hardware.
+The ``cfgetospeed()`` function does not do anything to the hardware.  It merely
-It merely returns the value stored by a previous call to ``tcgetattr()``.
+returns the value stored by a previous call to ``tcgetattr()``.
 
 **NOTES:**
 
-Baud rates are defined by symbols, such as B110, B1200, B2400. The actual
+Baud rates are defined by symbols, such as ``B110``, ``B1200``, ``B2400``. The
-number returned for any given speed may change from system to system.
+actual number returned for any given speed may change from system to system.
+
+.. _cfsetispeed:
 
 cfsetispeed - Sets terminal input baud rate
 -------------------------------------------
@@ -124,31 +136,34 @@ cfsetispeed - Sets terminal input baud rate
 
 **CALLING SEQUENCE:**
 
-.. code:: c
+.. code-block:: c
 
     #include <termios.h>
     int cfsetispeed(
-    struct termios \*p,
+        struct termios *p,
-    speed_t         speed
+        speed_t         speed
     );
 
 **STATUS CODES:**
 
-The ``cfsetispeed()`` function returns a zero when successful and
+The ``cfsetispeed()`` function returns a zero when successful and returns -1
-returns -1 when an error occurs.
+when an error occurs.
 
 **DESCRIPTION:**
 
-The ``cfsetispeed()`` function stores a code for the terminal speed
+The ``cfsetispeed()`` function stores a code for the terminal speed stored in a
-stored in a struct termios. The codes are defined in ``<termios.h>``
+struct termios. The codes are defined in ``<termios.h>`` by the macros ``BO``,
-by the macros B0, B50, B75, B110, B134, B150, B200, B300, B600, B1200,
+``B50``, ``B75``, ``B110``, ``B134``, ``B150``, ``B200``, ``B300``, ``B600``,
-B1800, B2400, B4800, B9600, B19200, and B38400.
+``B1200``, ``B1800``, ``B2400``, ``B4800``, ``B9600``, ``B19200``, and
+``B38400``.
 
 **NOTES:**
 
-This function merely stores a value in the ``termios`` structure. It
+This function merely stores a value in the ``termios`` structure. It does not
-does not change the terminal speed until a ``tcsetattr()`` is done.
+change the terminal speed until a ``tcsetattr()`` is done.  It does not detect
-It does not detect impossible terminal speeds.
+impossible terminal speeds.
+
+.. _cfsetospeed:
 
 cfsetospeed - Sets terminal output baud rate
 --------------------------------------------
@@ -157,12 +172,12 @@ cfsetospeed - Sets terminal output baud rate
 
 **CALLING SEQUENCE:**
 
-.. code:: c
+.. code-block:: c
 
     #include <termios.h>
     int cfsetospeed(
-    struct termios \*p,
+        struct termios *p,
-    speed_t         speed
+        speed_t         speed
     );
 
 **STATUS CODES:**
@@ -172,19 +187,22 @@ returns -1 when an error occurs.
 
 **DESCRIPTION:**
 
-The ``cfsetospeed()`` function stores a code for the terminal speed stored
+The ``cfsetospeed()`` function stores a code for the terminal speed stored in a
-in a struct ``termios``. The codes are defiined in ``<termios.h>`` by the
+struct ``termios``. The codes are defiined in ``<termios.h>`` by the macros
-macros B0, B50, B75, B110, B134, B150, B200, B300, B600, B1200, B1800, B2400,
+``BO``, ``B50``, ``B75``, ``B110``, ``B134``, ``B150``, ``B200``, ``B300``,
-B4800, B9600, B19200, and B38400.
+``B600``, ``B1200``, ``B1800``, ``B2400``, ``B4800``, ``B9600``, ``B19200``,
+and ``B38400``.
 
-The ``cfsetospeed()`` function does not do anything to the hardware. It
+The ``cfsetospeed()`` function does not do anything to the hardware. It merely
-merely stores a value for use by ``tcsetattr()``.
+stores a value for use by ``tcsetattr()``.
 
 **NOTES:**
 
-This function merely stores a value in the ``termios`` structure.
+This function merely stores a value in the ``termios`` structure.  It does not
-It does not change the terminal speed until a ``tcsetattr()`` is done.
+change the terminal speed until a ``tcsetattr()`` is done.  It does not detect
-It does not detect impossible terminal speeds.
+impossible terminal speeds.
+
+.. _tcgetattr:
 
 tcgetattr - Gets terminal attributes
 ------------------------------------
@@ -193,33 +211,37 @@ tcgetattr - Gets terminal attributes
 
 **CALLING SEQUENCE:**
 
-.. code:: c
+.. code-block:: c
 
     #include <termios.h>
     #include <unistd.h>
     int tcgetattr(
-    int             fildes,
+        int             fildes,
-    struct termios \*p
+        struct termios *p
     );
 
 **STATUS CODES:**
 
-*EBADF*
+.. list-table::
-    Invalid file descriptor
+ :class: rtems-table
 
-*ENOOTY*
+ * - ``EBADF``
-    Terminal control function attempted for a file that is not a terminal.
+   - Invalid file descriptor
+ * - ``ENOOTY``
+   - Terminal control function attempted for a file that is not a terminal.
 
 **DESCRIPTION:**
 
-The ``tcgetattr()`` gets the parameters associated with the terminal
+The ``tcgetattr()`` gets the parameters associated with the terminal referred
-referred to by ``fildes`` and stores them into the ``termios()``
+to by ``fildes`` and stores them into the ``termios()`` structure pointed to by
-structure pointed to by ``termios_p``.
+``termios_p``.
 
 **NOTES:**
 
 NONE
 
+.. _tcsetattr:
+
 tcsetattr - Set terminal attributes
 -----------------------------------
 .. index:: tcsetattr
@@ -227,25 +249,30 @@ tcsetattr - Set terminal attributes
 
 **CALLING SEQUENCE:**
 
-.. code:: c
+.. code-block:: c
 
     #include <termios.h>
     #include <unistd.h>
     int tcsetattr(
-    int                   fildes,
+        int                   fildes,
-    int                   options,
+        int                   options,
-    const struct termios \*tp
+        const struct termios *tp
     );
 
 **STATUS CODES:**
 
-*E*
+.. list-table::
-    The
+ :class: rtems-table
+
+ * - ``E``
+   - The
 
 **DESCRIPTION:**
 
 **NOTES:**
 
+.. _tcsendbreak:
+
 tcsendbreak - Sends a break to a terminal
 -----------------------------------------
 .. index:: tcsendbreak
@@ -253,16 +280,19 @@ tcsendbreak - Sends a break to a terminal
 
 **CALLING SEQUENCE:**
 
-.. code:: c
+.. code-block:: c
 
     int tcsendbreak(
-    int fd
+        int fd
     );
 
 **STATUS CODES:**
 
-*E*
+.. list-table::
-    The
+ :class: rtems-table
+
+ * - ``E``
+   - The
 
 **DESCRIPTION:**
 
@@ -271,6 +301,8 @@ tcsendbreak - Sends a break to a terminal
 This routine is not currently supported by RTEMS but could be
 in a future version.
 
+.. _tcdrain:
+
 tcdrain - Waits for all output to be transmitted to the terminal.
 -----------------------------------------------------------------
 .. index:: tcdrain
@@ -278,33 +310,37 @@ tcdrain - Waits for all output to be transmitted to the terminal.
 
 **CALLING SEQUENCE:**
 
-.. code:: c
+.. code-block:: c
 
     #include <termios.h>
     #include <unistd.h>
     int tcdrain(
-    int fildes
+        int fildes
     );
 
 **STATUS CODES:**
 
-*EBADF*
+.. list-table::
-    Invalid file descriptor
+ :class: rtems-table
 
-*EINTR*
+ * - ``EBADF``
-    Function was interrupted by a signal
+   - Invalid file descriptor
-
+ * - ``EINTR``
-*ENOTTY*
+   - Function was interrupted by a signal
-    Terminal control function attempted for a file that is not a terminal.
+ * - ``ENOTTY``
+   - Terminal control function attempted for a file that is not a terminal.
 
 **DESCRIPTION:**
 
-The ``tcdrain()`` function waits until all output written to``fildes`` has been transmitted.
+The ``tcdrain()`` function waits until all output written to ``fildes`` has been
+transmitted.
 
 **NOTES:**
 
 NONE
 
+.. _tcflush:
+
 tcflush - Discards terminal data
 --------------------------------
 .. index:: tcflush
@@ -312,23 +348,28 @@ tcflush - Discards terminal data
 
 **CALLING SEQUENCE:**
 
-.. code:: c
+.. code-block:: c
 
     int tcflush(
-    int fd
+        int fd
     );
 
 **STATUS CODES:**
 
-*E*
+.. list-table::
-    The
+ :class: rtems-table
+
+ * - ``E``
+   - The
 
 **DESCRIPTION:**
 
 **NOTES:**
 
-This routine is not currently supported by RTEMS but could be
+This routine is not currently supported by RTEMS but could be in a future
-in a future version.
+version.
+
+.. _tcflow:
 
 tcflow - Suspends/restarts terminal output.
 -------------------------------------------
@@ -337,23 +378,28 @@ tcflow - Suspends/restarts terminal output.
 
 **CALLING SEQUENCE:**
 
-.. code:: c
+.. code-block:: c
 
     int tcflow(
-    int fd
+        int fd
     );
 
 **STATUS CODES:**
 
-*E*
+.. list-table::
-    The
+ :class: rtems-table
+
+ * - ``E``
+   - The
 
 **DESCRIPTION:**
 
 **NOTES:**
 
-This routine is not currently supported by RTEMS but could be
+This routine is not currently supported by RTEMS but could be in a future
-in a future version.
+version.
+
+.. _tcgetpgrp:
 
 tcgetpgrp - Gets foreground process group ID
 --------------------------------------------
@@ -362,22 +408,27 @@ tcgetpgrp - Gets foreground process group ID
 
 **CALLING SEQUENCE:**
 
-.. code:: c
+.. code-block:: c
 
     int tcgetpgrp(
     );
 
 **STATUS CODES:**
 
-*E*
+.. list-table::
-    The
+ :class: rtems-table
+
+ * - ``E``
+   - The
 
 **DESCRIPTION:**
 
 **NOTES:**
 
-This routine is not currently supported by RTEMS but could be
+This routine is not currently supported by RTEMS but could be in a future
-in a future version.
+version.
+
+.. _tcsetpgrp:
 
 tcsetpgrp - Sets foreground process group ID
 --------------------------------------------
@@ -386,26 +437,22 @@ tcsetpgrp - Sets foreground process group ID
 
 **CALLING SEQUENCE:**
 
-.. code:: c
+.. code-block:: c
 
     int tcsetpgrp(
     );
 
 **STATUS CODES:**
 
-*E*
+.. list-table::
-    The
+ :class: rtems-table
+
+ * - ``E``
+   - The
 
 **DESCRIPTION:**
 
 **NOTES:**
 
-This routine is not currently supported by RTEMS but could be
+This routine is not currently supported by RTEMS but could be in a future
-in a future version.
+version.
-
-.. COMMENT: COPYRIGHT (c) 1988-2002.
-
-.. COMMENT: On-Line Applications Research Corporation (OAR).
-
-.. COMMENT: All rights reserved.
-

posix_users/index.rst

@@ -2,45 +2,41 @@
 RTEMS POSIX API User's Guide
 ============================
 
-COPYRIGHT (c) 1988 - 2015.
+RTEMS POSIX API User's Guide
+----------------------------
 
-On-Line Applications Research Corporation (OAR).
+ | COPYRIGHT (c) 1988 - 2015.
+ | On-Line Applications Research Corporation (OAR).
 
-The authors have used their best efforts in preparing
+The authors have used their best efforts in preparing this material.  These
-this material.  These efforts include the development, research,
+efforts include the development, research, and testing of the theories and
-and testing of the theories and programs to determine their
+programs to determine their effectiveness.  No warranty of any kind, expressed
-effectiveness.  No warranty of any kind, expressed or implied,
+or implied, with regard to the software or the material contained in this
-with regard to the software or the material contained in this
+document is provided.  No liability arising out of the application or use of
-document is provided.  No liability arising out of the
+any product described in this document is assumed.  The authors reserve the
-application or use of any product described in this document is
+right to revise this material and to make changes from time to time in the
-assumed.  The authors reserve the right to revise this material
+content hereof without obligation to notify anyone of such revision or changes.
-and to make changes from time to time in the content hereof
-without obligation to notify anyone of such revision or changes.
 
-The RTEMS Project is hosted at http://www.rtems.org.  Any
+The RTEMS Project is hosted at http://www.rtems.org/.  Any inquiries concerning
-inquiries concerning RTEMS, its related support components, or its
+RTEMS, its related support components, or its documentation should be directed
-documentation should be directed to the Community Project hosted athttp://www.rtems.org.
+to the Community Project hosted at http://www.rtems.org/.
 
-Any inquiries for commercial services including training, support, custom
+.. topic:: RTEMS Online Resources
-development, application development assistance should be directed tohttp://www.rtems.com.
-
-.. COMMENT: This prevents a black box from being printed on "overflow" lines.
-
-.. COMMENT: The alternative is to rework a sentence to avoid this problem.
-
-
-Table of Contents
------------------
-
-.. toctree::
-
-	preface
 
+  ================  =============================
+  Home              https://www.rtems.org/
+  Developers        https://devel.rtems.org/
+  Documentation     https://docs.rtems.org/
+  Bug Reporting     https://devel.rtems.org/query
+  Mailing Lists     https://lists.rtems.org/
+  Git Repositories  https://git.rtems.org/
+  ================  =============================
 
 .. toctree::
 	:maxdepth: 3
 	:numbered:
 
+	preface
 	process_creation_and_execution
 	signal
 	process_environment
@@ -65,6 +61,5 @@ Table of Contents
 	status_of_implementation
 	command
 
-
 *	:ref:`genindex`
 *	:ref:`search`

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.
+This section details the key manager's directives.  A subsection is dedicated
-A subsection is dedicated to each of this manager's directives
+to each of this manager's directives and describes the calling sequence,
-and describes the calling sequence, related constants, usage,
+related constants, usage, and status codes.
-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,
+        pthread_key_t *key,
-    void (\*destructor)( void )
+        void (*destructor)( void )
     );
 
 **STATUS CODES:**
 
-*EAGAIN*
+.. list-table::
-    There were not enough resources available to create another key.
+ :class: rtems-table
 
-*ENOMEM*
+ * - ``EAGAIN``
-    Insufficient memory exists to create the key.
+   - 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
+The ``pthread_key_create()`` function shall create a thread-specific data key
-key visible to all threads in the process. Key values provided by
+visible to all threads in the process. Key values provided by
-pthread_key_create() are opaque objects used to locate thread-specific
+``pthread_key_create()`` are opaque objects used to locate thread-specific
-data. Although the same key value may be used by different threads, the
+data. Although the same key value may be used by different threads, the values
-values bound to the key by pthread_setspecific() are maintained on a
+bound to the key by ``pthread_setspecific()`` are maintained on a per-thread
-per-thread basis and persist for the life of the calling thread.
+basis and persist for the life of the calling thread.
 
-Upon key creation, the value NULL shall be associated with the new key
+Upon key creation, the value ``NULL`` shall be associated with the new key in
-in all active threads. Upon thread creation, the value NULL shall be
+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.
+An optional destructor function may be associated with each key value.  At
-At thread exit, if a key value has a non-NULL destructor pointer, and
+thread exit, if a key value has a non-``NULL`` destructor pointer, and the
-the thread has a non-NULL value associated with that key, the value of
+thread has a non-``NULL`` value associated with that key, the value of the key
-the key is set to NULL, and then the function pointed to is called with
+is set to NULL, and then the function pointed to is called with the previously
-the previously associated value as its sole argument. The order of
+associated value as its sole argument. The order of destructor calls is
-destructor calls is unspecified if more than one destructor exists for
+unspecified if more than one destructor exists for a thread when it exits.
-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*
+.. list-table::
-    The key was invalid
+ :class: rtems-table
+
+ * - ``EINVAL``
+   - The key was invalid
 
 **DESCRIPTION:**
 
-The pthread_key_delete() function shall delete a thread-specific data key
+The ``pthread_key_delete()`` function shall delete a thread-specific data key
-previously returned by pthread_key_create(). The thread-specific data
+previously returned by ``pthread_key_create()``. The thread-specific data
-values associated with key need not be NULL at the time pthread_key_delete()
+values associated with key need not be NULL at the time
-is called. It is the responsibility of the application to free any
+``pthread_key_delete()`` is called. It is the responsibility of the application
-application storage or perform any cleanup actions for data structures related
+to free any application storage or perform any cleanup actions for data
-to the deleted key or associated thread-specific data in any
+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()`` is called. Any attempt to use key following the call
-pthread_key_delete() results in undefined behavior.
+to ``pthread_key_delete()`` results in undefined behavior.
 
 **NOTES:**
 
-The pthread_key_delete() function shall be callable from within
+The ``pthread_key_delete()`` function shall be callable from within destructor
-destructor functions. No destructor functions shall be invoked by
+functions. No destructor functions shall be invoked by
-pthread_key_delete(). Any destructor function that may have been
+``pthread_key_delete()``. Any destructor function that may have been associated
-associated with key shall no longer be called upon thread exit.
+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,
+        pthread_key_t  key,
-    const void \*value
+        const void    *value
     );
 
 **STATUS CODES:**
 
-*EINVAL*
+.. list-table::
-    The specified key is invalid.
+ :class: rtems-table
+
+ * - ``EINVAL``
+   - The specified key is invalid.
 
 **DESCRIPTION:**
 
-The pthread_setspecific() function shall associate a thread-specific value
+The ``pthread_setspecific()`` function shall associate a thread-specific value
-with a key obtained via a previous call to pthread_key_create().
+with a key obtained via a previous call to ``pthread_key_create()``.  Different
-Different threads may bind different values to the same key. These values
+threads may bind different values to the same key. These values are typically
-are typically pointers to blocks of dynamically allocated memory that
+pointers to blocks of dynamically allocated memory that have been reserved for
-have been reserved for use by the calling thread.
+use by the calling thread.
 
 **NOTES:**
 
-The effect of calling pthread_setspecific() with a key value not obtained
+The effect of calling ``pthread_setspecific()`` with a key value not obtained
-from pthread_key_create() or after key has
+from ``pthread_key_create()`` or after key has been deleted with
-been deleted with pthread_key_delete() is undefined.
+``pthread_key_delete()`` is undefined.
 
-pthread_setspecific() may be called from a thread-specific data
+``pthread_setspecific()`` may be called from a thread-specific data destructor
-destructor function. Calling pthread_setspecific() from a thread-specific
+function. Calling ``pthread_setspecific()`` from a thread-specific data
-data destructor routine may result either in lost storage (after at least
+destructor routine may result either in lost storage (after at least
-PTHREAD_DESTRUCTOR_ITERATIONS attempts at destruction) or in an infinite loop.
+``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(
+    void *pthread_getspecific(
-    pthread_key_t key
+        pthread_key_t key
     );
 
 **STATUS CODES:**
 
-*NULL*
+.. list-table::
-    There is no thread-specific data associated with the specified key.
+ :class: rtems-table
 
-*non-NULL*
+ * - ``NULL``
-    The data associated with the specified key.
+   - 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 ``pthread_getspecific()`` function shall return the value currently bound
-the specified key on behalf of the calling thread.
+to the specified key on behalf of the calling thread.
 
 **NOTES:**
 
-The effect of calling pthread_getspecific() with a key value not obtained from
+The effect of calling ``pthread_getspecific()`` with a key value not obtained
-pthread_key_create() or after key has
+from ``pthread_key_create()`` or after key has been deleted with
-been deleted with pthread_key_delete() is undefined.
+``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.
 
+``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()``.

posix_users/language_specific_services.rst

@@ -1,55 +1,58 @@
+.. COMMENT: COPYRIGHT (c) 1988-2002.
+.. COMMENT: On-Line Applications Research Corporation (OAR).
+.. COMMENT: All rights reserved.
+
 Language-Specific Services for the C Programming Language Manager
 #################################################################
 
 Introduction
 ============
 
-The
+The language-specific services for the C programming language manager is ...
-language-specific services for the C programming language manager is ...
 
 The directives provided by the language-specific services for the C programming language manager are:
 
-- ``setlocale`` - Set the Current Locale
+- setlocale_ - Set the Current Locale
 
-- ``fileno`` - Obtain File Descriptor Number for this File
+- fileno_ - Obtain File Descriptor Number for this File
 
-- ``fdopen`` - Associate Stream with File Descriptor
+- fdopen_ - Associate Stream with File Descriptor
 
-- ``flockfile`` - Acquire Ownership of File Stream
+- flockfile_ - Acquire Ownership of File Stream
 
-- ``ftrylockfile`` - Poll to Acquire Ownership of File Stream
+- ftrylockfile_ - Poll to Acquire Ownership of File Stream
 
-- ``funlockfile`` - Release Ownership of File Stream
+- funlockfile_ - Release Ownership of File Stream
 
-- ``getc_unlocked`` - Get Character without Locking
+- getc_unlocked_ - Get Character without Locking
 
-- ``getchar_unlocked`` - Get Character from stdin without Locking
+- getchar_unlocked_ - Get Character from stdin without Locking
 
-- ``putc_unlocked`` - Put Character without Locking
+- putc_unlocked_ - Put Character without Locking
 
-- ``putchar_unlocked`` - Put Character to stdin without Locking
+- putchar_unlocked_ - Put Character to stdin without Locking
 
-- ``setjmp`` - Save Context for Non-Local Goto
+- setjmp_ - Save Context for Non-Local Goto
 
-- ``longjmp`` - Non-Local Jump to a Saved Context
+- longjmp_ - Non-Local Jump to a Saved Context
 
-- ``sigsetjmp`` - Save Context with Signal Status for Non-Local Goto
+- sigsetjmp_ - Save Context with Signal Status for Non-Local Goto
 
-- ``siglongjmp`` - Non-Local Jump with Signal Status to a Saved Context
+- siglongjmp_ - Non-Local Jump with Signal Status to a Saved Context
 
-- ``tzset`` - Initialize Time Conversion Information
+- tzset_ - Initialize Time Conversion Information
 
-- ``strtok_r`` - Reentrant Extract Token from String
+- strtok_r_ - Reentrant Extract Token from String
 
-- ``asctime_r`` - Reentrant struct tm to ASCII Time Conversion
+- asctime_r_ - Reentrant struct tm to ASCII Time Conversion
 
-- ``ctime_r`` - Reentrant time_t to ASCII Time Conversion
+- ctime_r_ - Reentrant time_t to ASCII Time Conversion
 
-- ``gmtime_r`` - Reentrant UTC Time Conversion
+- gmtime_r_ - Reentrant UTC Time Conversion
 
-- ``localtime_r`` - Reentrant Local Time Conversion
+- localtime_r_ - Reentrant Local Time Conversion
 
-- ``rand_r`` - Reentrant Random Number Generation
+- rand_r_ - Reentrant Random Number Generation
 
 Background
 ==========
@@ -64,10 +67,12 @@ There is currently no text in this section.
 Directives
 ==========
 
-This section details the language-specific services for the C programming language manager's directives.
+This section details the language-specific services for the C programming
-A subsection is dedicated to each of this manager's directives
+language manager's directives.  A subsection is dedicated to each of this
-and describes the calling sequence, related constants, usage,
+manager's directives and describes the calling sequence, related constants,
-and status codes.
+usage, and status codes.
+
+.. _setlocale:
 
 setlocale - Set the Current Locale
 ----------------------------------
@@ -76,20 +81,25 @@ setlocale - Set the Current Locale
 
 **CALLING SEQUENCE:**
 
-.. code:: c
+.. code-block:: c
 
     int setlocale(
     );
 
 **STATUS CODES:**
 
-*E*
+.. list-table::
-    The
+ :class: rtems-table
+
+ * - ``E``
+   - The
 
 **DESCRIPTION:**
 
 **NOTES:**
 
+.. _fileno:
+
 fileno - Obtain File Descriptor Number for this File
 ----------------------------------------------------
 .. index:: fileno
@@ -97,20 +107,25 @@ fileno - Obtain File Descriptor Number for this File
 
 **CALLING SEQUENCE:**
 
-.. code:: c
+.. code-block:: c
 
     int fileno(
     );
 
 **STATUS CODES:**
 
-*E*
+.. list-table::
-    The
+ :class: rtems-table
+
+ * - ``E``
+   - The
 
 **DESCRIPTION:**
 
 **NOTES:**
 
+.. _fdopen:
+
 fdopen - Associate Stream with File Descriptor
 ----------------------------------------------
 .. index:: fdopen
@@ -118,20 +133,25 @@ fdopen - Associate Stream with File Descriptor
 
 **CALLING SEQUENCE:**
 
-.. code:: c
+.. code-block:: c
 
     int fdopen(
     );
 
 **STATUS CODES:**
 
-*E*
+.. list-table::
-    The
+ :class: rtems-table
+
+ * - ``E``
+   - The
 
 **DESCRIPTION:**
 
 **NOTES:**
 
+.. _flockfile:
+
 flockfile - Acquire Ownership of File Stream
 --------------------------------------------
 .. index:: flockfile
@@ -139,20 +159,25 @@ flockfile - Acquire Ownership of File Stream
 
 **CALLING SEQUENCE:**
 
-.. code:: c
+.. code-block:: c
 
     int flockfile(
     );
 
 **STATUS CODES:**
 
-*E*
+.. list-table::
-    The
+ :class: rtems-table
+
+ * - ``E``
+   - The
 
 **DESCRIPTION:**
 
 **NOTES:**
 
+.. _ftrylockfile:
+
 ftrylockfile - Poll to Acquire Ownership of File Stream
 -------------------------------------------------------
 .. index:: ftrylockfile
@@ -160,20 +185,25 @@ ftrylockfile - Poll to Acquire Ownership of File Stream
 
 **CALLING SEQUENCE:**
 
-.. code:: c
+.. code-block:: c
 
     int ftrylockfile(
     );
 
 **STATUS CODES:**
 
-*E*
+.. list-table::
-    The
+ :class: rtems-table
+
+ * - ``E``
+   - The
 
 **DESCRIPTION:**
 
 **NOTES:**
 
+.. _funlockfile:
+
 funlockfile - Release Ownership of File Stream
 ----------------------------------------------
 .. index:: funlockfile
@@ -181,20 +211,25 @@ funlockfile - Release Ownership of File Stream
 
 **CALLING SEQUENCE:**
 
-.. code:: c
+.. code-block:: c
 
     int funlockfile(
     );
 
 **STATUS CODES:**
 
-*E*
+.. list-table::
-    The
+ :class: rtems-table
+
+ * - ``E``
+   - The
 
 **DESCRIPTION:**
 
 **NOTES:**
 
+.. _getc_unlocked:
+
 getc_unlocked - Get Character without Locking
 ---------------------------------------------
 .. index:: getc_unlocked
@@ -202,20 +237,25 @@ getc_unlocked - Get Character without Locking
 
 **CALLING SEQUENCE:**
 
-.. code:: c
+.. code-block:: c
 
     int getc_unlocked(
     );
 
 **STATUS CODES:**
 
-*E*
+.. list-table::
-    The
+ :class: rtems-table
+
+ * - ``E``
+   - The
 
 **DESCRIPTION:**
 
 **NOTES:**
 
+.. _getchar_unlocked:
+
 getchar_unlocked - Get Character from stdin without Locking
 -----------------------------------------------------------
 .. index:: getchar_unlocked
@@ -223,20 +263,25 @@ getchar_unlocked - Get Character from stdin without Locking
 
 **CALLING SEQUENCE:**
 
-.. code:: c
+.. code-block:: c
 
     int getchar_unlocked(
     );
 
 **STATUS CODES:**
 
-*E*
+.. list-table::
-    The
+ :class: rtems-table
+
+ * - ``E``
+   - The
 
 **DESCRIPTION:**
 
 **NOTES:**
 
+.. _putc_unlocked:
+
 putc_unlocked - Put Character without Locking
 ---------------------------------------------
 .. index:: putc_unlocked
@@ -244,20 +289,25 @@ putc_unlocked - Put Character without Locking
 
 **CALLING SEQUENCE:**
 
-.. code:: c
+.. code-block:: c
 
     int putc_unlocked(
     );
 
 **STATUS CODES:**
 
-*E*
+.. list-table::
-    The
+ :class: rtems-table
+
+ * - ``E``
+   - The
 
 **DESCRIPTION:**
 
 **NOTES:**
 
+.. _putchar_unlocked:
+
 putchar_unlocked - Put Character to stdin without Locking
 ---------------------------------------------------------
 .. index:: putchar_unlocked
@@ -265,20 +315,25 @@ putchar_unlocked - Put Character to stdin without Locking
 
 **CALLING SEQUENCE:**
 
-.. code:: c
+.. code-block:: c
 
     int putchar_unlocked(
     );
 
 **STATUS CODES:**
 
-*E*
+.. list-table::
-    The
+ :class: rtems-table
+
+ * - ``E``
+   - The
 
 **DESCRIPTION:**
 
 **NOTES:**
 
+.. _setjmp:
+
 setjmp - Save Context for Non-Local Goto
 ----------------------------------------
 .. index:: setjmp
@@ -286,20 +341,25 @@ setjmp - Save Context for Non-Local Goto
 
 **CALLING SEQUENCE:**
 
-.. code:: c
+.. code-block:: c
 
     int setjmp(
     );
 
 **STATUS CODES:**
 
-*E*
+.. list-table::
-    The
+ :class: rtems-table
+
+ * - ``E``
+   - The
 
 **DESCRIPTION:**
 
 **NOTES:**
 
+.. _longjmp:
+
 longjmp - Non-Local Jump to a Saved Context
 -------------------------------------------
 .. index:: longjmp
@@ -307,20 +367,25 @@ longjmp - Non-Local Jump to a Saved Context
 
 **CALLING SEQUENCE:**
 
-.. code:: c
+.. code-block:: c
 
     int longjmp(
     );
 
 **STATUS CODES:**
 
-*E*
+.. list-table::
-    The
+ :class: rtems-table
+
+ * - ``E``
+   - The
 
 **DESCRIPTION:**
 
 **NOTES:**
 
+.. _sigsetjmp:
+
 sigsetjmp - Save Context with Signal Status for Non-Local Goto
 --------------------------------------------------------------
 .. index:: sigsetjmp
@@ -328,20 +393,25 @@ sigsetjmp - Save Context with Signal Status for Non-Local Goto
 
 **CALLING SEQUENCE:**
 
-.. code:: c
+.. code-block:: c
 
     int sigsetjmp(
     );
 
 **STATUS CODES:**
 
-*E*
+.. list-table::
-    The
+ :class: rtems-table
+
+ * - ``E``
+   - The
 
 **DESCRIPTION:**
 
 **NOTES:**
 
+.. _siglongjmp:
+
 siglongjmp - Non-Local Jump with Signal Status to a Saved Context
 -----------------------------------------------------------------
 .. index:: siglongjmp
@@ -349,20 +419,25 @@ siglongjmp - Non-Local Jump with Signal Status to a Saved Context
 
 **CALLING SEQUENCE:**
 
-.. code:: c
+.. code-block:: c
 
     int siglongjmp(
     );
 
 **STATUS CODES:**
 
-*E*
+.. list-table::
-    The
+ :class: rtems-table
+
+ * - ``E``
+   - The
 
 **DESCRIPTION:**
 
 **NOTES:**
 
+.. _tzset:
+
 tzset - Initialize Time Conversion Information
 ----------------------------------------------
 .. index:: tzset
@@ -370,20 +445,25 @@ tzset - Initialize Time Conversion Information
 
 **CALLING SEQUENCE:**
 
-.. code:: c
+.. code-block:: c
 
     int tzset(
     );
 
 **STATUS CODES:**
 
-*E*
+.. list-table::
-    The
+ :class: rtems-table
+
+ * - ``E``
+   - The
 
 **DESCRIPTION:**
 
 **NOTES:**
 
+.. _strtok_r:
+
 strtok_r - Reentrant Extract Token from String
 ----------------------------------------------
 .. index:: strtok_r
@@ -391,20 +471,25 @@ strtok_r - Reentrant Extract Token from String
 
 **CALLING SEQUENCE:**
 
-.. code:: c
+.. code-block:: c
 
     int strtok_r(
     );
 
 **STATUS CODES:**
 
-*E*
+.. list-table::
-    The
+ :class: rtems-table
+
+ * - ``E``
+   - The
 
 **DESCRIPTION:**
 
 **NOTES:**
 
+.. _asctime_r:
+
 asctime_r - Reentrant struct tm to ASCII Time Conversion
 --------------------------------------------------------
 .. index:: asctime_r
@@ -412,20 +497,25 @@ asctime_r - Reentrant struct tm to ASCII Time Conversion
 
 **CALLING SEQUENCE:**
 
-.. code:: c
+.. code-block:: c
 
     int asctime_r(
     );
 
 **STATUS CODES:**
 
-*E*
+.. list-table::
-    The
+ :class: rtems-table
+
+ * - ``E``
+   - The
 
 **DESCRIPTION:**
 
 **NOTES:**
 
+.. _ctime_r:
+
 ctime_r - Reentrant time_t to ASCII Time Conversion
 ---------------------------------------------------
 .. index:: ctime_r
@@ -433,20 +523,25 @@ ctime_r - Reentrant time_t to ASCII Time Conversion
 
 **CALLING SEQUENCE:**
 
-.. code:: c
+.. code-block:: c
 
     int ctime_r(
     );
 
 **STATUS CODES:**
 
-*E*
+.. list-table::
-    The
+ :class: rtems-table
+
+ * - ``E``
+   - The
 
 **DESCRIPTION:**
 
 **NOTES:**
 
+.. _gmtime_r:
+
 gmtime_r - Reentrant UTC Time Conversion
 ----------------------------------------
 .. index:: gmtime_r
@@ -454,20 +549,25 @@ gmtime_r - Reentrant UTC Time Conversion
 
 **CALLING SEQUENCE:**
 
-.. code:: c
+.. code-block:: c
 
     int gmtime_r(
     );
 
 **STATUS CODES:**
 
-*E*
+.. list-table::
-    The
+ :class: rtems-table
+
+ * - ``E``
+   - The
 
 **DESCRIPTION:**
 
 **NOTES:**
 
+.. _localtime_r:
+
 localtime_r - Reentrant Local Time Conversion
 ---------------------------------------------
 .. index:: localtime_r
@@ -475,20 +575,25 @@ localtime_r - Reentrant Local Time Conversion
 
 **CALLING SEQUENCE:**
 
-.. code:: c
+.. code-block:: c
 
     int localtime_r(
     );
 
 **STATUS CODES:**
 
-*E*
+.. list-table::
-    The
+ :class: rtems-table
+
+ * - ``E``
+   - The
 
 **DESCRIPTION:**
 
 **NOTES:**
 
+.. _rand_r:
+
 rand_r - Reentrant Random Number Generation
 -------------------------------------------
 .. index:: rand_r
@@ -496,23 +601,19 @@ rand_r - Reentrant Random Number Generation
 
 **CALLING SEQUENCE:**
 
-.. code:: c
+.. code-block:: c
 
     int rand_r(
     );
 
 **STATUS CODES:**
 
-*E*
+.. list-table::
-    The
+ :class: rtems-table
+
+ * - ``E``
+   - The
 
 **DESCRIPTION:**
 
 **NOTES:**
-
-.. COMMENT: COPYRIGHT (c) 1988-2002.
-
-.. COMMENT: On-Line Applications Research Corporation (OAR).
-
-.. COMMENT: All rights reserved.
-

posix_users/memory_managment.rst

@@ -1,3 +1,7 @@
+.. COMMENT: COPYRIGHT (c) 1988-2002.
+.. COMMENT: On-Line Applications Research Corporation (OAR).
+.. COMMENT: All rights reserved.
+
 Memory Management Manager
 #########################
 
@@ -9,25 +13,25 @@ memory management manager is ...
 
 The directives provided by the memory management manager are:
 
-- ``mlockall`` - Lock the Address Space of a Process
+- mlockall_ - Lock the Address Space of a Process
 
-- ``munlockall`` - Unlock the Address Space of a Process
+- munlockall_ - Unlock the Address Space of a Process
 
-- ``mlock`` - Lock a Range of the Process Address Space
+- mlock_ - Lock a Range of the Process Address Space
 
-- ``munlock`` - Unlock a Range of the Process Address Space
+- munlock_ - Unlock a Range of the Process Address Space
 
-- ``mmap`` - Map Process Addresses to a Memory Object
+- mmap_ - Map Process Addresses to a Memory Object
 
-- ``munmap`` - Unmap Previously Mapped Addresses
+- munmap_ - Unmap Previously Mapped Addresses
 
-- ``mprotect`` - Change Memory Protection
+- mprotect_ - Change Memory Protection
 
-- ``msync`` - Memory Object Synchronization
+- msync_ - Memory Object Synchronization
 
-- ``shm_open`` - Open a Shared Memory Object
+- shm_open_ - Open a Shared Memory Object
 
-- ``shm_unlink`` - Remove a Shared Memory Object
+- shm_unlink_ - Remove a Shared Memory Object
 
 Background
 ==========
@@ -42,10 +46,11 @@ There is currently no text in this section.
 Directives
 ==========
 
-This section details the memory management manager's directives.
+This section details the memory management manager's directives.  A subsection
-A subsection is dedicated to each of this manager's directives
+is dedicated to each of this manager's directives and describes the calling
-and describes the calling sequence, related constants, usage,
+sequence, related constants, usage, and status codes.
-and status codes.
+
+.. _mlockall:
 
 mlockall - Lock the Address Space of a Process
 ----------------------------------------------
@@ -54,20 +59,25 @@ mlockall - Lock the Address Space of a Process
 
 **CALLING SEQUENCE:**
 
-.. code:: c
+.. code-block:: c
 
     int mlockall(
     );
 
 **STATUS CODES:**
 
-*E*
+.. list-table::
-    The
+ :class: rtems-table
+
+ * - ``E``
+   - The
 
 **DESCRIPTION:**
 
 **NOTES:**
 
+.. _munlockall:
+
 munlockall - Unlock the Address Space of a Process
 --------------------------------------------------
 .. index:: munlockall
@@ -75,20 +85,25 @@ munlockall - Unlock the Address Space of a Process
 
 **CALLING SEQUENCE:**
 
-.. code:: c
+.. code-block:: c
 
     int munlockall(
     );
 
 **STATUS CODES:**
 
-*E*
+.. list-table::
-    The
+ :class: rtems-table
+
+ * - ``E``
+   - The
 
 **DESCRIPTION:**
 
 **NOTES:**
 
+.. _mlock:
+
 mlock - Lock a Range of the Process Address Space
 -------------------------------------------------
 .. index:: mlock
@@ -96,20 +111,25 @@ mlock - Lock a Range of the Process Address Space
 
 **CALLING SEQUENCE:**
 
-.. code:: c
+.. code-block:: c
 
     int mlock(
     );
 
 **STATUS CODES:**
 
-*E*
+.. list-table::
-    The
+ :class: rtems-table
+
+ * - ``E``
+   - The
 
 **DESCRIPTION:**
 
 **NOTES:**
 
+.. _munlock:
+
 munlock - Unlock a Range of the Process Address Space
 -----------------------------------------------------
 .. index:: munlock
@@ -117,20 +137,25 @@ munlock - Unlock a Range of the Process Address Space
 
 **CALLING SEQUENCE:**
 
-.. code:: c
+.. code-block:: c
 
     int munlock(
     );
 
 **STATUS CODES:**
 
-*E*
+.. list-table::
-    The
+ :class: rtems-table
+
+ * - ``E``
+   - The
 
 **DESCRIPTION:**
 
 **NOTES:**
 
+.. _mmap:
+
 mmap - Map Process Addresses to a Memory Object
 -----------------------------------------------
 .. index:: mmap
@@ -138,20 +163,25 @@ mmap - Map Process Addresses to a Memory Object
 
 **CALLING SEQUENCE:**
 
-.. code:: c
+.. code-block:: c
 
     int mmap(
     );
 
 **STATUS CODES:**
 
-*E*
+.. list-table::
-    The
+ :class: rtems-table
+
+ * - ``E``
+   - The
 
 **DESCRIPTION:**
 
 **NOTES:**
 
+.. _munmap:
+
 munmap - Unmap Previously Mapped Addresses
 ------------------------------------------
 .. index:: munmap
@@ -159,20 +189,25 @@ munmap - Unmap Previously Mapped Addresses
 
 **CALLING SEQUENCE:**
 
-.. code:: c
+.. code-block:: c
 
     int munmap(
     );
 
 **STATUS CODES:**
 
-*E*
+.. list-table::
-    The
+ :class: rtems-table
+
+ * - ``E``
+   - The
 
 **DESCRIPTION:**
 
 **NOTES:**
 
+.. _mprotect:
+
 mprotect - Change Memory Protection
 -----------------------------------
 .. index:: mprotect
@@ -180,20 +215,25 @@ mprotect - Change Memory Protection
 
 **CALLING SEQUENCE:**
 
-.. code:: c
+.. code-block:: c
 
     int mprotect(
     );
 
 **STATUS CODES:**
 
-*E*
+.. list-table::
-    The
+ :class: rtems-table
+
+ * - ``E``
+   - The
 
 **DESCRIPTION:**
 
 **NOTES:**
 
+.. _msync:
+
 msync - Memory Object Synchronization
 -------------------------------------
 .. index:: msync
@@ -201,20 +241,25 @@ msync - Memory Object Synchronization
 
 **CALLING SEQUENCE:**
 
-.. code:: c
+.. code-block:: c
 
     int msync(
     );
 
 **STATUS CODES:**
 
-*E*
+.. list-table::
-    The
+ :class: rtems-table
+
+ * - ``E``
+   - The
 
 **DESCRIPTION:**
 
 **NOTES:**
 
+.. _shm_open:
+
 shm_open - Open a Shared Memory Object
 --------------------------------------
 .. index:: shm_open
@@ -222,20 +267,25 @@ shm_open - Open a Shared Memory Object
 
 **CALLING SEQUENCE:**
 
-.. code:: c
+.. code-block:: c
 
     int shm_open(
     );
 
 **STATUS CODES:**
 
-*E*
+.. list-table::
-    The
+ :class: rtems-table
+
+ * - ``E``
+   - The
 
 **DESCRIPTION:**
 
 **NOTES:**
 
+.. _shm_unlink:
+
 shm_unlink - Remove a Shared Memory Object
 ------------------------------------------
 .. index:: shm_unlink
@@ -243,23 +293,19 @@ shm_unlink - Remove a Shared Memory Object
 
 **CALLING SEQUENCE:**
 
-.. code:: c
+.. code-block:: c
 
     int shm_unlink(
     );
 
 **STATUS CODES:**
 
-*E*
+.. list-table::
-    The
+ :class: rtems-table
+
+ * - ``E``
+   - The
 
 **DESCRIPTION:**
 
 **NOTES:**
-
-.. COMMENT: COPYRIGHT (c) 1988-2002.
-
-.. COMMENT: On-Line Applications Research Corporation (OAR).
-
-.. COMMENT: All rights reserved.
-

posix_users/mutex.rst

@@ -1,48 +1,51 @@
+.. COMMENT: COPYRIGHT (c) 1988-2002.
+.. COMMENT: On-Line Applications Research Corporation (OAR).
+.. COMMENT: All rights reserved.
+
 Mutex Manager
 #############
 
 Introduction
 ============
 
-The mutex manager implements the functionality required of the mutex
+The mutex manager implements the functionality required of the mutex manager as
-manager as defined by POSIX 1003.1b-1996. This standard requires that
+defined by POSIX 1003.1b-1996. This standard requires that a compliant
-a compliant operating system provide the facilties to ensure that
+operating system provide the facilties to ensure that threads can operate with
-threads can operate with mutual exclusion from one another and
+mutual exclusion from one another and defines the API that must be provided.
-defines the API that must be provided.
 
 The services provided by the mutex manager are:
 
-- ``pthread_mutexattr_init`` - Initialize a Mutex Attribute Set
+- pthread_mutexattr_init_ - Initialize a Mutex Attribute Set
 
-- ``pthread_mutexattr_destroy`` - Destroy a Mutex Attribute Set
+- pthread_mutexattr_destroy_ - Destroy a Mutex Attribute Set
 
-- ``pthread_mutexattr_setprotocol`` - Set the Blocking Protocol
+- pthread_mutexattr_setprotocol_ - Set the Blocking Protocol
 
-- ``pthread_mutexattr_getprotocol`` - Get the Blocking Protocol
+- pthread_mutexattr_getprotocol_ - Get the Blocking Protocol
 
-- ``pthread_mutexattr_setprioceiling`` - Set the Priority Ceiling
+- pthread_mutexattr_setprioceiling_ - Set the Priority Ceiling
 
-- ``pthread_mutexattr_getprioceiling`` - Get the Priority Ceiling
+- pthread_mutexattr_getprioceiling_ - Get the Priority Ceiling
 
-- ``pthread_mutexattr_setpshared`` - Set the Visibility
+- pthread_mutexattr_setpshared_ - Set the Visibility
 
-- ``pthread_mutexattr_getpshared`` - Get the Visibility
+- pthread_mutexattr_getpshared_ - Get the Visibility
 
-- ``pthread_mutex_init`` - Initialize a Mutex
+- pthread_mutex_init_ - Initialize a Mutex
 
-- ``pthread_mutex_destroy`` - Destroy a Mutex
+- pthread_mutex_destroy_ - Destroy a Mutex
 
-- ``pthread_mutex_lock`` - Lock a Mutex
+- pthread_mutex_lock_ - Lock a Mutex
 
-- ``pthread_mutex_trylock`` - Poll to Lock a Mutex
+- pthread_mutex_trylock_ - Poll to Lock a Mutex
 
-- ``pthread_mutex_timedlock`` - Lock a Mutex with Timeout
+- pthread_mutex_timedlock_ - Lock a Mutex with Timeout
 
-- ``pthread_mutex_unlock`` - Unlock a Mutex
+- pthread_mutex_unlock_ - Unlock a Mutex
 
-- ``pthread_mutex_setprioceiling`` - Dynamically Set the Priority Ceiling
+- pthread_mutex_setprioceiling_ - Dynamically Set the Priority Ceiling
 
-- ``pthread_mutex_getprioceiling`` - Dynamically Get the Priority Ceiling
+- pthread_mutex_getprioceiling_ - Dynamically Get the Priority Ceiling
 
 Background
 ==========
@@ -50,32 +53,32 @@ Background
 Mutex Attributes
 ----------------
 
-Mutex attributes are utilized only at mutex creation time. A mutex
+Mutex attributes are utilized only at mutex creation time. A mutex attribute
-attribute structure may be initialized and passed as an argument to
+structure may be initialized and passed as an argument to the ``mutex_init``
-the ``mutex_init`` routine. Note that the priority ceiling of
+routine. Note that the priority ceiling of a mutex may be set at run-time.
-a mutex may be set at run-time.
 
-*blocking protcol*
+.. list-table::
-    is the XXX
+ :class: rtems-table
 
-*priority ceiling*
+ * - *blocking protcol*
-    is the XXX
+   - is the XXX
-
+ * - *priority ceiling*
-*pshared*
+   - is the XXX
-    is the XXX
+ * - *pshared*
+   - is the XXX
 
 PTHREAD_MUTEX_INITIALIZER
 -------------------------
 
-This is a special value that a variable of type ``pthread_mutex_t``
+This is a special value that a variable of type ``pthread_mutex_t`` may be
-may be statically initialized to as shown below:
+statically initialized to as shown below:
-.. code:: c
+
+.. code-block:: c
 
     pthread_mutex_t my_mutex = PTHREAD_MUTEX_INITIALIZER;
 
-This indicates that ``my_mutex`` will be automatically initialized
+This indicates that ``my_mutex`` will be automatically initialized by an
-by an implicit call to ``pthread_mutex_init`` the first time
+implicit call to ``pthread_mutex_init`` the first time the mutex is used.
-the mutex is used.
 
 Note that the mutex will be initialized with default attributes.
 
@@ -87,10 +90,11 @@ There is currently no text in this section.
 Services
 ========
 
-This section details the mutex manager's services.
+This section details the mutex manager's services.  A subsection is dedicated
-A subsection is dedicated to each of this manager's services
+to each of this manager's services and describes the calling sequence, related
-and describes the calling sequence, related constants, usage,
+constants, usage, and status codes.
-and status codes.
+
+.. _pthread_mutexattr_init:
 
 pthread_mutexattr_init - Initialize a Mutex Attribute Set
 ---------------------------------------------------------
@@ -99,11 +103,11 @@ pthread_mutexattr_init - Initialize a Mutex Attribute Set
 
 **CALLING SEQUENCE:**
 
-.. code:: c
+.. code-block:: c
 
     #include <pthread.h>
     int pthread_mutexattr_init(
-    pthread_mutexattr_t \*attr
+        pthread_mutexattr_t *attr
     );
 
 **STATUS CODES:**
@@ -113,14 +117,16 @@ pthread_mutexattr_init - Initialize a Mutex Attribute Set
 
 **DESCRIPTION:**
 
-The ``pthread_mutexattr_init`` routine initializes the mutex attributes
+The ``pthread_mutexattr_init`` routine initializes the mutex attributes object
-object specified by ``attr`` with the default value for all of the
+specified by ``attr`` with the default value for all of the individual
-individual attributes.
+attributes.
 
 **NOTES:**
 
 XXX insert list of default attributes here.
 
+.. _pthread_mutexattr_destroy:
+
 pthread_mutexattr_destroy - Destroy a Mutex Attribute Set
 ---------------------------------------------------------
 .. index:: pthread_mutexattr_destroy
@@ -128,31 +134,35 @@ pthread_mutexattr_destroy - Destroy a Mutex Attribute Set
 
 **CALLING SEQUENCE:**
 
-.. code:: c
+.. code-block:: c
 
     #include <pthread.h>
-    int pthread_mutexattr_destroy(
+        int pthread_mutexattr_destroy(
-    pthread_mutexattr_t \*attr
+        pthread_mutexattr_t *attr
     );
 
 **STATUS CODES:**
 
-*EINVAL*
+.. list-table::
-    The attribute pointer argument is invalid.
+ :class: rtems-table
 
-*EINVAL*
+ * - ``EINVAL``
-    The attribute set is not initialized.
+   - The attribute pointer argument is invalid.
+ * - ``EINVAL``
+   - The attribute set is not initialized.
 
 **DESCRIPTION:**
 
 The ``pthread_mutex_attr_destroy`` routine is used to destroy a mutex
-attributes object. The behavior of using an attributes object after
+attributes object. The behavior of using an attributes object after it is
-it is destroyed is implementation dependent.
+destroyed is implementation dependent.
 
 **NOTES:**
 
 NONE
 
+.. _pthread_mutexattr_setprotocol:
+
 pthread_mutexattr_setprotocol - Set the Blocking Protocol
 ---------------------------------------------------------
 .. index:: pthread_mutexattr_setprotocol
@@ -160,47 +170,52 @@ pthread_mutexattr_setprotocol - Set the Blocking Protocol
 
 **CALLING SEQUENCE:**
 
-.. code:: c
+.. code-block:: c
 
     #include <pthread.h>
     int pthread_mutexattr_setprotocol(
-    pthread_mutexattr_t \*attr,
+        pthread_mutexattr_t *attr,
-    int                  protocol
+        int                  protocol
     );
 
 **STATUS CODES:**
 
-*EINVAL*
+.. list-table::
-    The attribute pointer argument is invalid.
+ :class: rtems-table
 
-*EINVAL*
+ * - ``EINVAL``
-    The attribute set is not initialized.
+   - The attribute pointer argument is invalid.
-
+ * - ``EINVAL``
-*EINVAL*
+   - The attribute set is not initialized.
-    The protocol argument is invalid.
+ * - ``EINVAL``
+   - The protocol argument is invalid.
 
 **DESCRIPTION:**
 
-The ``pthread_mutexattr_setprotocol`` routine is used to set value of the``protocol`` attribute. This attribute controls the order in which
+The ``pthread_mutexattr_setprotocol`` routine is used to set value of the
-threads waiting on this mutex will receive it.
+``protocol`` attribute. This attribute controls the order in which threads
+waiting on this mutex will receive it.
 
 The ``protocol`` can be one of the following:
 
-*``PTHREAD_PRIO_NONE``*
+.. list-table::
-    in which case blocking order is FIFO.
+ :class: rtems-table
 
-*``PTHREAD_PRIO_INHERIT``*
+ * - ``PTHREAD_PRIO_NONE``
-    in which case blocking order is priority with the priority inheritance
+   - in which case blocking order is FIFO.
-    protocol in effect.
+ * - ``PTHREAD_PRIO_INHERIT``
-
+   - in which case blocking order is priority with the priority inheritance
-*``PTHREAD_PRIO_PROTECT``*
+     protocol in effect.
-    in which case blocking order is priority with the priority ceiling
+ * - ``PTHREAD_PRIO_PROTECT``
-    protocol in effect.
+   - in which case blocking order is priority with the priority ceiling
+     protocol in effect.
 
 **NOTES:**
 
-There is currently no way to get simple priority blocking ordering
+There is currently no way to get simple priority blocking ordering with POSIX
-with POSIX mutexes even though this could easily by supported by RTEMS.
+mutexes even though this could easily by supported by RTEMS.
+
+.. _pthread_mutexattr_getprotocol:
 
 pthread_mutexattr_getprotocol - Get the Blocking Protocol
 ---------------------------------------------------------
@@ -209,35 +224,38 @@ pthread_mutexattr_getprotocol - Get the Blocking Protocol
 
 **CALLING SEQUENCE:**
 
-.. code:: c
+.. code-block:: c
 
     #include <pthread.h>
     int pthread_mutexattr_getprotocol(
-    pthread_mutexattr_t \*attr,
+        pthread_mutexattr_t *attr,
-    int                 \*protocol
+        int                 *protocol
     );
 
 **STATUS CODES:**
 
-*EINVAL*
+.. list-table::
-    The attribute pointer argument is invalid.
+ :class: rtems-table
 
-*EINVAL*
+ * - ``EINVAL``
-    The attribute set is not initialized.
+   - The attribute pointer argument is invalid.
-
+ * - ``EINVAL``
-*EINVAL*
+   - The attribute set is not initialized.
-    The protocol pointer argument is invalid.
+ * - ``EINVAL``
+   - The protocol pointer argument is invalid.
 
 **DESCRIPTION:**
 
-The ``pthread_mutexattr_getprotocol`` routine is used to obtain
+The ``pthread_mutexattr_getprotocol`` routine is used to obtain the value of
-the value of the ``protocol`` attribute. This attribute controls
+the ``protocol`` attribute. This attribute controls the order in which threads
-the order in which threads waiting on this mutex will receive it.
+waiting on this mutex will receive it.
 
 **NOTES:**
 
 NONE
 
+.. _pthread_mutexattr_setprioceiling:
+
 pthread_mutexattr_setprioceiling - Set the Priority Ceiling
 -----------------------------------------------------------
 .. index:: pthread_mutexattr_setprioceiling
@@ -245,36 +263,40 @@ pthread_mutexattr_setprioceiling - Set the Priority Ceiling
 
 **CALLING SEQUENCE:**
 
-.. code:: c
+.. code-block:: c
 
     #include <pthread.h>
     int pthread_mutexattr_setprioceiling(
-    pthread_mutexattr_t \*attr,
+        pthread_mutexattr_t *attr,
-    int                  prioceiling
+        int                  prioceiling
     );
 
 **STATUS CODES:**
 
-*EINVAL*
+.. list-table::
-    The attribute pointer argument is invalid.
+ :class: rtems-table
 
-*EINVAL*
+ * - ``EINVAL``
-    The attribute set is not initialized.
+   - The attribute pointer argument is invalid.
-
+ * - ``EINVAL``
-*EINVAL*
+   - The attribute set is not initialized.
-    The prioceiling argument is invalid.
+ * - ``EINVAL``
+   - The prioceiling argument is invalid.
 
 **DESCRIPTION:**
 
-The ``pthread_mutexattr_setprioceiling`` routine is used to set value of the``prioceiling`` attribute. This attribute specifies the priority that
+The ``pthread_mutexattr_setprioceiling`` routine is used to set value of the
-is the ceiling for threads obtaining this mutex. Any task obtaining this
+``prioceiling`` attribute. This attribute specifies the priority that is the
-mutex may not be of greater priority that the ceiling. If it is of lower
+ceiling for threads obtaining this mutex. Any task obtaining this mutex may not
-priority, then its priority will be elevated to ``prioceiling``.
+be of greater priority that the ceiling. If it is of lower priority, then its
+priority will be elevated to ``prioceiling``.
 
 **NOTES:**
 
 NONE
 
+.. _pthread_mutexattr_getprioceiling:
+
 pthread_mutexattr_getprioceiling - Get the Priority Ceiling
 -----------------------------------------------------------
 .. index:: pthread_mutexattr_getprioceiling
@@ -282,35 +304,38 @@ pthread_mutexattr_getprioceiling - Get the Priority Ceiling
 
 **CALLING SEQUENCE:**
 
-.. code:: c
+.. code-block:: c
 
     #include <pthread.h>
     int pthread_mutexattr_getprioceiling(
-    const pthread_mutexattr_t \*attr,
+        const pthread_mutexattr_t *attr,
-    int                       \*prioceiling
+        int                       *prioceiling
     );
 
 **STATUS CODES:**
 
-*EINVAL*
+.. list-table::
-    The attribute pointer argument is invalid.
+ :class: rtems-table
 
-*EINVAL*
+ * - ``EINVAL``
-    The attribute set is not initialized.
+   - The attribute pointer argument is invalid.
-
+ * - ``EINVAL``
-*EINVAL*
+   - The attribute set is not initialized.
-    The prioceiling pointer argument is invalid.
+ * - ``EINVAL``
+   - The prioceiling pointer argument is invalid.
 
 **DESCRIPTION:**
 
-The ``pthread_mutexattr_getprioceiling`` routine is used to obtain the
+The ``pthread_mutexattr_getprioceiling`` routine is used to obtain the value of
-value of the ``prioceiling`` attribute. This attribute specifies the
+the ``prioceiling`` attribute. This attribute specifies the priority ceiling
-priority ceiling for this mutex.
+for this mutex.
 
 **NOTES:**
 
 NONE
 
+.. _pthread_mutexattr_setpshared:
+
 pthread_mutexattr_setpshared - Set the Visibility
 -------------------------------------------------
 .. index:: pthread_mutexattr_setpshared
@@ -318,29 +343,32 @@ pthread_mutexattr_setpshared - Set the Visibility
 
 **CALLING SEQUENCE:**
 
-.. code:: c
+.. code-block:: c
 
     #include <pthread.h>
     int pthread_mutexattr_setpshared(
-    pthread_mutexattr_t \*attr,
+        pthread_mutexattr_t *attr,
-    int                  pshared
+        int                  pshared
     );
 
 **STATUS CODES:**
 
-*EINVAL*
+.. list-table::
-    The attribute pointer argument is invalid.
+ :class: rtems-table
 
-*EINVAL*
+ * - ``EINVAL``
-    The attribute set is not initialized.
+   - The attribute pointer argument is invalid.
-
+ * - ``EINVAL``
-*EINVAL*
+   - The attribute set is not initialized.
-    The pshared argument is invalid.
+ * - ``EINVAL``
+   - The pshared argument is invalid.
 
 **DESCRIPTION:**
 
 **NOTES:**
 
+.. _pthread_mutexattr_getpshared:
+
 pthread_mutexattr_getpshared - Get the Visibility
 -------------------------------------------------
 .. index:: pthread_mutexattr_getpshared
@@ -348,29 +376,32 @@ pthread_mutexattr_getpshared - Get the Visibility
 
 **CALLING SEQUENCE:**
 
-.. code:: c
+.. code-block:: c
 
     #include <pthread.h>
     int pthread_mutexattr_getpshared(
-    const pthread_mutexattr_t \*attr,
+        const pthread_mutexattr_t *attr,
-    int                       \*pshared
+        int                       *pshared
     );
 
 **STATUS CODES:**
 
-*EINVAL*
+.. list-table::
-    The attribute pointer argument is invalid.
+ :class: rtems-table
 
-*EINVAL*
+ * - ``EINVAL``
-    The attribute set is not initialized.
+   - The attribute pointer argument is invalid.
-
+ * - ``EINVAL``
-*EINVAL*
+   - The attribute set is not initialized.
-    The pshared pointer argument is invalid.
+ * - ``EINVAL``
+   - The pshared pointer argument is invalid.
 
 **DESCRIPTION:**
 
 **NOTES:**
 
+.. _pthread_mutex_init:
+
 pthread_mutex_init - Initialize a Mutex
 ---------------------------------------
 .. index:: pthread_mutex_init
@@ -378,36 +409,37 @@ pthread_mutex_init - Initialize a Mutex
 
 **CALLING SEQUENCE:**
 
-.. code:: c
+.. code-block:: c
 
     #include <pthread.h>
     int pthread_mutex_init(
-    pthread_mutex_t           \*mutex,
+        pthread_mutex_t           *mutex,
-    const pthread_mutexattr_t \*attr
+        const pthread_mutexattr_t *attr
     );
 
 **STATUS CODES:**
 
-*EINVAL*
+.. list-table::
-    The attribute set is not initialized.
+ :class: rtems-table
 
-*EINVAL*
+ * - ``EINVAL``
-    The specified protocol is invalid.
+   - The attribute set is not initialized.
-
+ * - ``EINVAL``
-*EAGAIN*
+   - The specified protocol is invalid.
-    The system lacked the necessary resources to initialize another mutex.
+ * - ``EAGAIN``
-
+   - The system lacked the necessary resources to initialize another mutex.
-*ENOMEM*
+ * - ``ENOMEM``
-    Insufficient memory exists to initialize the mutex.
+   - Insufficient memory exists to initialize the mutex.
-
+ * - ``EBUSY``
-*EBUSY*
+   - Attempted to reinialize the object reference by mutex, a previously
-    Attempted to reinialize the object reference by mutex, a previously
+     initialized, but not yet destroyed.
-    initialized, but not yet destroyed.
 
 **DESCRIPTION:**
 
 **NOTES:**
 
+.. _pthread_mutex_destroy:
+
 pthread_mutex_destroy - Destroy a Mutex
 ---------------------------------------
 .. index:: pthread_mutex_destroy
@@ -415,26 +447,30 @@ pthread_mutex_destroy - Destroy a Mutex
 
 **CALLING SEQUENCE:**
 
-.. code:: c
+.. code-block:: c
 
     #include <pthread.h>
-    int pthread_mutex_destroy(
+        int pthread_mutex_destroy(
-    pthread_mutex_t \*mutex
+        pthread_mutex_t *mutex
     );
 
 **STATUS CODES:**
 
-*EINVAL*
+.. list-table::
-    The specified mutex is invalid.
+ :class: rtems-table
 
-*EBUSY*
+ * - ``EINVAL``
-    Attempted to destroy the object reference by mutex, while it is locked or
+   - The specified mutex is invalid.
-    referenced by another thread.
+ * - ``EBUSY``
+   - Attempted to destroy the object reference by mutex, while it is locked or
+     referenced by another thread.
 
 **DESCRIPTION:**
 
 **NOTES:**
 
+.. _pthread_mutex_lock:
+
 pthread_mutex_lock - Lock a Mutex
 ---------------------------------
 .. index:: pthread_mutex_lock
@@ -442,30 +478,33 @@ pthread_mutex_lock - Lock a Mutex
 
 **CALLING SEQUENCE:**
 
-.. code:: c
+.. code-block:: c
 
     #include <pthread.h>
     int pthread_mutex_lock(
-    pthread_mutex_t \*mutex
+        pthread_mutex_t *mutex
     );
 
 **STATUS CODES:**
 
-*EINVAL*
+.. list-table::
-    The specified mutex is invalid.
+ :class: rtems-table
 
-*EINVAL*
+ * - ``EINVAL``
-    The mutex has the protocol attribute of PTHREAD_PRIO_PROTECT and the
+   - The specified mutex is invalid.
-    priority of the calling thread is higher than the current priority
+ * - ``EINVAL``
-    ceiling.
+   - The mutex has the protocol attribute of ``PTHREAD_PRIO_PROTECT`` and the
-
+     priority of the calling thread is higher than the current priority
-*EDEADLK*
+     ceiling.
-    The current thread already owns the mutex.
+ * - ``EDEADLK``
+   - The current thread already owns the mutex.
 
 **DESCRIPTION:**
 
 **NOTES:**
 
+.. _pthread_mutex_trylock:
+
 pthread_mutex_trylock - Poll to Lock a Mutex
 --------------------------------------------
 .. index:: pthread_mutex_trylock
@@ -473,30 +512,32 @@ pthread_mutex_trylock - Poll to Lock a Mutex
 
 **CALLING SEQUENCE:**
 
-.. code:: c
+.. code-block:: c
 
     #include <pthread.h>
     int pthread_mutex_trylock(
-    pthread_mutex_t \*mutex
+        pthread_mutex_t *mutex
     );
 
 **STATUS CODES:**
 
-*EINVAL*
+.. list-table::
-    The specified mutex is invalid.
+ :class: rtems-table
 
-*EINVAL*
+ * - ``EINVAL``
-    The mutex has the protocol attribute of PTHREAD_PRIO_PROTECT and the
+   - The specified mutex is invalid.
-    priority of the calling thread is higher than the current priority
+ * - ``EINVAL``
-    ceiling.
+   - The mutex has the protocol attribute of ``PTHREAD_PRIO_PROTECT`` and the
-
+     priority of the calling thread is higher than the current priority ceiling.
-*EBUSY*
+ * - ``EBUSY``
-    The mutex is already locked.
+   - The mutex is already locked.
 
 **DESCRIPTION:**
 
 **NOTES:**
 
+.. _pthread_mutex_timedlock:
+
 pthread_mutex_timedlock - Lock a Mutex with Timeout
 ---------------------------------------------------
 .. index:: pthread_mutex_timedlock
@@ -504,39 +545,40 @@ pthread_mutex_timedlock - Lock a Mutex with Timeout
 
 **CALLING SEQUENCE:**
 
-.. code:: c
+.. code-block:: c
 
     #include <pthread.h>
     #include <time.h>
     int pthread_mutex_timedlock(
-    pthread_mutex_t       \*mutex,
+        pthread_mutex_t       *mutex,
-    const struct timespec \*timeout
+        const struct timespec *timeout
     );
 
 **STATUS CODES:**
 
-*EINVAL*
+.. list-table::
-    The specified mutex is invalid.
+ :class: rtems-table
 
-*EINVAL*
+ * - ``EINVAL``
-    The nanoseconds field of timeout is invalid.
+   - The specified mutex is invalid.
-
+ * - ``EINVAL``
-*EINVAL*
+   - The nanoseconds field of timeout is invalid.
-    The mutex has the protocol attribute of PTHREAD_PRIO_PROTECT and the
+ * - ``EINVAL``
-    priority of the calling thread is higher than the current priority
+   - The mutex has the protocol attribute of ``PTHREAD_PRIO_PROTECT`` and the
-    ceiling.
+     priority of the calling thread is higher than the current priority
-
+     ceiling.
-*EDEADLK*
+ * - ``EDEADLK``
-    The current thread already owns the mutex.
+   - The current thread already owns the mutex.
-
+ * - ``ETIMEDOUT``
-*ETIMEDOUT*
+   - The calling thread was unable to obtain the mutex within the specified
-    The calling thread was unable to obtain the mutex within the specified
+     timeout period.
-    timeout period.
 
 **DESCRIPTION:**
 
 **NOTES:**
 
+.. _pthread_mutex_unlock:
+
 pthread_mutex_unlock - Unlock a Mutex
 -------------------------------------
 .. index:: pthread_mutex_unlock
@@ -544,22 +586,27 @@ pthread_mutex_unlock - Unlock a Mutex
 
 **CALLING SEQUENCE:**
 
-.. code:: c
+.. code-block:: c
 
     #include <pthread.h>
     int pthread_mutex_unlock(
-    pthread_mutex_t \*mutex
+        pthread_mutex_t *mutex
     );
 
 **STATUS CODES:**
 
-*EINVAL*
+.. list-table::
-    The specified mutex is invalid.
+ :class: rtems-table
+
+ * - ``EINVAL``
+   - The specified mutex is invalid.
 
 **DESCRIPTION:**
 
 **NOTES:**
 
+.. _pthread_mutex_setprioceiling:
+
 pthread_mutex_setprioceiling - Dynamically Set the Priority Ceiling
 -------------------------------------------------------------------
 .. index:: pthread_mutex_setprioceiling
@@ -567,30 +614,33 @@ pthread_mutex_setprioceiling - Dynamically Set the Priority Ceiling
 
 **CALLING SEQUENCE:**
 
-.. code:: c
+.. code-block:: c
 
     #include <pthread.h>
     int pthread_mutex_setprioceiling(
-    pthread_mutex_t \*mutex,
+        pthread_mutex_t *mutex,
-    int              prioceiling,
+        int              prioceiling,
-    int             \*oldceiling
+        int             *oldceiling
     );
 
 **STATUS CODES:**
 
-*EINVAL*
+.. list-table::
-    The oldceiling pointer parameter is invalid.
+ :class: rtems-table
 
-*EINVAL*
+ * - ``EINVAL``
-    The prioceiling parameter is an invalid priority.
+   - The oldceiling pointer parameter is invalid.
-
+ * - ``EINVAL``
-*EINVAL*
+   - The prioceiling parameter is an invalid priority.
-    The specified mutex is invalid.
+ * - ``EINVAL``
+   - The specified mutex is invalid.
 
 **DESCRIPTION:**
 
 **NOTES:**
 
+.. _pthread_mutex_getprioceiling:
+
 pthread_mutex_getprioceiling - Get the Current Priority Ceiling
 ---------------------------------------------------------------
 .. index:: pthread_mutex_getprioceiling
@@ -598,29 +648,24 @@ pthread_mutex_getprioceiling - Get the Current Priority Ceiling
 
 **CALLING SEQUENCE:**
 
-.. code:: c
+.. code-block:: c
 
     #include <pthread.h>
     int pthread_mutex_getprioceiling(
-    pthread_mutex_t \*mutex,
+        pthread_mutex_t *mutex,
-    int             \*prioceiling
+        int             *prioceiling
     );
 
 **STATUS CODES:**
 
-*EINVAL*
+.. list-table::
-    The prioceiling pointer parameter is invalid.
+ :class: rtems-table
 
-*EINVAL*
+ * - ``EINVAL``
-    The specified mutex is invalid.
+   - The prioceiling pointer parameter is invalid.
+ * - ``EINVAL``
+   - The specified mutex is invalid.
 
 **DESCRIPTION:**
 
 **NOTES:**
-
-.. COMMENT: COPYRIGHT (c) 1988-2002.
-
-.. COMMENT: On-Line Applications Research Corporation (OAR).
-
-.. COMMENT: All rights reserved.
-

posix_users/preface.rst

@@ -1,11 +1,14 @@
+.. COMMENT: COPYRIGHT (c) 1988-2002.
+.. COMMENT: On-Line Applications Research Corporation (OAR).
+.. COMMENT: All rights reserved.
+
 Preface
 #######
 
-This is the User's Guide for the POSIX API support
+This is the User's Guide for the POSIX API support provided in RTEMS.
-provided in RTEMS.
 
-The functionality described in this document is based
+The functionality described in this document is based on the following
-on the following standards:
+standards:
 
 - POSIX 1003.1b-1993.
 
@@ -13,57 +16,35 @@ on the following standards:
 
 - Open Group Single UNIX Specification.
 
-Much of the POSIX API standard is actually implemented in the
+Much of the POSIX API standard is actually implemented in the Cygnus Newlib
-Cygnus Newlib ANSI C Library.  Please refer to documentation on
+ANSI C Library.  Please refer to documentation on Newlib for more information
-Newlib for more information on the functionality it supplies.
+on the functionality it supplies.
 
-This manual is still under construction and improvements
+This manual is still under construction and improvements are welcomed from
-are welcomed from users.
+users.
 
 Acknowledgements
 ================
 
-.. COMMENT: COPYRIGHT (c) 1988-2009.
+The RTEMS Project has been granted permission from The Open Group IEEE to
+excerpt and use portions of the POSIX standards documents in the RTEMS POSIX
+API User's Guide and RTEMS Shell User's Guide.  We have to include a specific
+acknowledgement paragraph in these documents (e.g. preface or copyright page)
+and another slightly different paragraph for each manual page that excerpts and
+uses text from the standards.
 
-.. COMMENT: On-Line Applications Research Corporation (OAR).
+This file should help ensure that the paragraphs are consistent and not
+duplicated
 
-.. COMMENT: All rights reserved.
+    The Institute of Electrical and Electronics Engineers, Inc and The Open
-
+    Group, have given us permission to reprint portions of their documentation.
-.. COMMENT: The RTEMS Project has been granted permission from The Open Group
+    Portions of this text are reprinted and reproduced in electronic form from
-
+    IEEE Std 1003.1, 2004 Edition, Standard for Information Technology
-.. COMMENT: IEEE to excerpt and use portions of the POSIX standards documents
+    Operating System Interface (POSIX), The Open Group Base Specifications
-
+    Issue 6, Copyright (c) 2001-2004 by the Institute of Electrical and
-.. COMMENT: in the RTEMS POSIX API User's Guide and RTEMS Shell User's Guide.
+    Electronics Engineers, Inc and The Open Group. In the event of any
-
+    discrepancy between this version and the original IEEE and The Open Group
-.. COMMENT: We have to include a specific acknowledgement paragraph in these
+    Standard, the original IEEE and The Open Group Standard is the referee
-
+    document. The original Standard can be obtained online at
-.. COMMENT: documents (e.g. preface or copyright page) and another slightly
+    http://www.opengroup.org/unix/online.html.
-
-.. COMMENT: different paragraph for each manual page that excerpts and uses
-
-.. COMMENT: text from the standards.
-
-.. COMMENT: This file should help ensure that the paragraphs are consistent
-
-.. COMMENT: and not duplicated
-
-    The Institute of Electrical and Electronics Engineers, Inc and The
-    Open Group, have given us permission to reprint portions of their
-    documentation.
-    Portions of this text are reprinted and reproduced in electronic
-    form from IEEE Std 1003.1, 2004 Edition, Standard for Information
-    Technology Operating System Interface (POSIX), The Open
-    Group Base Specifications Issue 6, Copyright (c) 2001-2004 by the
-    Institute of Electrical and Electronics Engineers, Inc and The
-    Open Group. In the event of any discrepancy between this version
-    and the original IEEE and The Open Group Standard, the original
-    IEEE and The Open Group Standard is the referee document. The
-    original Standard can be obtained online athttp://www.opengroup.org/unix/online.html.
     This notice shall appear on any product containing this material.
-
-.. COMMENT: COPYRIGHT (c) 1988-2002.
-
-.. COMMENT: On-Line Applications Research Corporation (OAR).
-
-.. COMMENT: All rights reserved.
-

posix_users/process_creation_and_execution.rst

@@ -1,66 +1,68 @@
+.. COMMENT: COPYRIGHT (c) 1988-2002.
+.. COMMENT: On-Line Applications Research Corporation (OAR).
+.. COMMENT: All rights reserved.
+
 Process Creation and Execution Manager
 ######################################
 
 Introduction
 ============
 
-The process creation and execution manager provides the
+The process creation and execution manager provides the functionality
-functionality associated with the creation and termination
+associated with the creation and termination of processes.
-of processes.
 
 The directives provided by the process creation and execution manager are:
 
-- ``fork`` - Create a Process
+- fork_ - Create a Process
 
-- ``execl`` - Execute a File
+- execl_ - Execute a File
 
-- ``execv`` - Execute a File
+- execv_ - Execute a File
 
-- ``execle`` - Execute a File
+- execle_ - Execute a File
 
-- ``execve`` - Execute a File
+- execve_ - Execute a File
 
-- ``execlp`` - Execute a File
+- execlp_ - Execute a File
 
-- ``execvp`` - Execute a File
+- execvp_ - Execute a File
 
-- ``pthread_atfork`` - Register Fork Handlers
+- pthread_atfork_ - Register Fork Handlers
 
-- ``wait`` - Wait for Process Termination
+- wait_ - Wait for Process Termination
 
-- ``waitpid`` - Wait for Process Termination
+- waitpid_ - Wait for Process Termination
 
-- ``_exit`` - Terminate a Process
+- `_exit`_ - Terminate a Process
 
 Background
 ==========
 
-POSIX process functionality can not be completely
+POSIX process functionality can not be completely supported by RTEMS.  This is
-supported by RTEMS.  This is because RTEMS provides no memory
+because RTEMS provides no memory protection and implements a *single process,
-protection and implements a *single process, multi-threaded
+multi-threaded execution model*.  In this light, RTEMS provides none of the
-execution model*.  In this light, RTEMS provides none of the
+routines that are associated with the creation of new processes.  However,
-routines that are associated with the creation of new processes.
+since the entire RTEMS application (e.g. executable) is logically a single
-However, since the entire RTEMS application (e.g. executable)
+POSIX process, RTEMS is able to provide implementations of many operations on
-is logically a single POSIX process, RTEMS is able to provide
+processes.  The rule of thumb is that those routines provide a meaningful
-implementations of many operations on processes.  The rule of
+result.  For example, ``getpid()`` returns the node number.
-thumb is that those routines provide a meaningful result.
-For example, ``getpid()`` returns the node number.
 
 Operations
 ==========
 
-The only functionality method defined by this manager which is
+The only functionality method defined by this manager which is supported by
-supported by RTEMS is the ``_exit`` service.  The
+RTEMS is the ``_exit`` service.  The implementation of ``_exit`` shuts the
-implementation of ``_exit`` shuts the application down and
+application down and is equivalent to invoking either ``exit`` or
-is equivalent to invoking either ``exit`` or``rtems_shutdown_executive``.
+``rtems_shutdown_executive``.
 
 Directives
 ==========
 
 This section details the process creation and execution manager's directives.
-A subsection is dedicated to each of this manager's directives
+A subsection is dedicated to each of this manager's directives and describes
-and describes the calling sequence, related constants, usage,
+the calling sequence, related constants, usage, and status codes.
-and status codes.
+
+.. _fork:
 
 fork - Create a Process
 -----------------------
@@ -69,15 +71,18 @@ fork - Create a Process
 
 **CALLING SEQUENCE:**
 
-.. code:: c
+.. code-block:: c
 
     #include <sys/types.h>
     int fork( void );
 
 **STATUS CODES:**
 
-*ENOSYS*
+.. list-table::
-    This routine is not supported by RTEMS.
+ :class: rtems-table
+
+ * - ``ENOSYS``
+   - This routine is not supported by RTEMS.
 
 **DESCRIPTION:**
 
@@ -87,6 +92,8 @@ This routine is not supported by RTEMS.
 
 NONE
 
+.. _execl:
+
 execl - Execute a File
 ----------------------
 .. index:: execl
@@ -94,18 +101,21 @@ execl - Execute a File
 
 **CALLING SEQUENCE:**
 
-.. code:: c
+.. code-block:: c
 
     int execl(
-    const char \*path,
+        const char *path,
-    const char \*arg,
+        const char *arg,
-    ...
+        ...
     );
 
 **STATUS CODES:**
 
-*ENOSYS*
+.. list-table::
-    This routine is not supported by RTEMS.
+ :class: rtems-table
+
+ * - ``ENOSYS``
+   - This routine is not supported by RTEMS.
 
 **DESCRIPTION:**
 
@@ -115,6 +125,8 @@ This routine is not supported by RTEMS.
 
 NONE
 
+.. _execv:
+
 execv - Execute a File
 ----------------------
 .. index:: execv
@@ -122,18 +134,21 @@ execv - Execute a File
 
 **CALLING SEQUENCE:**
 
-.. code:: c
+.. code-block:: c
 
     int execv(
-    const char \*path,
+        const char *path,
-    char const \*argv[],
+        char const *argv[],
-    ...
+        ...
     );
 
 **STATUS CODES:**
 
-*ENOSYS*
+.. list-table::
-    This routine is not supported by RTEMS.
+ :class: rtems-table
+
+ * - ``ENOSYS``
+   - This routine is not supported by RTEMS.
 
 **DESCRIPTION:**
 
@@ -143,6 +158,8 @@ This routine is not supported by RTEMS.
 
 NONE
 
+.. _execle:
+
 execle - Execute a File
 -----------------------
 .. index:: execle
@@ -150,18 +167,21 @@ execle - Execute a File
 
 **CALLING SEQUENCE:**
 
-.. code:: c
+.. code-block:: c
 
     int execle(
-    const char \*path,
+        const char *path,
-    const char \*arg,
+        const char *arg,
-    ...
+        ...
     );
 
 **STATUS CODES:**
 
-*ENOSYS*
+.. list-table::
-    This routine is not supported by RTEMS.
+ :class: rtems-table
+
+ * - ``ENOSYS``
+   - This routine is not supported by RTEMS.
 
 **DESCRIPTION:**
 
@@ -171,6 +191,8 @@ This routine is not supported by RTEMS.
 
 NONE
 
+.. _execve:
+
 execve - Execute a File
 -----------------------
 .. index:: execve
@@ -178,18 +200,21 @@ execve - Execute a File
 
 **CALLING SEQUENCE:**
 
-.. code:: c
+.. code-block:: c
 
     int execve(
-    const char \*path,
+        const char *path,
-    char \*const argv[],
+        char *const argv[],
-    char \*const envp[]
+        char *const envp[]
     );
 
 **STATUS CODES:**
 
-*ENOSYS*
+.. list-table::
-    This routine is not supported by RTEMS.
+ :class: rtems-table
+
+ * - ``ENOSYS``
+   - This routine is not supported by RTEMS.
 
 **DESCRIPTION:**
 
@@ -199,6 +224,8 @@ This routine is not supported by RTEMS.
 
 NONE
 
+.. _execlp:
+
 execlp - Execute a File
 -----------------------
 .. index:: execlp
@@ -206,18 +233,21 @@ execlp - Execute a File
 
 **CALLING SEQUENCE:**
 
-.. code:: c
+.. code-block:: c
 
     int execlp(
-    const char \*file,
+        const char *file,
-    const char \*arg,
+        const char *arg,
-    ...
+        ...
     );
 
 **STATUS CODES:**
 
-*ENOSYS*
+.. list-table::
-    This routine is not supported by RTEMS.
+ :class: rtems-table
+
+ * - ``ENOSYS``
+   - This routine is not supported by RTEMS.
 
 **DESCRIPTION:**
 
@@ -227,6 +257,8 @@ This routine is not supported by RTEMS.
 
 NONE
 
+.. _execvp:
+
 execvp - Execute a File
 -----------------------
 .. index:: execvp
@@ -234,18 +266,21 @@ execvp - Execute a File
 
 **CALLING SEQUENCE:**
 
-.. code:: c
+.. code-block:: c
 
     int execvp(
-    const char \*file,
+        const char *file,
-    char \*const argv[]
+        char *const argv[],
-    ...
+        ...
     );
 
 **STATUS CODES:**
 
-*ENOSYS*
+.. list-table::
-    This routine is not supported by RTEMS.
+ :class: rtems-table
+
+ * - ``ENOSYS``
+   - This routine is not supported by RTEMS.
 
 **DESCRIPTION:**
 
@@ -255,6 +290,8 @@ This routine is not supported by RTEMS.
 
 NONE
 
+.. _pthread_atfork:
+
 pthread_atfork - Register Fork Handlers
 ---------------------------------------
 .. index:: pthread_atfork
@@ -262,19 +299,22 @@ pthread_atfork - Register Fork Handlers
 
 **CALLING SEQUENCE:**
 
-.. code:: c
+.. code-block:: c
 
     #include <sys/types.h>
     int pthread_atfork(
-    void (\*prepare)(void),
+        void (*prepare)(void),
-    void (\*parent)(void),
+        void (*parent)(void),
-    void (\*child)(void)
+        void (*child)(void)
     );
 
 **STATUS CODES:**
 
-*ENOSYS*
+.. list-table::
-    This routine is not supported by RTEMS.
+ :class: rtems-table
+
+ * - ``ENOSYS``
+   - This routine is not supported by RTEMS.
 
 **DESCRIPTION:**
 
@@ -284,6 +324,8 @@ This routine is not supported by RTEMS.
 
 NONE
 
+.. _wait:
+
 wait - Wait for Process Termination
 -----------------------------------
 .. index:: wait
@@ -291,18 +333,21 @@ wait - Wait for Process Termination
 
 **CALLING SEQUENCE:**
 
-.. code:: c
+.. code-block:: c
 
     #include <sys/types.h>
     #include <sys/wait.h>
     int wait(
-    int \*stat_loc
+        int *stat_loc
     );
 
 **STATUS CODES:**
 
-*ENOSYS*
+.. list-table::
-    This routine is not supported by RTEMS.
+ :class: rtems-table
+
+ * - ``ENOSYS``
+   - This routine is not supported by RTEMS.
 
 **DESCRIPTION:**
 
@@ -312,6 +357,8 @@ This routine is not supported by RTEMS.
 
 NONE
 
+.. _waitpid:
+
 waitpid - Wait for Process Termination
 --------------------------------------
 .. index:: waitpid
@@ -319,18 +366,21 @@ waitpid - Wait for Process Termination
 
 **CALLING SEQUENCE:**
 
-.. code:: c
+.. code-block:: c
 
     int wait(
-    pid_t  pid,
+        pid_t  pid,
-    int   \*stat_loc,
+        int   *stat_loc,
-    int    options
+        int    options
     );
 
 **STATUS CODES:**
 
-*ENOSYS*
+.. list-table::
-    This routine is not supported by RTEMS.
+ :class: rtems-table
+
+ * - ``ENOSYS``
+   - This routine is not supported by RTEMS.
 
 **DESCRIPTION:**
 
@@ -340,6 +390,8 @@ This routine is not supported by RTEMS.
 
 NONE
 
+.. _\_exit:
+
 _exit - Terminate a Process
 ---------------------------
 .. index:: _exit
@@ -347,10 +399,10 @@ _exit - Terminate a Process
 
 **CALLING SEQUENCE:**
 
-.. code:: c
+.. code-block:: c
 
     void _exit(
-    int status
+        int status
     );
 
 **STATUS CODES:**
@@ -365,10 +417,3 @@ The ``_exit()`` function terminates the calling process.
 
 In RTEMS, a process is equivalent to the entire application on a single
 processor. Invoking this service terminates the application.
-
-.. COMMENT: COPYRIGHT (c) 1988-2002.
-
-.. COMMENT: On-Line Applications Research Corporation (OAR).
-
-.. COMMENT: All rights reserved.
-

posix_users/process_environment.rst

@@ -1,59 +1,63 @@
+.. COMMENT: COPYRIGHT (c) 1988-2002.
+.. COMMENT: On-Line Applications Research Corporation (OAR).
+.. COMMENT: All rights reserved.
+
 Process Environment Manager
 ###########################
 
 Introduction
 ============
 
-The process environment manager is responsible for providing the
+The process environment manager is responsible for providing the functions
-functions related to user and group Id management.
+related to user and group Id management.
 
 The directives provided by the process environment manager are:
 
-- ``getpid`` - Get Process ID
+- getpid_ - Get Process ID
 
-- ``getppid`` - Get Parent Process ID
+- getppid_ - Get Parent Process ID
 
-- ``getuid`` - Get User ID
+- getuid_ - Get User ID
 
-- ``geteuid`` - Get Effective User ID
+- geteuid_ - Get Effective User ID
 
-- ``getgid`` - Get Real Group ID
+- getgid_ - Get Real Group ID
 
-- ``getegid`` - Get Effective Group ID
+- getegid_ - Get Effective Group ID
 
-- ``setuid`` - Set User ID
+- setuid_ - Set User ID
 
-- ``setgid`` - Set Group ID
+- setgid_ - Set Group ID
 
-- ``getgroups`` - Get Supplementary Group IDs
+- getgroups_ - Get Supplementary Group IDs
 
-- ``getlogin`` - Get User Name
+- getlogin_ - Get User Name
 
-- ``getlogin_r`` - Reentrant Get User Name
+- getlogin_r_ - Reentrant Get User Name
 
-- ``getpgrp`` - Get Process Group ID
+- getpgrp_ - Get Process Group ID
 
-- ``setsid`` - Create Session and Set Process Group ID
+- setsid_ - Create Session and Set Process Group ID
 
-- ``setpgid`` - Set Process Group ID for Job Control
+- setpgid_ - Set Process Group ID for Job Control
 
-- ``uname`` - Get System Name
+- uname_ - Get System Name
 
-- ``times`` - Get Process Times
+- times_ - Get Process Times
 
-- ``getenv`` - Get Environment Variables
+- getenv_ - Get Environment Variables
 
-- ``setenv`` - Set Environment Variables
+- setenv_ - Set Environment Variables
 
-- ``ctermid`` - Generate Terminal Pathname
+- ctermid_ - Generate Terminal Pathname
 
-- ``ttyname`` - Determine Terminal Device Name
+- ttyname_ - Determine Terminal Device Name
 
-- ``ttyname_r`` - Reentrant Determine Terminal Device Name
+- ttyname_r_ - Reentrant Determine Terminal Device Name
 
-- ``isatty`` - Determine if File Descriptor is Terminal
+- isatty_ - Determine if File Descriptor is Terminal
 
-- ``sysconf`` - Get Configurable System Variables
+- sysconf_ - Get Configurable System Variables
 
 Background
 ==========
@@ -61,51 +65,45 @@ Background
 Users and Groups
 ----------------
 
-RTEMS provides a single process, multi-threaded execution environment.
+RTEMS provides a single process, multi-threaded execution environment.  In this
-In this light, the notion of user and group is somewhat without meaning.
+light, the notion of user and group is somewhat without meaning.  But RTEMS
-But RTEMS does provide services to provide a synthetic version of
+does provide services to provide a synthetic version of user and group.  By
-user and group.  By default, a single user and group is associated
+default, a single user and group is associated with the application.  Thus
-with the application.  Thus unless special actions are taken,
+unless special actions are taken, every thread in the application shares the
-every thread in the application shares the same user and group Id.
+same user and group Id.  The initial rationale for providing user and group Id
-The initial rationale for providing user and group Id functionality
+functionality in RTEMS was for the filesystem infrastructure to implement file
-in RTEMS was for the filesystem infrastructure to implement
+permission checks.  The effective user/group Id capability has since been used
-file permission checks.  The effective user/group Id capability
+to implement permissions checking by the ``ftpd`` server.
-has since been used to implement permissions checking by
-the ``ftpd`` server.
 
-In addition to the "real" user and group Ids, a process may
+In addition to the "real" user and group Ids, a process may have an effective
-have an effective user/group Id.  This allows a process to
+user/group Id.  This allows a process to function using a more limited
-function using a more limited permission set for certain operations.
+permission set for certain operations.
 
 User and Group Names
 --------------------
 
-POSIX considers user and group Ids to be a unique integer that
+POSIX considers user and group Ids to be a unique integer that may be
-may be associated with a name.  This is usually accomplished
+associated with a name.  This is usually accomplished via a file named
-via a file named ``/etc/passwd`` for user Id mapping and``/etc/groups`` for group Id mapping.  Again, although
+:file:`/etc/passwd` for user Id mapping and :file:`/etc/groups` for group Id
-RTEMS is effectively a single process and thus single user
+mapping.  Again, although RTEMS is effectively a single process and thus single
-system, it provides limited support for user and group
+user system, it provides limited support for user and group names.  When
-names.  When configured with an appropriate filesystem, RTEMS
+configured with an appropriate filesystem, RTEMS will access the appropriate
-will access the appropriate files to map user and group Ids
+files to map user and group Ids to names.
-to names.
 
-If these files do not exist, then RTEMS will synthesize
+If these files do not exist, then RTEMS will synthesize a minimal version so
-a minimal version so this family of services return without
+this family of services return without error.  It is important to remember that
-error.  It is important to remember that a design goal of
+a design goal of the RTEMS POSIX services is to provide useable and meaningful
-the RTEMS POSIX services is to provide useable and
+results even though a full process model is not available.
-meaningful results even though a full process model
-is not available.
 
 Environment Variables
 ---------------------
 
-POSIX allows for variables in the run-time environment.  These are
+POSIX allows for variables in the run-time environment.  These are name/value
-name/value pairs that make be dynamically set and obtained by
+pairs that make be dynamically set and obtained by programs.  In a full POSIX
-programs.  In a full POSIX environment with command line shell
+environment with command line shell and multiple processes, environment
-and multiple processes,  environment variables may be set in
+variables may be set in one process - such as the shell - and inherited by
-one process - such as the shell - and inherited by child
+child processes.  In RTEMS, there is only one process and thus only one set of
-processes.  In RTEMS, there is only one process and thus
+environment variables across all processes.
-only one set of environment variables across all processes.
 
 Operations
 ==========
@@ -113,24 +111,24 @@ Operations
 Accessing User and Group Ids
 ----------------------------
 
-The user Id associated with the current thread may be obtain
+The user Id associated with the current thread may be obtain using the
-using the ``getuid()`` service.  Similarly, the group Id
+``getuid()`` service.  Similarly, the group Id may be obtained using the
-may be obtained using the ``getgid()`` service.
+``getgid()`` service.
 
 Accessing Environment Variables
 -------------------------------
 
-The value associated with an environment variable may be
+The value associated with an environment variable may be obtained using the
-obtained using the ``getenv()`` service and set using
+``getenv()`` service and set using the ``putenv()`` service.
-the ``putenv()`` service.
 
 Directives
 ==========
 
-This section details the process environment manager's directives.
+This section details the process environment manager's directives.  A
-A subsection is dedicated to each of this manager's directives
+subsection is dedicated to each of this manager's directives and describes the
-and describes the calling sequence, related constants, usage,
+calling sequence, related constants, usage, and status codes.
-and status codes.
+
+.. _getpid:
 
 getpid - Get Process ID
 -----------------------
@@ -139,7 +137,7 @@ getpid - Get Process ID
 
 **CALLING SEQUENCE:**
 
-.. code:: c
+.. code-block:: c
 
     int getpid( void );
 
@@ -155,6 +153,8 @@ This service returns the process Id.
 
 NONE
 
+.. _getppid:
+
 getppid - Get Parent Process ID
 -------------------------------
 .. index:: getppid
@@ -162,7 +162,7 @@ getppid - Get Parent Process ID
 
 **CALLING SEQUENCE:**
 
-.. code:: c
+.. code-block:: c
 
     int getppid( void );
 
@@ -178,6 +178,8 @@ This service returns the parent process Id.
 
 NONE
 
+.. _getuid:
+
 getuid - Get User ID
 --------------------
 .. index:: getuid
@@ -185,7 +187,7 @@ getuid - Get User ID
 
 **CALLING SEQUENCE:**
 
-.. code:: c
+.. code-block:: c
 
     int getuid( void );
 
@@ -201,6 +203,8 @@ This service returns the effective user Id.
 
 NONE
 
+.. _geteuid:
+
 geteuid - Get Effective User ID
 -------------------------------
 .. index:: geteuid
@@ -208,7 +212,7 @@ geteuid - Get Effective User ID
 
 **CALLING SEQUENCE:**
 
-.. code:: c
+.. code-block:: c
 
     int geteuid( void );
 
@@ -224,6 +228,8 @@ This service returns the effective group Id.
 
 NONE
 
+.. _getgid:
+
 getgid - Get Real Group ID
 --------------------------
 .. index:: getgid
@@ -231,7 +237,7 @@ getgid - Get Real Group ID
 
 **CALLING SEQUENCE:**
 
-.. code:: c
+.. code-block:: c
 
     int getgid( void );
 
@@ -247,6 +253,8 @@ This service returns the group Id.
 
 NONE
 
+.. _getegid:
+
 getegid - Get Effective Group ID
 --------------------------------
 .. index:: getegid
@@ -254,7 +262,7 @@ getegid - Get Effective Group ID
 
 **CALLING SEQUENCE:**
 
-.. code:: c
+.. code-block:: c
 
     int getegid( void );
 
@@ -270,6 +278,8 @@ This service returns the effective group Id.
 
 NONE
 
+.. _setuid:
+
 setuid - Set User ID
 --------------------
 .. index:: setuid
@@ -277,10 +287,10 @@ setuid - Set User ID
 
 **CALLING SEQUENCE:**
 
-.. code:: c
+.. code-block:: c
 
     int setuid(
-    uid_t uid
+        uid_t uid
     );
 
 **STATUS CODES:**
@@ -295,6 +305,8 @@ This service sets the user Id to ``uid``.
 
 NONE
 
+.. _setgid:
+
 setgid - Set Group ID
 ---------------------
 .. index:: setgid
@@ -302,10 +314,10 @@ setgid - Set Group ID
 
 **CALLING SEQUENCE:**
 
-.. code:: c
+.. code-block:: c
 
     int setgid(
-    gid_t  gid
+        gid_t  gid
     );
 
 **STATUS CODES:**
@@ -320,6 +332,8 @@ This service sets the group Id to ``gid``.
 
 NONE
 
+.. _getgroups:
+
 getgroups - Get Supplementary Group IDs
 ---------------------------------------
 .. index:: getgroups
@@ -327,11 +341,11 @@ getgroups - Get Supplementary Group IDs
 
 **CALLING SEQUENCE:**
 
-.. code:: c
+.. code-block:: c
 
     int getgroups(
-    int    gidsetsize,
+        int    gidsetsize,
-    gid_t  grouplist[]
+        gid_t  grouplist[]
     );
 
 **STATUS CODES:**
@@ -340,13 +354,13 @@ NA
 
 **DESCRIPTION:**
 
-This service is not implemented as RTEMS has no notion of
+This service is not implemented as RTEMS has no notion of supplemental groups.
-supplemental groups.
 
 **NOTES:**
 
-If supported, this routine would only be allowed for
+If supported, this routine would only be allowed for the super-user.
-the super-user.
+
+.. _getlogin:
 
 getlogin - Get User Name
 ------------------------
@@ -355,14 +369,13 @@ getlogin - Get User Name
 
 **CALLING SEQUENCE:**
 
-.. code:: c
+.. code-block:: c
 
-    char \*getlogin( void );
+    char *getlogin( void );
 
 **STATUS CODES:**
 
-Returns a pointer to a string containing the name of the
+Returns a pointer to a string containing the name of the current user.
-current user.
 
 **DESCRIPTION:**
 
@@ -370,7 +383,10 @@ This routine returns the name of the current user.
 
 **NOTES:**
 
-This routine is not reentrant and subsequent calls to``getlogin()`` will overwrite the same buffer.
+This routine is not reentrant and subsequent calls to ``getlogin()`` will
+overwrite the same buffer.
+
+.. _getlogin_r:
 
 getlogin_r - Reentrant Get User Name
 ------------------------------------
@@ -380,28 +396,33 @@ getlogin_r - Reentrant Get User Name
 
 **CALLING SEQUENCE:**
 
-.. code:: c
+.. code-block:: c
 
     int getlogin_r(
-    char   \*name,
+        char   *name,
-    size_t  namesize
+        size_t  namesize
     );
 
 **STATUS CODES:**
 
-*EINVAL*
+.. list-table::
-    The arguments were invalid.
+ :class: rtems-table
+
+ * - ``EINVAL``
+   - The arguments were invalid.
 
 **DESCRIPTION:**
 
-This is a reentrant version of the ``getlogin()`` service.  The
+This is a reentrant version of the ``getlogin()`` service.  The caller
-caller specified their own buffer, ``name``, as well as the
+specified their own buffer, ``name``, as well as the length of this buffer,
-length of this buffer, ``namesize``.
+``namesize``.
 
 **NOTES:**
 
 NONE
 
+.. _getpgrp:
+
 getpgrp - Get Process Group ID
 ------------------------------
 .. index:: getpgrp
@@ -409,7 +430,7 @@ getpgrp - Get Process Group ID
 
 **CALLING SEQUENCE:**
 
-.. code:: c
+.. code-block:: c
 
     pid_t getpgrp( void );
 
@@ -423,8 +444,10 @@ This service returns the current progress group Id.
 
 **NOTES:**
 
-This routine is implemented in a somewhat meaningful
+This routine is implemented in a somewhat meaningful way for RTEMS but is truly
-way for RTEMS but is truly not functional.
+not functional.
+
+.. _setsid:
 
 setsid - Create Session and Set Process Group ID
 ------------------------------------------------
@@ -433,25 +456,29 @@ setsid - Create Session and Set Process Group ID
 
 **CALLING SEQUENCE:**
 
-.. code:: c
+.. code-block:: c
 
     pid_t setsid( void );
 
 **STATUS CODES:**
 
-*EPERM*
+.. list-table::
-    The application does not have permission to create a process group.
+ :class: rtems-table
+
+ * - ``EPERM``
+   - The application does not have permission to create a process group.
 
 **DESCRIPTION:**
 
-This routine always returns ``EPERM`` as RTEMS has no way
+This routine always returns ``EPERM`` as RTEMS has no way to create new
-to create new processes and thus no way to create a new process
+processes and thus no way to create a new process group.
-group.
 
 **NOTES:**
 
 NONE
 
+.. _setpgid:
+
 setpgid - Set Process Group ID for Job Control
 ----------------------------------------------
 .. index:: setpgid
@@ -459,27 +486,31 @@ setpgid - Set Process Group ID for Job Control
 
 **CALLING SEQUENCE:**
 
-.. code:: c
+.. code-block:: c
 
     int setpgid(
-    pid_t pid,
+        pid_t pid,
-    pid_t pgid
+        pid_t pgid
     );
 
 **STATUS CODES:**
 
-*ENOSYS*
+.. list-table::
-    The routine is not implemented.
+ :class: rtems-table
+
+ * - ``ENOSYS``
+   - The routine is not implemented.
 
 **DESCRIPTION:**
 
-This service is not implemented for RTEMS as process groups are not
+This service is not implemented for RTEMS as process groups are not supported.
-supported.
 
 **NOTES:**
 
 NONE
 
+.. _uname:
+
 uname - Get System Name
 -----------------------
 .. index:: uname
@@ -487,29 +518,33 @@ uname - Get System Name
 
 **CALLING SEQUENCE:**
 
-.. code:: c
+.. code-block:: c
 
     int uname(
-    struct utsname \*name
+        struct utsname \*name
     );
 
 **STATUS CODES:**
 
-*EPERM*
+.. list-table::
-    The provided structure pointer is invalid.
+ :class: rtems-table
+
+ * - ``EPERM``
+   - The provided structure pointer is invalid.
 
 **DESCRIPTION:**
 
-This service returns system information to the caller.  It does this
+This service returns system information to the caller.  It does this by filling
-by filling in the ``struct utsname`` format structure for the
+in the ``struct utsname`` format structure for the caller.
-caller.
 
 **NOTES:**
 
-The information provided includes the operating system (RTEMS in
+The information provided includes the operating system (RTEMS in all
-all configurations), the node number, the release as the RTEMS
+configurations), the node number, the release as the RTEMS version, and the CPU
-version, and the CPU family and model.  The CPU model name
+family and model.  The CPU model name will indicate the multilib executive
-will indicate the multilib executive variant being used.
+variant being used.
+
+.. _times:
 
 times - Get process times
 -------------------------
@@ -518,32 +553,32 @@ times - Get process times
 
 **CALLING SEQUENCE:**
 
-.. code:: c
+.. code-block:: c
 
     #include <sys/time.h>
     clock_t times(
-    struct tms \*ptms
+        struct tms *ptms
     );
 
 **STATUS CODES:**
 
-This routine returns the number of clock ticks that have elapsed
+This routine returns the number of clock ticks that have elapsed since the
-since the system was initialized (e.g. the application was
+system was initialized (e.g. the application was started).
-started).
 
 **DESCRIPTION:**
 
-``times`` stores the current process times in ``ptms``.  The
+``times`` stores the current process times in ``ptms``.  The format of ``struct
-format of ``struct tms`` is as defined in``<sys/times.h>``.  RTEMS fills in the field ``tms_utime``
+tms`` is as defined in ``<sys/times.h>``.  RTEMS fills in the field
-with the number of ticks that the calling thread has executed
+``tms_utime`` with the number of ticks that the calling thread has executed and
-and the field ``tms_stime`` with the number of clock ticks
+the field ``tms_stime`` with the number of clock ticks since system boot (also
-since system boot (also returned).  All other fields in the``ptms`` are left zero.
+returned).  All other fields in the ``ptms`` are left zero.
 
 **NOTES:**
 
-RTEMS has no way to distinguish between user and system time
+RTEMS has no way to distinguish between user and system time so this routine
-so this routine returns the most meaningful information
+returns the most meaningful information possible.
-possible.
+
+.. _getenv:
 
 getenv - Get Environment Variables
 ----------------------------------
@@ -552,30 +587,33 @@ getenv - Get Environment Variables
 
 **CALLING SEQUENCE:**
 
-.. code:: c
+.. code-block:: c
 
-    char \*getenv(
+    char *getenv(
-    const char \*name
+        const char \*name
     );
 
 **STATUS CODES:**
 
-*NULL*
+.. list-table::
-    when no match
+ :class: rtems-table
 
-*pointer to value*
+ * - ``NULL``
-    when successful
+   - when no match
+ * - `pointer to value`
+   - when successful
 
 **DESCRIPTION:**
 
-This service searches the set of environment variables for
+This service searches the set of environment variables for a string that
-a string that matches the specified ``name``.  If found,
+matches the specified ``name``.  If found, it returns the associated value.
-it returns the associated value.
 
 **NOTES:**
 
-The environment list consists of name value pairs that
+The environment list consists of name value pairs that are of the form ``name =
-are of the form *name = value*.
+value``.
+
+.. _setenv:
 
 setenv - Set Environment Variables
 ----------------------------------
@@ -584,12 +622,12 @@ setenv - Set Environment Variables
 
 **CALLING SEQUENCE:**
 
-.. code:: c
+.. code-block:: c
 
     int setenv(
-    const char \*name,
+        const char *name,
-    const char \*value,
+        const char *value,
-    int overwrite
+        int overwrite
     );
 
 **STATUS CODES:**
@@ -598,14 +636,16 @@ Returns 0 if successful and -1 otherwise.
 
 **DESCRIPTION:**
 
-This service adds the variable ``name`` to the environment with``value``.  If ``name`` is not already exist, then it is
+This service adds the variable ``name`` to the environment with ``value``.  If
-created.  If ``name`` exists and ``overwrite`` is zero, then
+``name`` is not already exist, then it is created.  If ``name`` exists and
-the previous value is not overwritten.
+``overwrite`` is zero, then the previous value is not overwritten.
 
 **NOTES:**
 
 NONE
 
+.. _ctermid:
+
 ctermid - Generate Terminal Pathname
 ------------------------------------
 .. index:: ctermid
@@ -613,10 +653,10 @@ ctermid - Generate Terminal Pathname
 
 **CALLING SEQUENCE:**
 
-.. code:: c
+.. code-block:: c
 
-    char \*ctermid(
+    char *ctermid(
-    char \*s
+        char *s
     );
 
 **STATUS CODES:**
@@ -626,18 +666,19 @@ terminal.
 
 **DESCRIPTION:**
 
-This service returns the name of the terminal device associated with
+This service returns the name of the terminal device associated with this
-this process.  If ``s`` is NULL, then a pointer to a static buffer
+process.  If ``s`` is NULL, then a pointer to a static buffer is returned.
-is returned.  Otherwise, ``s`` is assumed to have a buffer of
+Otherwise, ``s`` is assumed to have a buffer of sufficient size to contain the
-sufficient size to contain the name of the controlling terminal.
+name of the controlling terminal.
 
 **NOTES:**
 
-By default on RTEMS systems, the controlling terminal is ``/dev/console``.
+By default on RTEMS systems, the controlling terminal is :file:`/dev/console`.
-Again this implementation is of limited meaning, but it provides
+Again this implementation is of limited meaning, but it provides true and
-true and useful results which should be sufficient to ease porting
+useful results which should be sufficient to ease porting applications from a
-applications from a full POSIX implementation to the reduced
+full POSIX implementation to the reduced profile supported by RTEMS.
-profile supported by RTEMS.
+
+.. _ttyname:
 
 ttyname - Determine Terminal Device Name
 ----------------------------------------
@@ -646,27 +687,29 @@ ttyname - Determine Terminal Device Name
 
 **CALLING SEQUENCE:**
 
-.. code:: c
+.. code-block:: c
 
-    char \*ttyname(
+    char *ttyname(
-    int fd
+        int fd
     );
 
 **STATUS CODES:**
 
-Pointer to a string containing the terminal device name or
+Pointer to a string containing the terminal device name or ``NULL`` is returned
-NULL is returned on any error.
+on any error.
 
 **DESCRIPTION:**
 
-This service returns a pointer to the pathname of the terminal
+This service returns a pointer to the pathname of the terminal device that is
-device that is open on the file descriptor ``fd``.  If``fd`` is not a valid descriptor for a terminal device,
+open on the file descriptor ``fd``.  If ``fd`` is not a valid descriptor for a
-then NULL is returned.
+terminal device, then NULL is returned.
 
 **NOTES:**
 
 This routine uses a static buffer.
 
+.. _ttyname_r:
+
 ttyname_r - Reentrant Determine Terminal Device Name
 ----------------------------------------------------
 .. index:: ttyname_r
@@ -674,33 +717,37 @@ ttyname_r - Reentrant Determine Terminal Device Name
 
 **CALLING SEQUENCE:**
 
-.. code:: c
+.. code-block:: c
 
     int ttyname_r(
-    int   fd,
+        int   fd,
-    char \*name,
+        char *name,
-    int   namesize
+        int   namesize
     );
 
 **STATUS CODES:**
 
 This routine returns -1 and sets ``errno`` as follows:
 
-*EBADF*
+.. list-table::
-    If not a valid descriptor for a terminal device.
+ :class: rtems-table
 
-*EINVAL*
+ * - ``EBADF``
-    If ``name`` is NULL or ``namesize`` are insufficient.
+   - If not a valid descriptor for a terminal device.
+ * - ``EINVAL``
+   - If ``name`` is ``NULL`` or ``namesize`` are insufficient.
 
 **DESCRIPTION:**
 
-This service the pathname of the terminal device that is open
+This service the pathname of the terminal device that is open on the file
-on the file descriptor ``fd``.
+descriptor ``fd``.
 
 **NOTES:**
 
 NONE
 
+.. _isatty:
+
 isatty - Determine if File Descriptor is Terminal
 -------------------------------------------------
 .. index:: isatty
@@ -708,10 +755,10 @@ isatty - Determine if File Descriptor is Terminal
 
 **CALLING SEQUENCE:**
 
-.. code:: c
+.. code-block:: c
 
     int isatty(
-    int fd
+        int fd
     );
 
 **STATUS CODES:**
@@ -720,11 +767,13 @@ Returns 1 if ``fd`` is a terminal device and 0 otherwise.
 
 **DESCRIPTION:**
 
-This service returns 1 if ``fd`` is an open file descriptor
+This service returns 1 if ``fd`` is an open file descriptor connected to a
-connected to a terminal and 0 otherwise.
+terminal and 0 otherwise.
 
 **NOTES:**
 
+.. _sysconf:
+
 sysconf - Get Configurable System Variables
 -------------------------------------------
 .. index:: sysconf
@@ -732,34 +781,25 @@ sysconf - Get Configurable System Variables
 
 **CALLING SEQUENCE:**
 
-.. code:: c
+.. code-block:: c
 
     long sysconf(
-    int name
+        int name
     );
 
 **STATUS CODES:**
 
-The value returned is the actual value of the system resource.
+The value returned is the actual value of the system resource.  If the
-If the requested configuration name is a feature flag, then
+requested configuration name is a feature flag, then 1 is returned if the
-1 is returned if the available and 0 if it is not.  On any
+available and 0 if it is not.  On any other error condition, -1 is returned.
-other error condition, -1 is returned.
 
 **DESCRIPTION:**
 
-This service is the mechanism by which an application determines
+This service is the mechanism by which an application determines values for
-values for system limits or options at runtime.
+system limits or options at runtime.
 
 **NOTES:**
 
-Much of the information that may be obtained via ``sysconf``
+Much of the information that may be obtained via ``sysconf`` has equivalent
-has equivalent macros in ``<unistd.h``.  However, those
+macros in ``unistd.h``.  However, those macros reflect conservative limits
-macros reflect conservative limits which may have been altered
+which may have been altered by application configuration.
-by application configuration.
-
-.. COMMENT: COPYRIGHT (c) 1988-2002.
-
-.. COMMENT: On-Line Applications Research Corporation (OAR).
-
-.. COMMENT: All rights reserved.
-

posix_users/scheduler.rst

@@ -1,3 +1,7 @@
+.. COMMENT: COPYRIGHT (c) 1988-2002.
+.. COMMENT: On-Line Applications Research Corporation (OAR).
+.. COMMENT: All rights reserved.
+
 Scheduler Manager
 #################
 
@@ -8,13 +12,13 @@ The scheduler manager ...
 
 The directives provided by the scheduler manager are:
 
-- ``sched_get_priority_min`` - Get Minimum Priority Value
+- sched_get_priority_min_ - Get Minimum Priority Value
 
-- ``sched_get_priority_max`` - Get Maximum Priority Value
+- sched_get_priority_max_ - Get Maximum Priority Value
 
-- ``sched_rr_get_interval`` - Get Timeslicing Quantum
+- sched_rr_get_interval_ - Get Timeslicing Quantum
 
-- ``sched_yield`` - Yield the Processor
+- sched_yield_ - Yield the Processor
 
 Background
 ==========
@@ -22,8 +26,9 @@ Background
 Priority
 --------
 
-In the RTEMS implementation of the POSIX API, the priorities range from
+In the RTEMS implementation of the POSIX API, the priorities range from the low
-the low priority of ``sched_get_priority_min()`` to the highest priority of``sched_get_priority_max()``. Numerically higher values represent higher
+priority of ``sched_get_priority_min()`` to the highest priority of
+``sched_get_priority_max()``. Numerically higher values represent higher
 priorities.
 
 Scheduling Policies
@@ -32,8 +37,8 @@ Scheduling Policies
 The following scheduling policies are available:
 
 *SCHED_FIFO*
-    Priority-based, preemptive scheduling with no timeslicing. This is equivalent
+    Priority-based, preemptive scheduling with no timeslicing. This is
-    to what is called "manual round-robin" scheduling.
+    equivalent to what is called "manual round-robin" scheduling.
 
 *SCHED_RR*
     Priority-based, preemptive scheduling with timeslicing. Time quantums are
@@ -46,11 +51,12 @@ The following scheduling policies are available:
     maintained on a per-thread basis and are reset at each context switch.
 
 *SCHED_SPORADIC*
-    Priority-based, preemptive scheduling utilizing three additional parameters:
+    Priority-based, preemptive scheduling utilizing three additional
-    budget, replenishment period, and low priority. Under this policy, the
+    parameters: budget, replenishment period, and low priority. Under this
-    thread is allowed to execute for "budget" amount of time before its priority
+    policy, the thread is allowed to execute for "budget" amount of time before
-    is lowered to "low priority". At the end of each replenishment period,
+    its priority is lowered to "low priority". At the end of each replenishment
-    the thread resumes its initial priority and has its budget replenished.
+    period, the thread resumes its initial priority and has its budget
+    replenished.
 
 Operations
 ==========
@@ -60,10 +66,11 @@ There is currently no text in this section.
 Directives
 ==========
 
-This section details the scheduler manager's directives.
+This section details the scheduler manager's directives.  A subsection is
-A subsection is dedicated to each of this manager's directives
+dedicated to each of this manager's directives and describes the calling
-and describes the calling sequence, related constants, usage,
+sequence, related constants, usage, and status codes.
-and status codes.
+
+.. _sched_get_priority_min:
 
 sched_get_priority_min - Get Minimum Priority Value
 ---------------------------------------------------
@@ -72,29 +79,34 @@ sched_get_priority_min - Get Minimum Priority Value
 
 **CALLING SEQUENCE:**
 
-.. code:: c
+.. code-block:: c
 
     #include <sched.h>
     int sched_get_priority_min(
-    int policy
+        int policy
     );
 
 **STATUS CODES:**
 
-On error, this routine returns -1 and sets errno to one of the following:
+On error, this routine returns -1 and sets ``errno`` to one of the following:
 
-*EINVAL*
+.. list-table::
-    The indicated policy is invalid.
+ :class: rtems-table
+
+ * - ``EINVAL``
+   - The indicated policy is invalid.
 
 **DESCRIPTION:**
 
-This routine return the minimum (numerically and logically lowest) priority
+This routine return the minimum (numerically and logically lowest) priority for
-for the specified ``policy``.
+the specified ``policy``.
 
 **NOTES:**
 
 NONE
 
+.. _sched_get_priority_max:
+
 sched_get_priority_max - Get Maximum Priority Value
 ---------------------------------------------------
 .. index:: sched_get_priority_max
@@ -102,19 +114,22 @@ sched_get_priority_max - Get Maximum Priority Value
 
 **CALLING SEQUENCE:**
 
-.. code:: c
+.. code-block:: c
 
     #include <sched.h>
     int sched_get_priority_max(
-    int policy
+        int policy
     );
 
 **STATUS CODES:**
 
-On error, this routine returns -1 and sets errno to one of the following:
+On error, this routine returns -1 and sets ``errno`` to one of the following:
 
-*EINVAL*
+.. list-table::
-    The indicated policy is invalid.
+ :class: rtems-table
+
+ * - ``EINVAL``
+   - The indicated policy is invalid.
 
 **DESCRIPTION:**
 
@@ -125,6 +140,8 @@ for the specified ``policy``.
 
 NONE
 
+.. _sched_rr_get_interval:
+
 sched_rr_get_interval - Get Timeslicing Quantum
 -----------------------------------------------
 .. index:: sched_rr_get_interval
@@ -132,32 +149,37 @@ sched_rr_get_interval - Get Timeslicing Quantum
 
 **CALLING SEQUENCE:**
 
-.. code:: c
+.. code-block:: c
 
     #include <sched.h>
     int sched_rr_get_interval(
-    pid_t            pid,
+        pid_t            pid,
-    struct timespec \*interval
+        struct timespec *interval
     );
 
 **STATUS CODES:**
 
-On error, this routine returns -1 and sets errno to one of the following:
+On error, this routine returns -1 and sets ``errno`` to one of the following:
 
-*ESRCH*
+.. list-table::
-    The indicated process id is invalid.
+ :class: rtems-table
 
-*EINVAL*
+ * - ``ESRCH``
-    The specified interval pointer parameter is invalid.
+   - The indicated process id is invalid.
+ * - ``EINVAL``
+   - The specified interval pointer parameter is invalid.
 
 **DESCRIPTION:**
 
-This routine returns the length of the timeslice quantum in the``interval`` parameter for the specified ``pid``.
+This routine returns the length of the timeslice quantum in the ``interval``
+parameter for the specified ``pid``.
 
 **NOTES:**
 
 The ``pid`` argument should be 0 to indicate the calling process.
 
+.. _sched_yield:
+
 sched_yield - Yield the Processor
 ---------------------------------
 .. index:: sched_yield
@@ -165,7 +187,7 @@ sched_yield - Yield the Processor
 
 **CALLING SEQUENCE:**
 
-.. code:: c
+.. code-block:: c
 
     #include <sched.h>
     int sched_yield( void );
@@ -177,16 +199,9 @@ This routine always returns zero to indicate success.
 **DESCRIPTION:**
 
 This call forces the calling thread to yield the processor to another
-thread. Normally this is used to implement voluntary round-robin
+thread. Normally this is used to implement voluntary round-robin task
-task scheduling.
+scheduling.
 
 **NOTES:**
 
 NONE
-
-.. COMMENT: COPYRIGHT (c) 1988-2002.
-
-.. COMMENT: On-Line Applications Research Corporation (OAR).
-
-.. COMMENT: All rights reserved.
-

posix_users/semaphore.rst

@@ -1,3 +1,7 @@
+.. COMMENT: COPYRIGHT (c) 1989-2008.
+.. COMMENT: On-Line Applications Research Corporation (OAR).
+.. COMMENT: All rights reserved.
+
 Semaphore Manager
 #################
 
@@ -9,25 +13,25 @@ semaphores. This manager is based on the POSIX 1003.1 standard.
 
 The directives provided by the semaphore manager are:
 
-- ``sem_init`` - Initialize an unnamed semaphore
+- sem_init_ - Initialize an unnamed semaphore
 
-- ``sem_destroy`` - Destroy an unnamed semaphore
+- sem_destroy_ - Destroy an unnamed semaphore
 
-- ``sem_open`` - Open a named semaphore
+- sem_open_ - Open a named semaphore
 
-- ``sem_close`` - Close a named semaphore
+- sem_close_ - Close a named semaphore
 
-- ``sem_unlink`` - Remove a named semaphore
+- sem_unlink_ - Remove a named semaphore
 
-- ``sem_wait`` - Lock a semaphore
+- sem_wait_ - Lock a semaphore
 
-- ``sem_trywait`` - Lock a semaphore
+- sem_trywait_ - Lock a semaphore
 
-- ``sem_timedwait`` - Wait on a Semaphore for a Specified Time
+- sem_timedwait_ - Wait on a Semaphore for a Specified Time
 
-- ``sem_post`` - Unlock a semaphore
+- sem_post_ - Unlock a semaphore
 
-- ``sem_getvalue`` - Get the value of a semeaphore
+- sem_getvalue_ - Get the value of a semeaphore
 
 Background
 ==========
@@ -51,7 +55,8 @@ semaphore, the tasks will be placed in the queue.
 
 The ``sem_t`` structure is used to represent semaphores. It is passed as an
 argument to the semaphore directives and is defined as follows:
-.. code:: c
+
+.. code-block:: c
 
     typedef int sem_t;
 
@@ -71,17 +76,19 @@ Creating a semaphore with a limit on the count of 1 effectively restricts the
 semaphore to being a binary semaphore. When the binary semaphore is available,
 the count is 1. When the binary semaphore is unavailable, the count is 0.
 
-Since this does not result in a true binary semaphore, advanced binary features like the Priority Inheritance and Priority Ceiling Protocols are not available.
+Since this does not result in a true binary semaphore, advanced binary features
+like the Priority Inheritance and Priority Ceiling Protocols are not available.
 
 There is currently no text in this section.
 
 Directives
 ==========
 
-This section details the semaphore manager's directives.
+This section details the semaphore manager's directives.  A subsection is
-A subsection is dedicated to each of this manager's directives
+dedicated to each of this manager's directives and describes the calling
-and describes the calling sequence, related constants, usage,
+sequence, related constants, usage, and status codes.
-and status codes.
+
+.. _sem_init:
 
 sem_init - Initialize an unnamed semaphore
 ------------------------------------------
@@ -90,45 +97,47 @@ sem_init - Initialize an unnamed semaphore
 
 **CALLING SEQUENCE:**
 
-.. code:: c
+.. code-block:: c
 
     int sem_init(
-    sem_t        \*sem,
+        sem_t        *sem,
-    int           pshared,
+        int           pshared,
-    unsigned int  value
+        unsigned int  value
     );
 
 **STATUS CODES:**
 
-*EINVAL*
+.. list-table::
-    The value argument exceeds SEM_VALUE_MAX
+ :class: rtems-table
 
-*ENOSPC*
+ * - ``EINVAL``
-    A resource required to initialize the semaphore has been exhausted
+   - The value argument exceeds ``SEM_VALUE_MAX``
-    The limit on semaphores (SEM_VALUE_MAX) has been reached
+ * - ``ENOSPC``
-
+   - A resource required to initialize the semaphore has been exhausted The
-*ENOSYS*
+     limit on semaphores (``SEM_VALUE_MAX``) has been reached
-    The function sem_init is not supported by this implementation
+ * - ``ENOSYS``
-
+   - The function sem_init is not supported by this implementation
-*EPERM*
+ * - ``EPERM``
-    The process lacks appropriate privileges to initialize the semaphore
+   - The process lacks appropriate privileges to initialize the semaphore
 
 **DESCRIPTION:**
 
-The sem_init function is used to initialize the unnamed semaphore referred to
+The ``sem_init`` function is used to initialize the unnamed semaphore referred
-by "sem". The value of the initialized semaphore is the parameter "value". The
+to by ``sem``. The value of the initialized semaphore is the parameter
-semaphore remains valid until it is destroyed.
+``value``. The semaphore remains valid until it is destroyed.
 
-ADD MORE HERE XXX
+.. COMMENT: ADD MORE HERE XXX
 
 **NOTES:**
 
 If the functions completes successfully, it shall return a value of zero.
-Otherwise, it shall return a value of -1 and set "errno" to specify the error
+otherwise, it shall return a value of -1 and set ``errno`` to specify the error
 that occurred.
 
 Multiprocessing is currently not supported in this implementation.
 
+.. _sem_destroy:
+
 sem_destroy - Destroy an unnamed semaphore
 ------------------------------------------
 .. index:: sem_destroy
@@ -136,37 +145,40 @@ sem_destroy - Destroy an unnamed semaphore
 
 **CALLING SEQUENCE:**
 
-.. code:: c
+.. code-block:: c
 
     int sem_destroy(
-    sem_t \*sem
+        sem_t *sem
     );
 
 **STATUS CODES:**
 
-*EINVAL*
+.. list-table::
-    The value argument exceeds SEM_VALUE_MAX
+ :class: rtems-table
 
-*ENOSYS*
+ * - ``EINVAL``
-    The function sem_init is not supported by this implementation
+   - The value argument exceeds ``SEM_VALUE_MAX``
-
+ * - ``ENOSYS``
-*EBUSY*
+   - The function ``sem_init`` is not supported by this implementation
-    There are currently processes blocked on the semaphore
+ * - ``EBUSY``
+   - There are currently processes blocked on the semaphore
 
 **DESCRIPTION:**
 
-The sem_destroy function is used to destroy an unnamed semaphore refered to by
+The ``sem_destroy`` function is used to destroy an unnamed semaphore refered to
-"sem". sem_destroy can only be used on a semaphore that was created using
+by ``sem``. ``sem_destroy`` can only be used on a semaphore that was created
-sem_init.
+using sem_init.
 
 **NOTES:**
 
 If the functions completes successfully, it shall return a value of zero.
-Otherwise, it shall return a value of -1 and set "errno" to specify the error
+Otherwise, it shall return a value of -1 and set ``errno`` to specify the error
 that occurred.
 
 Multiprocessing is currently not supported in this implementation.
 
+.. _sem_open:
+
 sem_open - Open a named semaphore
 ---------------------------------
 .. index:: sem_open
@@ -174,66 +186,70 @@ sem_open - Open a named semaphore
 
 **CALLING SEQUENCE:**
 
-.. code:: c
+.. code-block:: c
 
     int sem_open(
-    const char \*name,
+        const char *name,
-    int         oflag
+        int         oflag
     );
 
 **ARGUMENTS:**
 
 The following flag bit may be set in oflag:
 
-``O_CREAT`` - Creates the semaphore if it does not already exist. If O_CREAT
+.. list-table::
-is set and the semaphore already exists then O_CREAT has no effect. Otherwise,
+ :class: rtems-table
-sem_open() creates a semaphore. The O_CREAT flag requires the third and fourth
-argument: mode and value of type mode_t and unsigned int, respectively.
 
-``O_EXCL`` - If O_EXCL and O_CREAT are set, all call to sem_open() shall fail
+ * - ``O_CREAT``
-if the semaphore name exists
+   - Creates the semaphore if it does not already exist. If ``O_CREAT`` is set
+     and the semaphore already exists then ``O_CREAT`` has no
+     effect. Otherwise, ``sem_open()`` creates a semaphore. The ``O_CREAT``
+     flag requires the third and fourth argument: mode and value of type
+     ``mode_t`` and ``unsigned int``, respectively.
+ * - ``O_EXCL``
+   - If ``O_EXCL`` and ``O_CREAT`` are set, all call to ``sem_open()`` shall
+     fail if the semaphore name exists
 
 **STATUS CODES:**
 
-*EACCES*
+.. list-table::
-    Valid name specified but oflag permissions are denied, or the semaphore name
+ :class: rtems-table
-    specified does not exist and permission to create the named semaphore is denied.
 
-*EEXIST*
+ * - ``EACCES``
-    O_CREAT and O_EXCL are set and the named semaphore already exists.
+   - Valid name specified but oflag permissions are denied, or the semaphore
-
+     name specified does not exist and permission to create the named semaphore
-*EINTR*
+     is denied.
-    The sem_open() operation was interrupted by a signal.
+ * - ``EEXIST``
-
+   - ``O_CREAT`` and ``O_EXCL`` are set and the named semaphore already exists.
-*EINVAL*
+ * - ``EINTR``
-    The sem_open() operation is not supported for the given name.
+   - The ``sem_open()`` operation was interrupted by a signal.
-
+ * - ``EINVAL``
-*EMFILE*
+   - The ``sem_open()`` operation is not supported for the given name.
-    Too many semaphore descriptors or file descriptors in use by this process.
+ * - ``EMFILE``
-
+   - Too many semaphore descriptors or file descriptors in use by this process.
-*ENAMETOOLONG*
+ * - ``ENAMETOOLONG``
-    The length of the name exceed PATH_MAX or name component is longer than NAME_MAX
+   - The length of the name exceed ``PATH_MAX`` or name component is longer
-    while POSIX_NO_TRUNC is in effect.
+     than ``NAME_MAX`` while ``POSIX_NO_TRUNC`` is in effect.
-
+ * - ``ENOENT``
-*ENOENT*
+   - ``O_CREAT`` is not set and the named semaphore does not exist.
-    O_CREAT is not set and the named semaphore does not exist.
+ * - ``ENOSPC``
-
+   - There is insufficient space for the creation of a new named semaphore.
-*ENOSPC*
+ * - ``ENOSYS``
-    There is insufficient space for the creation of a new named semaphore.
+   - The function ``sem_open()`` is not supported by this implementation.
-
-*ENOSYS*
-    The function sem_open() is not supported by this implementation.
 
 **DESCRIPTION:**
 
-The sem_open() function establishes a connection between a specified semaphore and
+The ``sem_open()`` function establishes a connection between a specified
-a process. After a call to sem_open with a specified semaphore name, a process
+semaphore and a process. After a call to sem_open with a specified semaphore
-can reference to semaphore by the associated name using the address returned by
+name, a process can reference to semaphore by the associated name using the
-the call. The oflag arguments listed above control the state of the semaphore by
+address returned by the call. The oflag arguments listed above control the
-determining if the semaphore is created or accessed by a call to sem_open().
+state of the semaphore by determining if the semaphore is created or accessed
+by a call to ``sem_open()``.
 
 **NOTES:**
 
+.. _sem_close:
+
 sem_close - Close a named semaphore
 -----------------------------------
 .. index:: sem_close
@@ -241,30 +257,34 @@ sem_close - Close a named semaphore
 
 **CALLING SEQUENCE:**
 
-.. code:: c
+.. code-block:: c
 
     int sem_close(
-    sem_t \*sem_close
+        sem_t *sem_close
     );
 
 **STATUS CODES:**
 
-*EACCES*
+.. list-table::
-    The semaphore argument is not a valid semaphore descriptor.
+ :class: rtems-table
 
-*ENOSYS*
+ * - ``EACCES``
-    The function sem_close is not supported by this implementation.
+   - The semaphore argument is not a valid semaphore descriptor.
+ * - ``ENOSYS``
+   - The function ``sem_close`` is not supported by this implementation.
 
 **DESCRIPTION:**
 
-The sem_close() function is used to indicate that the calling process is finished
+The ``sem_close()`` function is used to indicate that the calling process is
-using the named semaphore indicated by sem. The function sem_close deallocates
+finished using the named semaphore indicated by ``sem``. The function
-any system resources that were previously allocated by a sem_open system call. If
+``sem_close`` deallocates any system resources that were previously allocated
-sem_close() completes successfully it returns a 1, otherwise a value of -1 is
+by a ``sem_open`` system call. If ``sem_close()`` completes successfully it
-return and errno is set.
+returns a 1, otherwise a value of -1 is return and ``errno`` is set.
 
 **NOTES:**
 
+.. _sem_unlink:
+
 sem_unlink - Unlink a semaphore
 -------------------------------
 .. index:: sem_unlink
@@ -272,43 +292,46 @@ sem_unlink - Unlink a semaphore
 
 **CALLING SEQUENCE:**
 
-.. code:: c
+.. code-block:: c
 
     int sem_unlink(
-    const char \*name
+        const char *name
     );
 
 **STATUS CODES:**
 
-*EACCESS*
+.. list-table::
-    Permission is denied to unlink a semaphore.
+ :class: rtems-table
 
-*ENAMETOOLONG*
+ * - ``EACCESS``
-    The length of the strong name exceed NAME_MAX while POSIX_NO_TRUNC is in effect.
+   - Permission is denied to unlink a semaphore.
-
+ * - ``ENAMETOOLONG``
-*ENOENT*
+   - The length of the strong name exceed ``NAME_MAX`` while ``POSIX_NO_TRUNC``
-    The name of the semaphore does not exist.
+     is in effect.
-
+ * - ``ENOENT``
-*ENOSPC*
+   - The name of the semaphore does not exist.
-    There is insufficient space for the creation of a new named semaphore.
+ * - ``ENOSPC``
-
+   - There is insufficient space for the creation of a new named semaphore.
-*ENOSYS*
+ * - ``ENOSYS``
-    The function sem_unlink is not supported by this implementation.
+   - The function ``sem_unlink`` is not supported by this implementation.
 
 **DESCRIPTION:**
 
-The sem_unlink() function shall remove the semaphore name by the string name. If
+The ``sem_unlink()`` function shall remove the semaphore name by the string
-a process is currently accessing the name semaphore, the sem_unlink command has
+name. If a process is currently accessing the name semaphore, the
-no effect. If one or more processes have the semaphore open when the sem_unlink
+``sem_unlink`` command has no effect. If one or more processes have the
-function is called, the destruction of semaphores shall be postponed until all
+semaphore open when the ``sem_unlink`` function is called, the destruction of
-reference to semaphore are destroyed by calls to sem_close, _exit(), or exec.
+semaphores shall be postponed until all reference to semaphore are destroyed by
-After all references have been destroyed, it returns immediately.
+calls to ``sem_close``, ``_exit()``, or ``exec``.  After all references have
+been destroyed, it returns immediately.
 
 If the termination is successful, the function shall return 0. Otherwise, a -1
-is returned and the errno is set.
+is returned and the ``errno`` is set.
 
 **NOTES:**
 
+.. _sem_wait:
+
 sem_wait - Wait on a Semaphore
 ------------------------------
 .. index:: sem_wait
@@ -316,16 +339,19 @@ sem_wait - Wait on a Semaphore
 
 **CALLING SEQUENCE:**
 
-.. code:: c
+.. code-block:: c
 
     int sem_wait(
-    sem_t \*sem
+        sem_t *sem
     );
 
 **STATUS CODES:**
 
-*EINVAL*
+.. list-table::
-    The "sem" argument does not refer to a valid semaphore
+ :class: rtems-table
+
+ * - ``EINVAL``
+   - The ``sem`` argument does not refer to a valid semaphore
 
 **DESCRIPTION:**
 
@@ -336,13 +362,15 @@ value is zero), then the function will block until the semaphore becomes
 available. It will then successfully lock the semaphore. The semaphore
 remains locked until released by a ``sem_post()`` call.
 
-If the call is unsuccessful, then the function returns -1 and sets errno to the
+If the call is unsuccessful, then the function returns -1 and sets ``errno`` to
-appropriate error code.
+the appropriate error code.
 
 **NOTES:**
 
 Multiprocessing is not supported in this implementation.
 
+.. _sem_trywait:
+
 sem_trywait - Non-blocking Wait on a Semaphore
 ----------------------------------------------
 .. index:: sem_trywait
@@ -350,36 +378,41 @@ sem_trywait - Non-blocking Wait on a Semaphore
 
 **CALLING SEQUENCE:**
 
-.. code:: c
+.. code-block:: c
 
     int sem_trywait(
-    sem_t \*sem
+        sem_t *sem
     );
 
 **STATUS CODES:**
 
-*EAGAIN*
+.. list-table::
-    The semaphore is not available (i.e., the semaphore value is zero), so the
+ :class: rtems-table
-    semaphore could not be locked.
 
-*EINVAL*
+ * - ``EAGAIN``
-    The ``sem`` argument does not refewr to a valid semaphore
+   - The semaphore is not available (i.e., the semaphore value is zero), so the
+     semaphore could not be locked.
+ * - ``EINVAL``
+   - The ``sem`` argument does not refewr to a valid semaphore
 
 **DESCRIPTION:**
 
 This function attempts to lock a semaphore specified by ``sem``. If the
-semaphore is available, then the semaphore is locked (i.e., the semaphore
+semaphore is available, then the semaphore is locked (i.e., the semaphore value
-value is decremented) and the function returns a value of 0. The semaphore
+is decremented) and the function returns a value of 0. The semaphore remains
-remains locked until released by a ``sem_post()`` call. If the semaphore
+locked until released by a ``sem_post()`` call. If the semaphore is unavailable
-is unavailable (i.e., the semaphore value is zero), then the function will
+(i.e., the semaphore value is zero), then the function will return a value
-return a value of -1 immediately and set ``errno`` to EAGAIN.
+of -1 immediately and set ``errno`` to ``EAGAIN``.
 
-If the call is unsuccessful, then the function returns -1 and sets``errno`` to the appropriate error code.
+If the call is unsuccessful, then the function returns -1 and sets ``errno`` to
+the appropriate error code.
 
 **NOTES:**
 
 Multiprocessing is not supported in this implementation.
 
+.. _sem_timedwait:
+
 sem_timedwait - Wait on a Semaphore for a Specified Time
 --------------------------------------------------------
 .. index:: sem_timedwait
@@ -387,40 +420,45 @@ sem_timedwait - Wait on a Semaphore for a Specified Time
 
 **CALLING SEQUENCE:**
 
-.. code:: c
+.. code-block:: c
 
     int sem_timedwait(
-    sem_t                 \*sem,
+        sem_t                 *sem,
-    const struct timespec \*abstime
+        const struct timespec *abstime
     );
 
 **STATUS CODES:**
 
-*EAGAIN*
+.. list-table::
-    The semaphore is not available (i.e., the semaphore value is zero), so the
+ :class: rtems-table
-    semaphore could not be locked.
 
-*EINVAL*
+ * - ``EAGAIN``
-    The ``sem`` argument does not refewr to a valid semaphore
+   - The semaphore is not available (i.e., the semaphore value is zero), so the
+     semaphore could not be locked.
+ * - ``EINVAL``
+   - The ``sem`` argument does not refewr to a valid semaphore
 
 **DESCRIPTION:**
 
-This function attemtps to lock a semaphore specified by ``sem``,
+This function attemtps to lock a semaphore specified by ``sem``, and will wait
-and will wait for the semaphore until the absolute time specified by``abstime``. If the semaphore is available, then the semaphore is
+for the semaphore until the absolute time specified by ``abstime``. If the
-locked (i.e., the semaphore value is decremented) and the function
+semaphore is available, then the semaphore is locked (i.e., the semaphore value
-returns a value of 0. The semaphore remains locked until released by
+is decremented) and the function returns a value of 0. The semaphore remains
-a ``sem_post()`` call. If the semaphore is unavailable, then the
+locked until released by a ``sem_post()`` call. If the semaphore is
-function will wait for the semaphore to become available for the amount
+unavailable, then the function will wait for the semaphore to become available
-of time specified by ``timeout``.
+for the amount of time specified by ``timeout``.
 
-If the semaphore does not become available within the interval specified by``timeout``, then the function returns -1 and sets ``errno`` to EAGAIN.
+If the semaphore does not become available within the interval specified by
-If any other error occurs, the function returns -1 and sets ``errno`` to
+``timeout``, then the function returns -1 and sets ``errno`` to ``EAGAIN``.  If
-the appropriate error code.
+any other error occurs, the function returns -1 and sets ``errno`` to the
+appropriate error code.
 
 **NOTES:**
 
 Multiprocessing is not supported in this implementation.
 
+.. _sem_post:
+
 sem_post - Unlock a Semaphore
 -----------------------------
 .. index:: sem_post
@@ -428,25 +466,28 @@ sem_post - Unlock a Semaphore
 
 **CALLING SEQUENCE:**
 
-.. code:: c
+.. code-block:: c
 
     int sem_post(
-    sem_t \*sem
+        sem_t *sem
     );
 
 **STATUS CODES:**
 
-*EINVAL*
+.. list-table::
-    The ``sem`` argument does not refer to a valid semaphore
+ :class: rtems-table
+
+ * - ``EINVAL``
+   - The ``sem`` argument does not refer to a valid semaphore
 
 **DESCRIPTION:**
 
-This function attempts to release the semaphore specified by ``sem``. If
+This function attempts to release the semaphore specified by ``sem``. If other
-other tasks are waiting on the semaphore, then one of those tasks (which one
+tasks are waiting on the semaphore, then one of those tasks (which one depends
-depends on the scheduler being used) is allowed to lock the semaphore and
+on the scheduler being used) is allowed to lock the semaphore and return from
-return from its ``sem_wait()``, ``sem_trywait()``, or``sem_timedwait()`` call. If there are no other tasks waiting on the
+its ``sem_wait()``, ``sem_trywait()``, or ``sem_timedwait()`` call. If there
-semaphore, then the semaphore value is simply incremented. ``sem_post()``
+are no other tasks waiting on the semaphore, then the semaphore value is simply
-returns 0 upon successful completion.
+incremented. ``sem_post()`` returns 0 upon successful completion.
 
 If an error occurs, the function returns -1 and sets ``errno`` to the
 appropriate error code.
@@ -455,6 +496,8 @@ appropriate error code.
 
 Multiprocessing is not supported in this implementation.
 
+.. _sem_getvalue:
+
 sem_getvalue - Get the value of a semaphore
 -------------------------------------------
 .. index:: sem_getvalue
@@ -462,42 +505,37 @@ sem_getvalue - Get the value of a semaphore
 
 **CALLING SEQUENCE:**
 
-.. code:: c
+.. code-block:: c
 
     int sem_getvalue(
-    sem_t \*sem,
+        sem_t *sem,
-    int   \*sval
+        int   *sval
     );
 
 **STATUS CODES:**
 
-*EINVAL*
+.. list-table::
-    The "sem" argument does not refer to a valid semaphore
+ :class: rtems-table
 
-*ENOSYS*
+ * - ``EINVAL``
-    The function sem_getvalue is not supported by this implementation
+   - The ``sem`` argument does not refer to a valid semaphore
+ * - ``ENOSYS``
+   - The function ``sem_getvalue`` is not supported by this implementation
 
 **DESCRIPTION:**
 
-The sem_getvalue functions sets the location referenced by the "sval" argument
+The ``sem_getvalue`` functions sets the location referenced by the ``sval``
-to the value of the semaphore without affecting the state of the semaphore. The
+argument to the value of the semaphore without affecting the state of the
-updated value represents a semaphore value that occurred at some point during
+semaphore. The updated value represents a semaphore value that occurred at some
-the call, but is not necessarily the actual value of the semaphore when it
+point during the call, but is not necessarily the actual value of the semaphore
-returns to the calling process.
+when it returns to the calling process.
 
-If "sem" is locked, the value returned by sem_getvalue will be zero or a
+If ``sem`` is locked, the value returned by ``sem_getvalue`` will be zero or a
 negative number whose absolute value is the number of processes waiting for the
 semaphore at some point during the call.
 
 **NOTES:**
 
 If the functions completes successfully, it shall return a value of zero.
-Otherwise, it shall return a value of -1 and set "errno" to specify the error
+Otherwise, it shall return a value of -1 and set ``errno`` to specify the error
 that occurred.
-
-.. COMMENT: COPYRIGHT (c) 1989-2008.
-
-.. COMMENT: On-Line Applications Research Corporation (OAR).
-
-.. COMMENT: All rights reserved.
-

posix_users/services_provided_by_c.rst

@@ -1,3 +1,7 @@
+.. COMMENT: COPYRIGHT (c) 1988-2002.
+.. COMMENT: On-Line Applications Research Corporation (OAR).
+.. COMMENT: All rights reserved.
+
 Services Provided by C Library (libc)
 #####################################
 
@@ -292,15 +296,18 @@ Reentrant Versions of Functions
   - ``errno_r`` - XXX
 
 - Locale functions:
+
   - ``localeconv_r`` - XXX
   - ``setlocale_r`` - XXX
 
 - Equivalents for stdio variables:
+
   - ``stdin_r`` - XXX
   - ``stdout_r`` - XXX
   - ``stderr_r`` - XXX
 
 - Stdio functions:
+
   - ``fdopen_r`` - XXX
   - ``perror_r`` - XXX
   - ``tempnam_r`` - XXX
@@ -323,6 +330,7 @@ Reentrant Versions of Functions
   - ``sprintf_r`` - XXX
 
 - Signal functions:
+
   - ``init_signal_r`` - XXX
   - ``signal_r`` - XXX
   - ``kill_r`` - XXX
@@ -330,6 +338,7 @@ Reentrant Versions of Functions
   - ``raise_r`` - XXX
 
 - Stdlib functions:
+
   - ``calloc_r`` - XXX
   - ``mblen_r`` - XXX
   - ``srand_r`` - XXX
@@ -355,9 +364,11 @@ Reentrant Versions of Functions
   - ``setenv_r`` - XXX
 
 - String functions:
+
   - ``strtok_r`` - XXX
 
 - System functions:
+
   - ``close_r`` - XXX
   - ``link_r`` - XXX
   - ``unlink_r`` - XXX
@@ -377,6 +388,7 @@ Reentrant Versions of Functions
   - ``times_r`` - XXX
 
 - Time function:
+
   - ``asctime_r`` - XXX
 
 Miscellaneous Macros and Functions
@@ -388,11 +400,13 @@ Variable Argument Lists
 =======================
 
 - Stdarg (stdarg.h):
+
   - ``va_start`` - XXX
   - ``va_arg`` - XXX
   - ``va_end`` - XXX
 
 - Vararg (varargs.h):
+
   - ``va_alist`` - XXX
   - ``va_start-trad`` - XXX
   - ``va_arg-trad`` - XXX
@@ -424,10 +438,3 @@ Reentrant System Calls
 - ``unlink_r`` - XXX
 
 - ``sbrk_r`` - XXX
-
-.. COMMENT: COPYRIGHT (c) 1988-2002.
-
-.. COMMENT: On-Line Applications Research Corporation (OAR).
-
-.. COMMENT: All rights reserved.
-

posix_users/status_of_implementation.rst

@@ -14,6 +14,7 @@ are provided and do work in a coherent manner.  This is significant
 when porting existing code from UNIX to RTEMS.
 
 - Implementation
+
   - The current implementation of ``dup()`` is insufficient.
   - FIFOs ``mkfifo()`` are not currently implemented.
   - Asynchronous IO is not implemented.
@@ -21,16 +22,17 @@ when porting existing code from UNIX to RTEMS.
   - getc/putc unlocked family is not implemented
   - Shared Memory is not implemented
   - Mapped Memory is not implemented
-
   - NOTES:
 
     - For Shared Memory and Mapped Memory services, it is unclear what
       level of support is appropriate and possible for RTEMS.
 
 - Functional Testing
+
   - Tests for unimplemented services
 
 - Performance Testing
+
   - There are no POSIX Performance Tests.
 
 - Documentation
@@ -40,4 +42,3 @@ when porting existing code from UNIX to RTEMS.
     background and operations sections.
 
   - Example programs (not just tests) would be very nice.
-

posix_users/system_database.rst

@@ -1,29 +1,32 @@
+.. COMMENT: COPYRIGHT(c) 1988-2002.
+.. COMMENT: On-Line Applications Research Corporation(OAR).
+.. COMMENT: All rights reserved.
+
 System Databases Manager
 ########################
 
 Introduction
 ============
 
-The
+The system databases manager is ...
-system databases manager is ...
 
 The directives provided by the system databases manager are:
 
-- ``getgrgid`` - Get Group File Entry for ID
+- getgrgid_ - Get Group File Entry for ID
 
-- ``getgrgid_r`` - Reentrant Get Group File Entry
+- getgrgid_r_ - Reentrant Get Group File Entry
 
-- ``getgrnam`` - Get Group File Entry for Name
+- getgrnam_ - Get Group File Entry for Name
 
-- ``getgrnam_r`` - Reentrant Get Group File Entry for Name
+- getgrnam_r_ - Reentrant Get Group File Entry for Name
 
-- ``getpwuid`` - Get Password File Entry for UID
+- getpwuid_ - Get Password File Entry for UID
 
-- ``getpwuid_r`` - Reentrant Get Password File Entry for UID
+- getpwuid_r_ - Reentrant Get Password File Entry for UID
 
-- ``getpwnam`` - Get Password File Entry for Name
+- getpwnam_ - Get Password File Entry for Name
 
-- ``getpwnam_r`` - Reentrant Get Password File Entry for Name
+- getpwnam_r_ - Reentrant Get Password File Entry for Name
 
 Background
 ==========
@@ -38,10 +41,11 @@ There is currently no text in this section.
 Directives
 ==========
 
-This section details the system databases manager's directives.
+This section details the system databases manager's directives.  A subsection
-A subsection is dedicated to each of this manager's directives
+is dedicated to each of this manager's directives and describes the calling
-and describes the calling sequence, related constants, usage,
+sequence, related constants, usage, and status codes.
-and status codes.
+
+.. _getgrgid:
 
 getgrgid - Get Group File Entry for ID
 --------------------------------------
@@ -50,20 +54,25 @@ getgrgid - Get Group File Entry for ID
 
 **CALLING SEQUENCE:**
 
-.. code:: c
+.. code-block:: c
 
     int getgrgid(
     );
 
 **STATUS CODES:**
 
-*E*
+.. list-table::
-    The
+ :class: rtems-table
+
+ * - ``E``
+   - The
 
 **DESCRIPTION:**
 
 **NOTES:**
 
+.. _getgrgid_r:
+
 getgrgid_r - Reentrant Get Group File Entry
 -------------------------------------------
 .. index:: getgrgid_r
@@ -71,20 +80,25 @@ getgrgid_r - Reentrant Get Group File Entry
 
 **CALLING SEQUENCE:**
 
-.. code:: c
+.. code-block:: c
 
     int getgrgid_r(
     );
 
 **STATUS CODES:**
 
-*E*
+.. list-table::
-    The
+ :class: rtems-table
+
+ * - ``E``
+   - The
 
 **DESCRIPTION:**
 
 **NOTES:**
 
+.. _getgrnam:
+
 getgrnam - Get Group File Entry for Name
 ----------------------------------------
 .. index:: getgrnam
@@ -92,20 +106,25 @@ getgrnam - Get Group File Entry for Name
 
 **CALLING SEQUENCE:**
 
-.. code:: c
+.. code-block:: c
 
     int getgrnam(
     );
 
 **STATUS CODES:**
 
-*E*
+.. list-table::
-    The
+ :class: rtems-table
+
+ * - ``E``
+   - The
 
 **DESCRIPTION:**
 
 **NOTES:**
 
+.. _getgrnam_r:
+
 getgrnam_r - Reentrant Get Group File Entry for Name
 ----------------------------------------------------
 .. index:: getgrnam_r
@@ -113,20 +132,25 @@ getgrnam_r - Reentrant Get Group File Entry for Name
 
 **CALLING SEQUENCE:**
 
-.. code:: c
+.. code-block:: c
 
     int getgrnam_r(
     );
 
 **STATUS CODES:**
 
-*E*
+.. list-table::
-    The
+ :class: rtems-table
+
+ * - ``E``
+   - The
 
 **DESCRIPTION:**
 
 **NOTES:**
 
+.. _getpwuid:
+
 getpwuid - Get Password File Entry for UID
 ------------------------------------------
 .. index:: getpwuid
@@ -134,20 +158,25 @@ getpwuid - Get Password File Entry for UID
 
 **CALLING SEQUENCE:**
 
-.. code:: c
+.. code-block:: c
 
     int getpwuid(
     );
 
 **STATUS CODES:**
 
-*E*
+.. list-table::
-    The
+ :class: rtems-table
+
+ * - ``E``
+   - The
 
 **DESCRIPTION:**
 
 **NOTES:**
 
+.. _getpwuid_r:
+
 getpwuid_r - Reentrant Get Password File Entry for UID
 ------------------------------------------------------
 .. index:: getpwuid_r
@@ -155,20 +184,25 @@ getpwuid_r - Reentrant Get Password File Entry for UID
 
 **CALLING SEQUENCE:**
 
-.. code:: c
+.. code-block:: c
 
     int getpwuid_r(
     );
 
 **STATUS CODES:**
 
-*E*
+.. list-table::
-    The
+ :class: rtems-table
+
+ * - ``E``
+   - The
 
 **DESCRIPTION:**
 
 **NOTES:**
 
+.. _getpwnam:
+
 getpwnam - Password File Entry for Name
 ---------------------------------------
 .. index:: getpwnam
@@ -176,20 +210,25 @@ getpwnam - Password File Entry for Name
 
 **CALLING SEQUENCE:**
 
-.. code:: c
+.. code-block:: c
 
     int getpwnam(
     );
 
 **STATUS CODES:**
 
-*E*
+.. list-table::
-    The
+ :class: rtems-table
+
+ * - ``E``
+   - The
 
 **DESCRIPTION:**
 
 **NOTES:**
 
+.. _getpwnam_r:
+
 getpwnam_r - Reentrant Get Password File Entry for Name
 -------------------------------------------------------
 .. index:: getpwnam_r
@@ -197,23 +236,19 @@ getpwnam_r - Reentrant Get Password File Entry for Name
 
 **CALLING SEQUENCE:**
 
-.. code:: c
+.. code-block:: c
 
     int getpwnam_r(
     );
 
 **STATUS CODES:**
 
-*E*
+.. list-table::
-    The
+ :class: rtems-table
+
+ * - ``E``
+   - The
 
 **DESCRIPTION:**
 
 **NOTES:**
-
-.. COMMENT: COPYRIGHT(c) 1988-2002.
-
-.. COMMENT: On-Line Applications Research Corporation(OAR).
-
-.. COMMENT: All rights reserved.
-

posix_users/thread_cancellation.rst

@@ -1,3 +1,7 @@
+.. COMMENT: COPYRIGHT (c) 1988-2002.
+.. COMMENT: On-Line Applications Research Corporation (OAR).
+.. COMMENT: All rights reserved.
+
 Thread Cancellation Manager
 ###########################
 
@@ -9,17 +13,17 @@ thread cancellation manager is ...
 
 The directives provided by the thread cancellation manager are:
 
-- ``pthread_cancel`` - Cancel Execution of a Thread
+- pthread_cancel_ - Cancel Execution of a Thread
 
-- ``pthread_setcancelstate`` - Set Cancelability State
+- pthread_setcancelstate_ - Set Cancelability State
 
-- ``pthread_setcanceltype`` - Set Cancelability Type
+- pthread_setcanceltype_ - Set Cancelability Type
 
-- ``pthread_testcancel`` - Create Cancellation Point
+- pthread_testcancel_ - Create Cancellation Point
 
-- ``pthread_cleanup_push`` - Establish Cancellation Handler
+- pthread_cleanup_push_ - Establish Cancellation Handler
 
-- ``pthread_cleanup_pop`` - Remove Cancellation Handler
+- pthread_cleanup_pop_ - Remove Cancellation Handler
 
 Background
 ==========
@@ -34,10 +38,11 @@ There is currently no text in this section.
 Directives
 ==========
 
-This section details the thread cancellation manager's directives.
+This section details the thread cancellation manager's directives.  A
-A subsection is dedicated to each of this manager's directives
+subsection is dedicated to each of this manager's directives and describes the
-and describes the calling sequence, related constants, usage,
+calling sequence, related constants, usage, and status codes.
-and status codes.
+
+.. _pthread_cancel:
 
 pthread_cancel - Cancel Execution of a Thread
 ---------------------------------------------
@@ -46,20 +51,25 @@ pthread_cancel - Cancel Execution of a Thread
 
 **CALLING SEQUENCE:**
 
-.. code:: c
+.. code-block:: c
 
     int pthread_cancel(
     );
 
 **STATUS CODES:**
 
-*E*
+.. list-table::
-    The
+ :class: rtems-table
+
+ * - ``E``
+   - The
 
 **DESCRIPTION:**
 
 **NOTES:**
 
+.. _pthread_setcancelstate:
+
 pthread_setcancelstate - Set Cancelability State
 ------------------------------------------------
 .. index:: pthread_setcancelstate
@@ -67,20 +77,25 @@ pthread_setcancelstate - Set Cancelability State
 
 **CALLING SEQUENCE:**
 
-.. code:: c
+.. code-block:: c
 
     int pthread_setcancelstate(
     );
 
 **STATUS CODES:**
 
-*E*
+.. list-table::
-    The
+ :class: rtems-table
+
+ * - ``E``
+   - The
 
 **DESCRIPTION:**
 
 **NOTES:**
 
+.. _pthread_setcanceltype:
+
 pthread_setcanceltype - Set Cancelability Type
 ----------------------------------------------
 .. index:: pthread_setcanceltype
@@ -88,20 +103,25 @@ pthread_setcanceltype - Set Cancelability Type
 
 **CALLING SEQUENCE:**
 
-.. code:: c
+.. code-block:: c
 
     int pthread_setcanceltype(
     );
 
 **STATUS CODES:**
 
-*E*
+.. list-table::
-    The
+ :class: rtems-table
+
+ * - ``E``
+   - The
 
 **DESCRIPTION:**
 
 **NOTES:**
 
+.. _pthread_testcancel:
+
 pthread_testcancel - Create Cancellation Point
 ----------------------------------------------
 .. index:: pthread_testcancel
@@ -109,20 +129,25 @@ pthread_testcancel - Create Cancellation Point
 
 **CALLING SEQUENCE:**
 
-.. code:: c
+.. code-block:: c
 
     int pthread_testcancel(
     );
 
 **STATUS CODES:**
 
-*E*
+.. list-table::
-    The
+ :class: rtems-table
+
+ * - ``E``
+   - The
 
 **DESCRIPTION:**
 
 **NOTES:**
 
+.. _pthread_cleanup_push:
+
 pthread_cleanup_push - Establish Cancellation Handler
 -----------------------------------------------------
 .. index:: pthread_cleanup_push
@@ -130,20 +155,25 @@ pthread_cleanup_push - Establish Cancellation Handler
 
 **CALLING SEQUENCE:**
 
-.. code:: c
+.. code-block:: c
 
     int pthread_cleanup_push(
     );
 
 **STATUS CODES:**
 
-*E*
+.. list-table::
-    The
+ :class: rtems-table
+
+ * - ``E``
+   - The
 
 **DESCRIPTION:**
 
 **NOTES:**
 
+.. _pthread_cleanup_pop:
+
 pthread_cleanup_pop - Remove Cancellation Handler
 -------------------------------------------------
 .. index:: pthread_cleanup_pop
@@ -151,23 +181,19 @@ pthread_cleanup_pop - Remove Cancellation Handler
 
 **CALLING SEQUENCE:**
 
-.. code:: c
+.. code-block:: c
 
     int pthread_cleanup_push(
     );
 
 **STATUS CODES:**
 
-*E*
+.. list-table::
-    The
+ :class: rtems-table
+
+ * - ``E``
+   - The
 
 **DESCRIPTION:**
 
 **NOTES:**
-
-.. COMMENT: COPYRIGHT (c) 1988-2002.
-
-.. COMMENT: On-Line Applications Research Corporation (OAR).
-
-.. COMMENT: All rights reserved.
-

posix_users/timer.rst

@@ -1,3 +1,7 @@
+.. COMMENT: COPYRIGHT(c) 1988-2002.
+.. COMMENT: On-Line Applications Research Corporation(OAR).
+.. COMMENT: All rights reserved.
+
 Timer Manager
 #############
 
@@ -8,15 +12,15 @@ The timer manager is ...
 
 The services provided by the timer manager are:
 
-- ``timer_create`` - Create a Per-Process Timer
+- timer_create_ - Create a Per-Process Timer
 
-- ``timer_delete`` - Delete a Per-Process Timer
+- timer_delete_ - Delete a Per-Process Timer
 
-- ``timer_settime`` - Set Next Timer Expiration
+- timer_settime_ - Set Next Timer Expiration
 
-- ``timer_gettime`` - Get Time Remaining on Timer
+- timer_gettime_ - Get Time Remaining on Timer
 
-- ``timer_getoverrun`` - Get Timer Overrun Count
+- timer_getoverrun_ - Get Timer Overrun Count
 
 Background
 ==========
@@ -27,26 +31,27 @@ Operations
 System Calls
 ============
 
-This section details the timer manager's services.
+This section details the timer manager's services.  A subsection is dedicated
-A subsection is dedicated to each of this manager's services
+to each of this manager's services and describes the calling sequence, related
-and describes the calling sequence, related constants, usage,
+constants, usage, and status codes.
-and status codes.
 
 .. COMMENT: timer_create
 
+.. _timer_create:
+
 timer_create - Create a Per-Process Timer
 -----------------------------------------
 
 **CALLING SEQUENCE:**
 
-.. code:: c
+.. code-block:: c
 
     #include <time.h>
     #include <signal.h>
     int timer_create(
-    clockid_t        clock_id,
+        clockid_t        clock_id,
-    struct sigevent \*evp,
+        struct sigevent *evp,
-    timer_t         \*timerid
+        timer_t         *timerid
     );
 
 **STATUS CODES:**
@@ -59,16 +64,18 @@ timer_create - Create a Per-Process Timer
 
 .. COMMENT: timer_delete
 
+.. _timer_delete:
+
 timer_delete - Delete a Per-Process Timer
 -----------------------------------------
 
 **CALLING SEQUENCE:**
 
-.. code:: c
+.. code-block:: c
 
     #include <time.h>
     int timer_delete(
-    timer_t timerid
+        timer_t timerid
     );
 
 **STATUS CODES:**
@@ -81,19 +88,21 @@ timer_delete - Delete a Per-Process Timer
 
 .. COMMENT: timer_settime
 
+.. _timer_settime:
+
 timer_settime - Set Next Timer Expiration
 -----------------------------------------
 
 **CALLING SEQUENCE:**
 
-.. code:: c
+.. code-block:: c
 
     #include <time.h>
     int timer_settime(
-    timer_t                  timerid,
+        timer_t                  timerid,
-    int                      flags,
+        int                      flags,
-    const struct itimerspec \*value,
+        const struct itimerspec *value,
-    struct itimerspec       \*ovalue
+        struct itimerspec       *ovalue
     );
 
 **STATUS CODES:**
@@ -106,17 +115,19 @@ timer_settime - Set Next Timer Expiration
 
 .. COMMENT: timer_gettime
 
+.. _timer_gettime:
+
 timer_gettime - Get Time Remaining on Timer
 -------------------------------------------
 
 **CALLING SEQUENCE:**
 
-.. code:: c
+.. code-block:: c
 
     #include <time.h>
     int timer_gettime(
-    timer_t            timerid,
+        timer_t            timerid,
-    struct itimerspec \*value
+        struct itimerspec *value
     );
 
 **STATUS CODES:**
@@ -129,16 +140,18 @@ timer_gettime - Get Time Remaining on Timer
 
 .. COMMENT: timer_getoverrun
 
+.. _timer_getoverrun:
+
 timer_getoverrun - Get Timer Overrun Count
 ------------------------------------------
 
 **CALLING SEQUENCE:**
 
-.. code:: c
+.. code-block:: c
 
     #include <time.h>
     int timer_getoverrun(
-    timer_t   timerid
+        timer_t   timerid
     );
 
 **STATUS CODES:**
@@ -148,10 +161,3 @@ timer_getoverrun - Get Timer Overrun Count
 **DESCRIPTION:**
 
 **NOTES:**
-
-.. COMMENT: COPYRIGHT(c) 1988-2002.
-
-.. COMMENT: On-Line Applications Research Corporation(OAR).
-
-.. COMMENT: All rights reserved.
-