summaryrefslogtreecommitdiffstats
path: root/posix_users
diff options
context:
space:
mode:
authorChris Johns <chrisj@rtems.org>2016-02-26 18:22:07 +1100
committerAmar Takhar <verm@darkbeer.org>2016-05-02 20:51:26 -0400
commitfa70fd20878e402610c263f129266593d31a0376 (patch)
treec609d33c7047b975cfe8e0ac0df020fb26dae255 /posix_users
parent238bf991f236b10fb544b4efad80bed0fb6aa394 (diff)
downloadrtems-docs-fa70fd20878e402610c263f129266593d31a0376.tar.bz2
POSIX User clean up.
Diffstat (limited to 'posix_users')
-rw-r--r--posix_users/clock.rst216
-rw-r--r--posix_users/condition_variable.rst215
-rw-r--r--posix_users/device_and_class_specific.rst283
-rw-r--r--posix_users/files_and_directory.rst2062
-rw-r--r--posix_users/index.rst65
-rw-r--r--posix_users/input_and_output.rst840
-rw-r--r--posix_users/key.rst187
-rw-r--r--posix_users/language_specific_services.rst295
-rw-r--r--posix_users/memory_managment.rst148
-rw-r--r--posix_users/message_passing.rst808
-rw-r--r--posix_users/mutex.rst517
-rw-r--r--posix_users/preface.rst85
-rw-r--r--posix_users/process_creation_and_execution.rst235
-rw-r--r--posix_users/process_environment.rst468
-rw-r--r--posix_users/scheduler.rst111
-rw-r--r--posix_users/semaphore.rst426
-rw-r--r--posix_users/services_provided_by_c.rst21
-rw-r--r--posix_users/signal.rst797
-rw-r--r--posix_users/status_of_implementation.rst5
-rw-r--r--posix_users/system_database.rst125
-rw-r--r--posix_users/thread.rst1208
-rw-r--r--posix_users/thread_cancellation.rst96
-rw-r--r--posix_users/timer.rst70
23 files changed, 5051 insertions, 4232 deletions
diff --git a/posix_users/clock.rst b/posix_users/clock.rst
index fe6aec3..85cccd5 100644
--- a/posix_users/clock.rst
+++ b/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
-of services. The first focuses on obtaining and setting
-the current date and time. The other category of services
-focus on allowing a thread to delay for a specific length
-of time.
+The clock manager provides services two primary classes of services. The first
+focuses on obtaining and setting the current date and time. The other category
+of services 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.
-A subsection is dedicated to each of this manager's directives
-and describes the calling sequence, related constants, usage,
-and status codes.
+This section details the clock manager's directives. A subsection is dedicated
+to each of this manager's directives and describes the calling sequence,
+related constants, usage, and status codes.
+
+.. _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,
- struct timespec \*tp
+ clockid_t clock_id,
+ 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*
- The tp pointer parameter is invalid.
+.. list-table::
+ :class: rtems-table
-*EINVAL*
- The clock_id specified is invalid.
+ * - ``EINVAL``
+ - 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,
- const struct timespec \*tp
+ clockid_t clock_id,
+ 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*
- The tp pointer parameter is invalid.
+.. list-table::
+ :class: rtems-table
-*EINVAL*
- The clock_id specified is invalid.
-
-*EINVAL*
- The contents of the tp structure are invalid.
+ * - ``EINVAL``
+ - The tp pointer parameter is invalid.
+ * - ``EINVAL``
+ - The clock_id specified is 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,
- struct timespec \*res
+ clockid_t clock_id,
+ 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*
- The res pointer parameter is invalid.
+.. list-table::
+ :class: rtems-table
-*EINVAL*
- The clock_id specified is invalid.
+ * - ``EINVAL``
+ - 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
-number of ``seconds``.
+The ``sleep()`` function delays the calling thread by the specified number of
+``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
-number of ``seconds``.
+The ``sleep()`` function delays the calling thread by the specified number of
+``seconds``.
-The ``usleep()`` function suspends the calling thread from execution
-until either the number of microseconds specified by the``useconds`` argument has elapsed or a signal is delivered to the
-calling thread and its action is to invoke a signal-catching function
-or to terminate the process.
+The ``usleep()`` function suspends the calling thread from execution until
+either the number of microseconds specified by the ``useconds`` argument has
+elapsed or a signal is delivered to the calling thread and its action is to
+invoke a signal-catching function or to terminate the process.
-Because of other activity, or because of the time spent in
-processing the call, the actual length of time the thread is
-blocked may be longer than
-the amount of time specified.
+Because of other activity, or because of the time spent in processing the call,
+the actual length of time the thread is blocked may be longer than 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 same timer as that used by the ``alarm()`` service. This is*NOT* the case for *RTEMS* and this call has no interaction with
-the ``SIGALRM`` signal.
+The Single UNIX Specification allows this service to be implemented using the
+same timer as that used by the ``alarm()`` service. This is *NOT* the case for
+*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,
- struct timespec \*rmtp
+ const struct timespec *rqtp,
+ 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*
- The routine was interrupted by a signal.
+.. list-table::
+ :class: rtems-table
-*EAGAIN*
- The requested sleep period specified negative seconds or nanoseconds.
-
-*EINVAL*
- The requested sleep period specified an invalid number for the nanoseconds
- field.
+ * - ``EINTR``
+ - The routine was interrupted by a signal.
+ * - ``EAGAIN``
+ - The requested sleep period specified negative seconds or nanoseconds.
+ * - ``EINVAL``
+ - 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 timezone \*tzp
+ struct timeval *tp,
+ struct timezone *tzp
);
**STATUS CODES:**
On error, this routine returns -1 and sets ``errno`` as appropriate.
-*EPERM*
- ``settimeofdat`` is called by someone other than the superuser.
-
-*EINVAL*
- Timezone (or something else) is invalid.
+.. list-table::
+ :class: rtems-table
-*EFAULT*
- One of ``tv`` or ``tz`` pointed outside your accessible address
- space
+ * - ``EPERM``
+ - ``settimeofdat`` is called by someone other than the superuser.
+ * - ``EINVAL``
+ - Timezone (or something else) is invalid.
+ * - ``EFAULT``
+ - 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``
-argument is ignored.
+Currently, the timezone information is not supported. The ``tzp`` argument is
+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,
-measured in seconds
+``time`` returns the time since 00:00:00 GMT, January 1, 1970, measured in
+seconds
-If ``tloc`` in non null, the return value is also stored in the
-memory pointed to by ``t``.
+If ``tloc`` in non null, the return value is also stored in the memory pointed
+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.
-
diff --git a/posix_users/condition_variable.rst b/posix_users/condition_variable.rst
index d940e33..2584d77 100644
--- a/posix_users/condition_variable.rst
+++ b/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.
-A subsection is dedicated to each of this manager's directives
-and describes the calling sequence, related constants, usage,
-and status codes.
+This section details the condition variable manager's directives. A subsection
+is dedicated to each of this manager's directives and describes the calling
+sequence, related constants, usage, and status codes.
+
+.. _pthread_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*
- Insufficient memory is available to initialize the condition variable
- attributes object.
+ * - ``ENOMEM``
+ - Insufficient memory is available to initialize the condition variable
+ 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*
- The attribute object specified is invalid.
+.. list-table::
+ :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,
- int pshared
+ pthread_condattr_t *attr,
+ int pshared
);
**STATUS CODES:**
-*EINVAL*
- Invalid argument passed.
+.. list-table::
+ :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,
- int \*pshared
+ const pthread_condattr_t *attr,
+ int *pshared
);
**STATUS CODES:**
-*EINVAL*
- Invalid argument passed.
+.. list-table::
+ :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,
- const pthread_condattr_t \*attr
+ pthread_cond_t *cond,
+ const pthread_condattr_t *attr
);
**STATUS CODES:**
-*EAGAIN*
- The system lacked a resource other than memory necessary to create the
- initialize the condition variable object.
+.. list-table::
+ :class: rtems-table
-*ENOMEM*
- Insufficient memory is available to initialize the condition variable object.
-
-*EBUSY*
- The specified condition variable has already been initialized.
-
-*EINVAL*
- The specified attribute value is invalid.
+ * - ``EAGAIN``
+ - The system lacked a resource other than memory necessary to create the
+ initialize the condition variable object.
+ * - ``ENOMEM``
+ - Insufficient memory is available to initialize the condition variable
+ object.
+ * - ``EBUSY``
+ - 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*
- The specified condition variable is invalid.
+.. list-table::
+ :class: rtems-table
-*EBUSY*
- The specified condition variable is currently in use.
+ * - ``EINVAL``
+ - 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*
- The specified condition variable is not valid.
+.. list-table::
+ :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*
- The specified condition variable is not valid.
+.. list-table::
+ :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_mutex_t \*mutex
+ pthread_cond_t *cond,
+ pthread_mutex_t *mutex
);
**STATUS CODES:**
-*EINVAL*
- 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.
+.. list-table::
+ :class: rtems-table
+
+ * - ``EINVAL``
+ - 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_mutex_t \*mutex,
- const struct timespec \*abstime
+ pthread_cond_t *cond,
+ pthread_mutex_t *mutex,
+ const struct timespec *abstime
);
**STATUS CODES:**
-*EINVAL*
- 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.
+.. list-table::
+ :class: rtems-table
-*ETIMEDOUT*
- The specified time has elapsed without the condition variable being
- satisfied.
+ * - ``EINVAL``
+ - 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.
+ * - ``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.
-
diff --git a/posix_users/device_and_class_specific.rst b/posix_users/device_and_class_specific.rst
index 0c344d2..e74b692 100644
--- a/posix_users/device_and_class_specific.rst
+++ b/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
-manager are:
+The directives provided by the device- and class- specific functions manager
+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
-stored in a struct termios. The codes are defined in ``<termios.h>``
-by the macros BO, B50, B75, B110, B134, B150, B200, B300, B600, B1200,
-B1800, B2400, B4800, B9600, B19200, and B38400.
+The ``cfsetispeed()`` function stores a code for the terminal speed stored in a
+struct termios. The codes are defined in ``<termios.h>`` by the macros ``BO``,
+``B50``, ``B75``, ``B110``, ``B134``, ``B150``, ``B200``, ``B300``, ``B600``,
+``B1200``, ``B1800``, ``B2400``, ``B4800``, ``B9600``, ``B19200``, and
+``B38400``.
-The ``cfsetispeed()`` function does not do anything to the hardware.
-It merely stores a value for use by ``tcsetattr()``.
+The ``cfsetispeed()`` function does not do anything to the hardware. It merely
+stores a value for use by ``tcsetattr()``.
**NOTES:**
-Baud rates are defined by symbols, such as B110, B1200, B2400. The actual
-number returned for any given speed may change from system to system.
+Baud rates are defined by symbols, such as ``B110``, ``B1200``, ``B2400``. The
+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(
- const struct termios \*p
+ int cfgetospeed(
+ 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
-stored in a ``struct termios``. The codes are defined in ``<termios.h>``
-by the macros BO, B50, B75, B110, B134, B150, B200, B300, B600, B1200, B1800,
-B2400, B4800, B9600, B19200, and B38400.
+The ``cfgetospeed()`` function returns a code for the terminal speed stored in
+a ``struct termios``. The codes are defined in ``<termios.h>`` by the macros
+``BO``, ``B50``, ``B75``, ``B110``, ``B134``, ``B150``, ``B200``, ``B300``,
+``B600``, ``B1200``, ``B1800``, ``B2400``, ``B4800``, ``B9600``, ``B19200``,
+and ``B38400``.
-The ``cfgetospeed()`` function does not do anything to the hardware.
-It merely returns the value stored by a previous call to ``tcgetattr()``.
+The ``cfgetospeed()`` function does not do anything to the hardware. It merely
+returns the value stored by a previous call to ``tcgetattr()``.
**NOTES:**
-Baud rates are defined by symbols, such as B110, B1200, B2400. The actual
-number returned for any given speed may change from system to system.
+Baud rates are defined by symbols, such as ``B110``, ``B1200``, ``B2400``. The
+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,
- speed_t speed
+ struct termios *p,
+ speed_t speed
);
**STATUS CODES:**
-The ``cfsetispeed()`` function returns a zero when successful and
-returns -1 when an error occurs.
+The ``cfsetispeed()`` function returns a zero when successful and returns -1
+when an error occurs.
**DESCRIPTION:**
-The ``cfsetispeed()`` function stores a code for the terminal speed
-stored in a struct termios. The codes are defined in ``<termios.h>``
-by the macros B0, B50, B75, B110, B134, B150, B200, B300, B600, B1200,
-B1800, B2400, B4800, B9600, B19200, and B38400.
+The ``cfsetispeed()`` function stores a code for the terminal speed stored in a
+struct termios. The codes are defined in ``<termios.h>`` by the macros ``BO``,
+``B50``, ``B75``, ``B110``, ``B134``, ``B150``, ``B200``, ``B300``, ``B600``,
+``B1200``, ``B1800``, ``B2400``, ``B4800``, ``B9600``, ``B19200``, and
+``B38400``.
**NOTES:**
-This function merely stores a value in the ``termios`` structure. It
-does not change the terminal speed until a ``tcsetattr()`` is done.
-It does not detect impossible terminal speeds.
+This function merely stores a value in the ``termios`` structure. It does not
+change the terminal speed until a ``tcsetattr()`` is done. It does not detect
+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,
- speed_t speed
+ struct termios *p,
+ 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
-in a struct ``termios``. The codes are defiined in ``<termios.h>`` by the
-macros B0, B50, B75, B110, B134, B150, B200, B300, B600, B1200, B1800, B2400,
-B4800, B9600, B19200, and B38400.
+The ``cfsetospeed()`` function stores a code for the terminal speed stored in a
+struct ``termios``. The codes are defiined in ``<termios.h>`` by the macros
+``BO``, ``B50``, ``B75``, ``B110``, ``B134``, ``B150``, ``B200``, ``B300``,
+``B600``, ``B1200``, ``B1800``, ``B2400``, ``B4800``, ``B9600``, ``B19200``,
+and ``B38400``.
-The ``cfsetospeed()`` function does not do anything to the hardware. It
-merely stores a value for use by ``tcsetattr()``.
+The ``cfsetospeed()`` function does not do anything to the hardware. It merely
+stores a value for use by ``tcsetattr()``.
**NOTES:**
-This function merely stores a value in the ``termios`` structure.
-It does not change the terminal speed until a ``tcsetattr()`` is done.
-It does not detect impossible terminal speeds.
+This function merely stores a value in the ``termios`` structure. It does not
+change the terminal speed until a ``tcsetattr()`` is done. It does not detect
+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,
- struct termios \*p
+ int fildes,
+ struct termios *p
);
**STATUS CODES:**
-*EBADF*
- Invalid file descriptor
+.. list-table::
+ :class: rtems-table
-*ENOOTY*
- Terminal control function attempted for a file that is not a terminal.
+ * - ``EBADF``
+ - 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
-referred to by ``fildes`` and stores them into the ``termios()``
-structure pointed to by ``termios_p``.
+The ``tcgetattr()`` gets the parameters associated with the terminal referred
+to by ``fildes`` and stores them into the ``termios()`` structure pointed to by
+``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 options,
- const struct termios \*tp
+ int fildes,
+ int options,
+ const struct termios *tp
);
**STATUS CODES:**
-*E*
- The
+.. list-table::
+ :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*
- The
+.. list-table::
+ :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*
- Invalid file descriptor
+.. list-table::
+ :class: rtems-table
-*EINTR*
- Function was interrupted by a signal
-
-*ENOTTY*
- Terminal control function attempted for a file that is not a terminal.
+ * - ``EBADF``
+ - Invalid file descriptor
+ * - ``EINTR``
+ - Function was interrupted by a signal
+ * - ``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*
- The
+.. list-table::
+ :class: rtems-table
+
+ * - ``E``
+ - The
**DESCRIPTION:**
**NOTES:**
-This routine is not currently supported by RTEMS but could be
-in a future version.
+This routine is not currently supported by RTEMS but could be in a future
+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*
- The
+.. list-table::
+ :class: rtems-table
+
+ * - ``E``
+ - The
**DESCRIPTION:**
**NOTES:**
-This routine is not currently supported by RTEMS but could be
-in a future version.
+This routine is not currently supported by RTEMS but could be in a future
+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*
- The
+.. list-table::
+ :class: rtems-table
+
+ * - ``E``
+ - The
**DESCRIPTION:**
**NOTES:**
-This routine is not currently supported by RTEMS but could be
-in a future version.
+This routine is not currently supported by RTEMS but could be in a future
+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*
- The
+.. list-table::
+ :class: rtems-table
+
+ * - ``E``
+ - The
**DESCRIPTION:**
**NOTES:**
-This routine is not currently supported by RTEMS but could be
-in a future version.
-
-.. COMMENT: COPYRIGHT (c) 1988-2002.
-
-.. COMMENT: On-Line Applications Research Corporation (OAR).
-
-.. COMMENT: All rights reserved.
-
+This routine is not currently supported by RTEMS but could be in a future
+version.
diff --git a/posix_users/files_and_directory.rst b/posix_users/files_and_directory.rst
index 7ebb8b4..a9d95c0 100644
--- a/posix_users/files_and_directory.rst
+++ b/posix_users/files_and_directory.rst
@@ -1,3 +1,7 @@
+.. COMMENT: COPYRIGHT (c) 1988-2002.
+.. COMMENT: On-Line Applications Research Corporation (OAR).
+.. COMMENT: All rights reserved.
+
Files and Directories Manager
#############################
@@ -8,73 +12,73 @@ The files and directories manager is ...
The directives provided by the files and directories manager are:
-- ``opendir`` - Open a Directory
+- opendir_ - Open a Directory
-- ``readdir`` - Reads a directory
+- readdir_ - Reads a directory
-- ``rewinddir`` - Resets the ``readdir()`` pointer
+- rewinddir_ - Resets the ``readdir()`` pointer
-- ``scandir`` - Scan a directory for matching entries
+- scandir_ - Scan a directory for matching entries
-- ``telldir`` - Return current location in directory stream
+- telldir_ - Return current location in directory stream
-- ``closedir`` - Ends directory read operation
+- closedir_ - Ends directory read operation
-- ``getdents`` - Get directory entries
+- getdents_ - Get directory entries
-- ``chdir`` - Changes the current working directory
+- chdir_ - Changes the current working directory
-- ``fchdir`` - Changes the current working directory
+- fchdir_ - Changes the current working directory
-- ``getcwd`` - Gets current working directory
+- getcwd_ - Gets current working directory
-- ``open`` - Opens a file
+- open_ - Opens a file
-- ``creat`` - Create a new file or rewrite an existing one
+- creat_ - Create a new file or rewrite an existing one
-- ``umask`` - Sets a file creation mask
+- umask_ - Sets a file creation mask
-- ``link`` - Creates a link to a file
+- link_ - Creates a link to a file
-- ``symlink`` - Creates a symbolic link to a file
+- symlink_ - Creates a symbolic link to a file
-- ``readlink`` - Obtain the name of the link destination
+- readlink_ - Obtain the name of the link destination
-- ``mkdir`` - Makes a directory
+- mkdir_ - Makes a directory
-- ``mkfifo`` - Makes a FIFO special file
+- mkfifo_ - Makes a FIFO special file
-- ``unlink`` - Removes a directory entry
+- unlink_ - Removes a directory entry
-- ``rmdir`` - Delete a directory
+- rmdir_ - Delete a directory
-- ``rename`` - Renames a file
+- rename_ - Renames a file
-- ``stat`` - Gets information about a file.
+- stat_ - Gets information about a file.
-- ``fstat`` - Gets file status
+- fstat_ - Gets file status
-- ``lstat`` - Gets file status
+- lstat_ - Gets file status
-- ``access`` - Check permissions for a file.
+- access_ - Check permissions for a file.
-- ``chmod`` - Changes file mode
+- chmod_ - Changes file mode
-- ``fchmod`` - Changes permissions of a file
+- fchmod_ - Changes permissions of a file
-- ``chown`` - Changes the owner and/ or group of a file
+- chown_ - Changes the owner and/ or group of a file
-- ``utime`` - Change access and/or modification times of an inode
+- utime_ - Change access and/or modification times of an inode
-- ``ftruncate`` - Truncate a file to a specified length
+- ftruncate_ - Truncate a file to a specified length
-- ``truncate`` - Truncate a file to a specified length
+- truncate_ - Truncate a file to a specified length
-- ``pathconf`` - Gets configuration values for files
+- pathconf_ - Gets configuration values for files
-- ``fpathconf`` - Get configuration values for files
+- fpathconf_ - Get configuration values for files
-- ``mknod`` - Create a directory
+- mknod_ - Create a directory
Background
==========
@@ -82,18 +86,17 @@ Background
Path Name Evaluation
--------------------
-A pathname is a string that consists of no more than ``PATH_MAX``
-bytes, including the terminating null character. A pathname has an optional
-beginning slash, followed by zero or more filenames separated by slashes.
-If the pathname refers to a directory, it may also have one or more trailing
-slashes. Multiple successive slahes are considered to be the same as
-one slash.
+A pathname is a string that consists of no more than ``PATH_MAX`` bytes,
+including the terminating null character. A pathname has an optional beginning
+slash, followed by zero or more filenames separated by slashes. If the
+pathname refers to a directory, it may also have one or more trailing
+slashes. Multiple successive slahes are considered to be the same as one slash.
POSIX allows a pathname that begins with precisely two successive slashes to be
interpreted in an implementation-defined manner. RTEMS does not currently
-recognize this as a special condition. Any number of successive
-slashes is treated the same as a single slash. POSIX requires that
-an implementation treat more than two leading slashes as a single slash.
+recognize this as a special condition. Any number of successive slashes is
+treated the same as a single slash. POSIX requires that an implementation treat
+more than two leading slashes as a single slash.
Operations
==========
@@ -103,10 +106,11 @@ There is currently no text in this section.
Directives
==========
-This section details the files and directories manager's directives.
-A subsection is dedicated to each of this manager's directives
-and describes the calling sequence, related constants, usage,
-and status codes.
+This section details the files and directories manager's directives. A
+subsection is dedicated to each of this manager's directives and describes the
+calling sequence, related constants, usage, and status codes.
+
+.. _opendir:
opendir - Open a Directory
--------------------------
@@ -115,34 +119,32 @@ opendir - Open a Directory
**CALLING SEQUENCE:**
-.. code:: c
+.. code-block:: c
#include <sys/types.h>
#include <dirent.h>
int opendir(
- const char \*dirname
+ const char *dirname
);
**STATUS CODES:**
-*EACCES*
- Search permission was denied on a component of the path
- prefix of ``dirname``, or read permission is denied
-
-*EMFILE*
- Too many file descriptors in use by process
-
-*ENFILE*
- Too many files are currently open in the system.
-
-*ENOENT*
- Directory does not exist, or ``name`` is an empty string.
-
-*ENOMEM*
- Insufficient memory to complete the operation.
-
-*ENOTDIR*
- ``name`` is not a directory.
+.. list-table::
+ :class: rtems-table
+
+ * - ``EACCES``
+ - Search permission was denied on a component of the path prefix of
+ ``dirname``, or read permission is denied
+ * - ``EMFILE``
+ - Too many file descriptors in use by process
+ * - ``ENFILE``
+ - Too many files are currently open in the system.
+ * - ``ENOENT``
+ - Directory does not exist, or ``name`` is an empty string.
+ * - ``ENOMEM``
+ - Insufficient memory to complete the operation.
+ * - ``ENOTDIR``
+ - ``name`` is not a directory.
**DESCRIPTION:**
@@ -154,6 +156,8 @@ directory stream is positioned at the first entry.
The routine is implemented in Cygnus newlib.
+.. _readdir:
+
readdir - Reads a directory
---------------------------
.. index:: readdir
@@ -161,37 +165,45 @@ readdir - Reads a directory
**CALLING SEQUENCE:**
-.. code:: c
+.. code-block:: c
#include <sys/types.h>
#include <dirent.h>
- int readdir(
- DIR \*dirp
+ int readdir(
+ DIR *dirp
);
**STATUS CODES:**
-*EBADF*
- Invalid file descriptor
+.. list-table::
+ :class: rtems-table
+
+ * - ``EBADF``
+ - Invalid file descriptor
**DESCRIPTION:**
The ``readdir()`` function returns a pointer to a structure ``dirent``
-representing the next directory entry from the directory stream pointed to
-by ``dirp``. On end-of-file, NULL is returned.
+representing the next directory entry from the directory stream pointed to by
+``dirp``. On end-of-file, ``NULL`` is returned.
-The ``readdir()`` function may (or may not) return entries for . or .. Your
-program should tolerate reading dot and dot-dot but not require them.
+The ``readdir()`` function may (or may not) return entries for ``.`` or ``..``
+Your program should tolerate reading dot and dot-dot but not require them.
-The data pointed to be ``readdir()`` may be overwritten by another call to``readdir()`` for the same directory stream. It will not be overwritten by
-a call for another directory.
+The data pointed to be ``readdir()`` may be overwritten by another call to
+``readdir()`` for the same directory stream. It will not be overwritten by a
+call for another directory.
**NOTES:**
-If ``ptr`` is not a pointer returned by ``malloc()``, ``calloc()``, or``realloc()`` or has been deallocated with ``free()`` or``realloc()``, the results are not portable and are probably disastrous.
+If ``ptr`` is not a pointer returned by ``malloc()``, ``calloc()``, or
+``realloc()`` or has been deallocated with ``free()`` or ``realloc()``, the
+results are not portable and are probably disastrous.
The routine is implemented in Cygnus newlib.
+.. _rewinddir:
+
rewinddir - Resets the readdir() pointer
----------------------------------------
.. index:: rewinddir
@@ -199,12 +211,12 @@ rewinddir - Resets the readdir() pointer
**CALLING SEQUENCE:**
-.. code:: c
+.. code-block:: c
#include <sys/types.h>
#include <dirent.h>
void rewinddir(
- DIR \*dirp
+ DIR *dirp
);
**STATUS CODES:**
@@ -213,19 +225,20 @@ No value is returned.
**DESCRIPTION:**
-The ``rewinddir()`` function resets the position associated with
-the directory stream pointed to by ``dirp``. It also causes the
-directory stream to refer to the current state of the directory.
+The ``rewinddir()`` function resets the position associated with the directory
+stream pointed to by ``dirp``. It also causes the directory stream to refer to
+the current state of the directory.
**NOTES:**
NONE
-If ``dirp`` is not a pointer by ``opendir()``, the results are
-undefined.
+If ``dirp`` is not a pointer by ``opendir()``, the results are undefined.
The routine is implemented in Cygnus newlib.
+.. _scandir:
+
scandir - Scan a directory for matching entries
-----------------------------------------------
.. index:: scandir
@@ -233,33 +246,39 @@ scandir - Scan a directory for matching entries
**CALLING SEQUENCE:**
-.. code:: c
+.. code-block:: c
#include <dirent.h>
int scandir(
- const char \*dir,
- struct dirent \***namelist,
- int (\*select)(const struct dirent \*),
- int (\*compar)(const struct dirent \**, const struct dirent \**)
+ const char *dir,
+ struct dirent ***namelist,
+ int (*select)(const struct dirent *),
+ int (*compar)(const struct dirent **, const struct dirent **)
);
**STATUS CODES:**
-*ENOMEM*
- Insufficient memory to complete the operation.
+.. list-table::
+ :class: rtems-table
+
+ * - ``ENOMEM``
+ - Insufficient memory to complete the operation.
**DESCRIPTION:**
-The ``scandir()`` function scans the directory ``dir``, calling``select()`` on each directory entry. Entries for which ``select()``
-returns non-zero are stored in strings allocated via ``malloc()``,
-sorted using ``qsort()`` with the comparison function ``compar()``,
-and collected in array ``namelist`` which is allocated via ``malloc()``.
-If ``select`` is NULL, all entries are selected.
+The ``scandir()`` function scans the directory ``dir``, calling ``select()`` on
+each directory entry. Entries for which ``select()`` returns non-zero are
+stored in strings allocated via ``malloc()``, sorted using ``qsort()`` with the
+comparison function ``compar()``, and collected in array ``namelist`` which is
+allocated via ``malloc()``. If ``select`` is ``NULL``, all entries are
+selected.
**NOTES:**
The routine is implemented in Cygnus newlib.
+.. _telldir:
+
telldir - Return current location in directory stream
-----------------------------------------------------
.. index:: telldir
@@ -267,17 +286,20 @@ telldir - Return current location in directory stream
**CALLING SEQUENCE:**
-.. code:: c
+.. code-block:: c
#include <dirent.h>
off_t telldir(
- DIR \*dir
+ DIR *dir
);
**STATUS CODES:**
-*EBADF*
- Invalid directory stream descriptor ``dir``.
+.. list-table::
+ :class: rtems-table
+
+ * - ``EBADF``
+ - Invalid directory stream descriptor ``dir``.
**DESCRIPTION:**
@@ -288,6 +310,8 @@ directory stream ``dir``.
The routine is implemented in Cygnus newlib.
+.. _closedir:
+
closedir - Ends directory read operation
----------------------------------------
.. index:: closedir
@@ -295,33 +319,38 @@ closedir - Ends directory read operation
**CALLING SEQUENCE:**
-.. code:: c
+.. code-block:: c
#include <sys/types.h>
#include <dirent.h>
int closedir(
- DIR \*dirp
+ DIR *dirp
);
**STATUS CODES:**
-*EBADF*
- Invalid file descriptor
+.. list-table::
+ :class: rtems-table
+
+ * - ``EBADF``
+ - Invalid file descriptor
**DESCRIPTION:**
-The directory stream associated with ``dirp`` is closed.
-The value in ``dirp`` may not be usable after a call to``closedir()``.
+The directory stream associated with ``dirp`` is closed. The value in ``dirp``
+may not be usable after a call to ``closedir()``.
**NOTES:**
NONE
-The argument to ``closedir()`` must be a pointer returned by``opendir()``. If it is not, the results are not portable and
-most likely unpleasant.
+The argument to ``closedir()`` must be a pointer returned by ``opendir()``. If
+it is not, the results are not portable and most likely unpleasant.
The routine is implemented in Cygnus newlib.
+.. _chdir:
+
chdir - Changes the current working directory
---------------------------------------------
.. index:: chdir
@@ -329,45 +358,45 @@ chdir - Changes the current working directory
**CALLING SEQUENCE:**
-.. code:: c
+.. code-block:: c
#include <unistd.h>
int chdir(
- const char \*path
+ const char *path
);
**STATUS CODES:**
-On error, this routine returns -1 and sets ``errno`` to one of
-the following:
-
-*EACCES*
- Search permission is denied for a directory in a file's path prefix.
+On error, this routine returns -1 and sets ``errno`` to one of the following:
-*ENAMETOOLONG*
- Length of a filename string exceeds PATH_MAX and _POSIX_NO_TRUNC is
- in effect.
+.. list-table::
+ :class: rtems-table
-*ENOENT*
- A file or directory does not exist.
-
-*ENOTDIR*
- A component of the specified pathname was not a directory when directory
- was expected.
+ * - ``EACCES``
+ - Search permission is denied for a directory in a file's path prefix.
+ * - ``ENAMETOOLONG``
+ - Length of a filename string exceeds ``PATH_MAX`` and ``_POSIX_NO_TRUNC``
+ is in effect.
+ * - ``ENOENT``
+ - A file or directory does not exist.
+ * - ``ENOTDIR``
+ - A component of the specified pathname was not a directory when directory
+ was expected.
**DESCRIPTION:**
-The ``chdir()`` function causes the directory named by ``path`` to
-become the current working directory; that is, the starting point for
-searches of pathnames not beginning with a slash.
+The ``chdir()`` function causes the directory named by ``path`` to become the
+current working directory; that is, the starting point for searches of
+pathnames not beginning with a slash.
-If ``chdir()`` detects an error, the current working directory is not
-changed.
+If ``chdir()`` detects an error, the current working directory is not changed.
**NOTES:**
NONE
+.. _fchdir:
+
fchdir - Changes the current working directory
----------------------------------------------
.. index:: fchdir
@@ -375,45 +404,45 @@ fchdir - Changes the current working directory
**CALLING SEQUENCE:**
-.. code:: c
+.. code-block:: c
#include <unistd.h>
int fchdir(
- int fd
+ int fd
);
**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:
-*EACCES*
- Search permission is denied for a directory in a file's path prefix.
+.. list-table::
+ :class: rtems-table
-*ENAMETOOLONG*
- Length of a filename string exceeds PATH_MAX and _POSIX_NO_TRUNC is
- in effect.
-
-*ENOENT*
- A file or directory does not exist.
-
-*ENOTDIR*
- A component of the specified pathname was not a directory when directory
- was expected.
+ * - ``EACCES``
+ - Search permission is denied for a directory in a file's path prefix.
+ * - ``ENAMETOOLONG``
+ - Length of a filename string exceeds ``PATH_MAX`` and ``_POSIX_NO_TRUNC``
+ is in effect.
+ * - ``ENOENT``
+ - A file or directory does not exist.
+ * - ``ENOTDIR``
+ - A component of the specified pathname was not a directory when directory
+ was expected.
**DESCRIPTION:**
-The ``fchdir()`` function causes the directory named by ``fd`` to
-become the current working directory; that is, the starting point for
-searches of pathnames not beginning with a slash.
+The ``fchdir()`` function causes the directory named by ``fd`` to become the
+current working directory; that is, the starting point for searches of
+pathnames not beginning with a slash.
-If ``fchdir()`` detects an error, the current working directory is not
-changed.
+If ``fchdir()`` detects an error, the current working directory is not changed.
**NOTES:**
NONE
+.. _getcwd:
+
getcwd - Gets current working directory
---------------------------------------
.. index:: getcwd
@@ -421,38 +450,41 @@ getcwd - Gets current working directory
**CALLING SEQUENCE:**
-.. code:: c
+.. code-block:: c
#include <unistd.h>
int getcwd( void );
**STATUS CODES:**
-*EINVAL*
- Invalid argument
-
-*ERANGE*
- Result is too large
+.. list-table::
+ :class: rtems-table
-*EACCES*
- Search permission is denied for a directory in a file's path prefix.
+ * - ``EINVAL``
+ - Invalid argument
+ * - ``ERANGE``
+ - Result is too large
+ * - ``EACCES``
+ - Search permission is denied for a directory in a file's path prefix.
**DESCRIPTION:**
-The ``getcwd()`` function copies the absolute pathname of the current
-working directory to the character array pointed to by ``buf``. The``size`` argument is the number of bytes available in ``buf``
+The ``getcwd()`` function copies the absolute pathname of the current working
+directory to the character array pointed to by ``buf``. The ``size`` argument
+is the number of bytes available in ``buf``
**NOTES:**
-There is no way to determine the maximum string length that ``fetcwd()``
-may need to return. Applications should tolerate getting ``ERANGE``
-and allocate a larger buffer.
+There is no way to determine the maximum string length that ``fetcwd()`` may
+need to return. Applications should tolerate getting ``ERANGE`` and allocate a
+larger buffer.
-It is possible for ``getcwd()`` to return EACCES if, say, ``login``
-puts the process into a directory without read access.
+It is possible for ``getcwd()`` to return EACCES if, say, ``login`` puts the
+process into a directory without read access.
-The 1988 standard uses ``int`` instead of ``size_t`` for the second
-parameter.
+The 1988 standard uses ``int`` instead of ``size_t`` for the second parameter.
+
+.. _open:
open - Opens a file
-------------------
@@ -461,113 +493,104 @@ open - Opens a file
**CALLING SEQUENCE:**
-.. code:: c
+.. code-block:: c
#include <sys/types.h>
#include <sys/stat.h>
#include <fcntl.h>
int open(
- const char \*path,
- int oflag,
- mode_t mode
+ const char *path,
+ int oflag,
+ mode_t mode
);
**STATUS CODES:**
-*EACCES*
- Search permission is denied for a directory in a file's path prefix.
-
-*EEXIST*
- The named file already exists.
-
-*EINTR*
- Function was interrupted by a signal.
-
-*EISDIR*
- Attempt to open a directory for writing or to rename a file to be a
- directory.
-
-*EMFILE*
- Too many file descriptors are in use by this process.
-
-*ENAMETOOLONG*
- Length of a filename string exceeds PATH_MAX and _POSIX_NO_TRUNC is in
- effect.
-
-*ENFILE*
- Too many files are currently open in the system.
-
-*ENOENT*
- A file or directory does not exist.
-
-*ENOSPC*
- No space left on disk.
-
-*ENOTDIR*
- A component of the specified pathname was not a directory when a directory
- was expected.
-
-*ENXIO*
- No such device. This error may also occur when a device is not ready, for
- example, a tape drive is off-line.
-
-*EROFS*
- Read-only file system.
+.. list-table::
+ :class: rtems-table
+
+ * - ``EACCES``
+ - Search permission is denied for a directory in a file's path prefix.
+ * - ``EEXIST``
+ - The named file already exists.
+ * - ``EINTR``
+ - Function was interrupted by a signal.
+ * - ``EISDIR``
+ - Attempt to open a directory for writing or to rename a file to be a
+ directory.
+ * - ``EMFILE``
+ - Too many file descriptors are in use by this process.
+ * - ``ENAMETOOLONG``
+ - Length of a filename string exceeds ``PATH_MAX`` and ``_POSIX_NO_TRUNC``
+ is in effect.
+ * - ``ENFILE``
+ - Too many files are currently open in the system.
+ * - ``ENOENT``
+ - A file or directory does not exist.
+ * - ``ENOSPC``
+ - No space left on disk.
+ * - ``ENOTDIR``
+ - A component of the specified pathname was not a directory when a directory
+ was expected.
+ * - ``ENXIO``
+ - No such device. This error may also occur when a device is not ready, for
+ example, a tape drive is off-line.
+ * - ``EROFS``
+ - Read-only file system.
**DESCRIPTION:**
The ``open`` function establishes a connection between a file and a file
descriptor. The file descriptor is a small integer that is used by I/O
-functions to reference the file. The ``path`` argument points to the
-pathname for the file.
-
-The ``oflag`` argument is the bitwise inclusive OR of the values of
-symbolic constants. The programmer must specify exactly one of the following
-three symbols:
+functions to reference the file. The ``path`` argument points to the pathname
+for the file.
-*O_RDONLY*
- Open for reading only.
+The ``oflag`` argument is the bitwise inclusive OR of the values of symbolic
+constants. The programmer must specify exactly one of the following three
+symbols:
-*O_WRONLY*
- Open for writing only.
+.. list-table::
+ :class: rtems-table
-*O_RDWR*
- Open for reading and writing.
+ * - ``O_RDONLY``
+ - Open for reading only.
+ * - ``O_WRONLY``
+ - Open for writing only.
+ * - ``O_RDWR``
+ - Open for reading and writing.
Any combination of the following symbols may also be used.
-*O_APPEND*
- Set the file offset to the end-of-file prior to each write.
-
-*O_CREAT*
- If the file does not exist, allow it to be created. This flag indicates
- that the ``mode`` argument is present in the call to ``open``.
-
-*O_EXCL*
- This flag may be used only if O_CREAT is also set. It causes the call
- to ``open`` to fail if the file already exists.
-
-*O_NOCTTY*
- If ``path`` identifies a terminal, this flag prevents that teminal from
- becoming the controlling terminal for thi9s process. See Chapter 8 for a
- description of terminal I/O.
-
-*O_NONBLOCK*
- Do no wait for the device or file to be ready or available. After the file
- is open, the ``read`` and ``write`` calls return immediately. If the
- process would be delayed in the read or write opermation, -1 is returned and``errno`` is set to ``EAGAIN`` instead of blocking the caller.
-
-*O_TRUNC*
- This flag should be used only on ordinary files opened for writing. It
- causes the file to be tuncated to zero length..
-
-Upon successful completion, ``open`` returns a non-negative file
-descriptor.
+.. list-table::
+ :class: rtems-table
+
+ * - ``O_APPEND``
+ - Set the file offset to the end-of-file prior to each write.
+ * - ``O_CREAT``
+ - If the file does not exist, allow it to be created. This flag indicates
+ that the ``mode`` argument is present in the call to ``open``.
+ * - ``O_EXCL``
+ - This flag may be used only if ``O_CREAT`` is also set. It causes the call
+ to ``open`` to fail if the file already exists.
+ * - ``O_NOCTTY``
+ - Do not assign controlling terminal.
+ * - ``O_NONBLOCK``
+ - Do no wait for the device or file to be ready or available. After the file
+ is open, the ``read`` and ``write`` calls return immediately. If the
+ process would be delayed in the read or write opermation, -1 is returned
+ and``errno`` is set to ``EAGAIN`` instead of blocking the caller.
+ * - ``O_TRUNC``
+ - This flag should be used only on ordinary files opened for writing. It
+ causes the file to be tuncated to zero length..
+
+Upon successful completion, ``open`` returns a non-negative file descriptor.
**NOTES:**
NONE
+.. _creat:
+
creat - Create a new file or rewrite an existing one
----------------------------------------------------
.. index:: creat
@@ -575,65 +598,55 @@ creat - Create a new file or rewrite an existing one
**CALLING SEQUENCE:**
-.. code:: c
+.. code-block:: c
#include <sys/types.h>
#include <sys/stat.h>
#include <fcntl.h>
int creat(
- const char \*path,
- mode_t mode
+ const char *path,
+ mode_t mode
);
**STATUS CODES:**
-*EEXIST*
- ``path`` already exists and O_CREAT and O_EXCL were used.
-
-*EISDIR*
- ``path`` refers to a directory and the access requested involved
- writing
-
-*ETXTBSY*
- ``path`` refers to an executable image which is currently being
- executed and write access was requested
-
-*EFAULT*
- ``path`` points outside your accessible address space
-
-*EACCES*
- The requested access to the file is not allowed, or one of the
- directories in ``path`` did not allow search (execute) permission.
-
-*ENAMETOOLONG*
- ``path`` was too long.
-
-*ENOENT*
- A directory component in ``path`` does not exist or is a dangling
- symbolic link.
-
-*ENOTDIR*
- A component used as a directory in ``path`` is not, in fact, a
- directory.
-
-*EMFILE*
- The process alreadyh has the maximum number of files open.
-
-*ENFILE*
- The limit on the total number of files open on the system has been
- reached.
-
-*ENOMEM*
- Insufficient kernel memory was available.
-
-*EROFS*
- ``path`` refers to a file on a read-only filesystem and write access
- was requested
+.. list-table::
+ :class: rtems-table
+
+ * - ``EEXIST``
+ - ``path`` already exists and ``O_CREAT`` and ``O_EXCL`` were used.
+ * - ``EISDIR``
+ - ``path`` refers to a directory and the access requested involved writing
+ * - ``ETXTBSY``
+ - ``path`` refers to an executable image which is currently being executed
+ and write access was requested
+ * - ``EFAULT``
+ - ``path`` points outside your accessible address space
+ * - ``EACCES``
+ - The requested access to the file is not allowed, or one of the directories
+ in ``path`` did not allow search (execute) permission.
+ * - ``ENAMETOOLONG``
+ - ``path`` was too long.
+ * - ``ENOENT``
+ - A directory component in ``path`` does not exist or is a dangling symbolic
+ link.
+ * - ``ENOTDIR``
+ - A component used as a directory in ``path`` is not, in fact, a directory.
+ * - ``EMFILE``
+ - The process alreadyh has the maximum number of files open.
+ * - ``ENFILE``
+ - The limit on the total number of files open on the system has been
+ reached.
+ * - ``ENOMEM``
+ - Insufficient kernel memory was available.
+ * - ``EROFS``
+ - ``path`` refers to a file on a read-only filesystem and write access was
+ requested
**DESCRIPTION:**
-``creat`` attempts to create a file and return a file descriptor for
-use in read, write, etc.
+``creat`` attempts to create a file and return a file descriptor for use in
+read, write, etc.
**NOTES:**
@@ -641,6 +654,8 @@ NONE
The routine is implemented in Cygnus newlib.
+.. _umask:
+
umask - Sets a file creation mask.
----------------------------------
.. index:: umask
@@ -648,34 +663,37 @@ umask - Sets a file creation mask.
**CALLING SEQUENCE:**
-.. code:: c
+.. code-block:: c
#include <sys/types.h>
#include <sys/stat.h>
mode_t umask(
- mode_t cmask
+ mode_t cmask
);
**STATUS CODES:**
**DESCRIPTION:**
-The ``umask()`` function sets the process file creation mask to ``cmask``.
-The file creation mask is used during ``open()``, ``creat()``, ``mkdir()``,``mkfifo()`` calls to turn off permission bits in the ``mode`` argument.
-Bit positions that are set in ``cmask`` are cleared in the mode of the
-created file.
+The ``umask()`` function sets the process file creation mask to ``cmask``. The
+file creation mask is used during ``open()``, ``creat()``, ``mkdir()``,
+``mkfifo()`` calls to turn off permission bits in the ``mode`` argument. Bit
+positions that are set in ``cmask`` are cleared in the mode of the created
+file.
**NOTES:**
NONE
-The ``cmask`` argument should have only permission bits set. All other
-bits should be zero.
+The ``cmask`` argument should have only permission bits set. All other bits
+should be zero.
+
+In a system which supports multiple processes, the file creation mask is
+inherited across ``fork()`` and ``exec()`` calls. This makes it possible to
+alter the default permission bits of created files. RTEMS does not support
+multiple processes so this behavior is not possible.
-In a system which supports multiple processes, the file creation mask is inherited
-across ``fork()`` and ``exec()`` calls. This makes it possible to alter the
-default permission bits of created files. RTEMS does not support multiple processes
-so this behavior is not possible.
+.. _link:
link - Creates a link to a file
-------------------------------
@@ -684,53 +702,47 @@ link - Creates a link to a file
**CALLING SEQUENCE:**
-.. code:: c
+.. code-block:: c
#include <unistd.h>
int link(
- const char \*existing,
- const char \*new
+ const char *existing,
+ const char *new
);
**STATUS CODES:**
-*EACCES*
- Search permission is denied for a directory in a file's path prefix
-
-*EEXIST*
- The named file already exists.
-
-*EMLINK*
- The number of links would exceed ``LINK_MAX``.
-
-*ENAMETOOLONG*
- Length of a filename string exceeds PATH_MAX and _POSIX_NO_TRUNC is in
- effect.
-
-*ENOENT*
- A file or directory does not exist.
-
-*ENOSPC*
- No space left on disk.
-
-*ENOTDIR*
- A component of the specified pathname was not a directory when a directory
- was expected.
-
-*EPERM*
- Operation is not permitted. Process does not have the appropriate priviledges
- or permissions to perform the requested operations.
-
-*EROFS*
- Read-only file system.
-
-*EXDEV*
- Attempt to link a file to another file system.
+.. list-table::
+ :class: rtems-table
+
+ * - ``EACCES``
+ - Search permission is denied for a directory in a file's path prefix
+ * - ``EEXIST``
+ - The named file already exists.
+ * - ``EMLINK``
+ - The number of links would exceed ``LINK_MAX``.
+ * - ``ENAMETOOLONG``
+ - Length of a filename string exceeds ``PATH_MAX`` and ``_POSIX_NO_TRUNC``
+ is in effect.
+ * - ``ENOENT``
+ - A file or directory does not exist.
+ * - ``ENOSPC``
+ - No space left on disk.
+ * - ``ENOTDIR``
+ - A component of the specified pathname was not a directory when a directory
+ was expected.
+ * - ``EPERM``
+ - Operation is not permitted. Process does not have the appropriate
+ priviledges or permissions to perform the requested operations.
+ * - ``EROFS``
+ - Read-only file system.
+ * - ``EXDEV``
+ - Attempt to link a file to another file system.
**DESCRIPTION:**
-The ``link()`` function atomically creates a new link for an existing file
-and increments the link count for the file.
+The ``link()`` function atomically creates a new link for an existing file and
+increments the link count for the file.
If the ``link()`` function fails, no directories are modified.
@@ -742,6 +754,8 @@ The caller may (or may not) need permission to access the existing file.
NONE
+.. _symlink:
+
symlink - Creates a symbolic link to a file
-------------------------------------------
.. index:: symlink
@@ -749,42 +763,38 @@ symlink - Creates a symbolic link to a file
**CALLING SEQUENCE:**
-.. code:: c
+.. code-block:: c
#include <unistd.h>
int symlink(
- const char \*topath,
- const char \*frompath
+ const char *topath,
+ const char *frompath
);
**STATUS CODES:**
-*EACCES*
- Search permission is denied for a directory in a file's path prefix
-
-*EEXIST*
- The named file already exists.
-
-*ENAMETOOLONG*
- Length of a filename string exceeds PATH_MAX and _POSIX_NO_TRUNC is in
- effect.
-
-*ENOENT*
- A file or directory does not exist.
-
-*ENOSPC*
- No space left on disk.
-
-*ENOTDIR*
- A component of the specified pathname was not a directory when a directory
- was expected.
-
-*EPERM*
- Operation is not permitted. Process does not have the appropriate priviledges
- or permissions to perform the requested operations.
-
-*EROFS*
- Read-only file system.
+.. list-table::
+ :class: rtems-table
+
+ * - ``EACCES``
+ - Search permission is denied for a directory in a file's path prefix
+ * - ``EEXIST``
+ - The named file already exists.
+ * - ``ENAMETOOLONG``
+ - Length of a filename string exceeds ``PATH_MAX`` and ``_POSIX_NO_TRUNC``
+ is in effect.
+ * - ``ENOENT``
+ - A file or directory does not exist.
+ * - ``ENOSPC``
+ - No space left on disk.
+ * - ``ENOTDIR``
+ - A component of the specified pathname was not a directory when a directory
+ was expected.
+ * - ``EPERM``
+ - Operation is not permitted. Process does not have the appropriate
+ priviledges or permissions to perform the requested operations.
+ * - ``EROFS``
+ - Read-only file system.
**DESCRIPTION:**
@@ -799,6 +809,8 @@ The caller may (or may not) need permission to access the existing file.
NONE
+.. _readlink:
+
readlink - Obtain the name of a symbolic link destination
---------------------------------------------------------
.. index:: readlink
@@ -806,51 +818,51 @@ readlink - Obtain the name of a symbolic link destination
**CALLING SEQUENCE:**
-.. code:: c
+.. code-block:: c
#include <unistd.h>
int readlink(
- const char \*path,
- char \*buf,
- size_t bufsize
+ const char *path,
+ char *buf,
+ size_t bufsize
);
**STATUS CODES:**
-*EACCES*
- Search permission is denied for a directory in a file's path prefix
-
-*ENAMETOOLONG*
- Length of a filename string exceeds PATH_MAX and _POSIX_NO_TRUNC is in
- effect.
-
-*ENOENT*
- A file or directory does not exist.
-
-*ENOTDIR*
- A component of the prefix pathname was not a directory when a directory
- was expected.
-
-*ELOOP*
- Too many symbolic links were encountered in the pathname.
-
-*EINVAL*
- The pathname does not refer to a symbolic link
-
-*EFAULT*
- An invalid pointer was passed into the ``readlink()`` routine.
+.. list-table::
+ :class: rtems-table
+
+ * - ``EACCES``
+ - Search permission is denied for a directory in a file's path prefix
+ * - ``ENAMETOOLONG``
+ - Length of a filename string exceeds ``PATH_MAX`` and ``_POSIX_NO_TRUNC``
+ is in effect.
+ * - ``ENOENT``
+ - A file or directory does not exist.
+ * - ``ENOTDIR``
+ - A component of the prefix pathname was not a directory when a directory
+ was expected.
+ * - ``ELOOP``
+ - Too many symbolic links were encountered in the pathname.
+ * - ``EINVAL``
+ - The pathname does not refer to a symbolic link
+ * - ``EFAULT``
+ - An invalid pointer was passed into the ``readlink()`` routine.
**DESCRIPTION:**
-The ``readlink()`` function places the symbolic link destination into``buf`` argument and returns the number of characters copied.
+The ``readlink()`` function places the symbolic link destination into ``buf``
+argument and returns the number of characters copied.
-If the symbolic link destination is longer than bufsize characters the
-name will be truncated.
+If the symbolic link destination is longer than bufsize characters the name
+will be truncated.
**NOTES:**
NONE
+.. _mkdir:
+
mkdir - Makes a directory
-------------------------
.. index:: mkdir
@@ -858,57 +870,54 @@ mkdir - Makes a directory
**CALLING SEQUENCE:**
-.. code:: c
+.. code-block:: c
#include <sys/types.h>
#include <sys/stat.h>
int mkdir(
- const char \*path,
- mode_t mode
+ const char *path,
+ mode_t mode
);
**STATUS CODES:**
-*EACCES*
- Search permission is denied for a directory in a file's path prefix
-
-*EEXIST*
- The name file already exist.
-
-*EMLINK*
- The number of links would exceed LINK_MAX
-
-*ENAMETOOLONG*
- Length of a filename string exceeds PATH_MAX and _POSIX_NO_TRUNC is in
- effect.
-
-*ENOENT*
- A file or directory does not exist.
-
-*ENOSPC*
- No space left on disk.
-
-*ENOTDIR*
- A component of the specified pathname was not a directory when a directory
- was expected.
-
-*EROFS*
- Read-only file system.
+.. list-table::
+ :class: rtems-table
+
+ * - ``EACCES``
+ - Search permission is denied for a directory in a file's path prefix
+ * - ``EEXIST``
+ - The name file already exist.
+ * - ``EMLINK``
+ - The number of links would exceed ``LINK_MAX``
+ * - ``ENAMETOOLONG``
+ - Length of a filename string exceeds ``PATH_MAX`` and ``_POSIX_NO_TRUNC``
+ is in effect.
+ * - ``ENOENT``
+ - A file or directory does not exist.
+ * - ``ENOSPC``
+ - No space left on disk.
+ * - ``ENOTDIR``
+ - A component of the specified pathname was not a directory when a directory
+ was expected.
+ * - ``EROFS``
+ - Read-only file system.
**DESCRIPTION:**
-The ``mkdir()`` function creates a new diectory named ``path``. The
-permission bits (modified by the file creation mask) are set from ``mode``.
-The owner and group IDs for the directory are set from the effective user ID
-and group ID.
+The ``mkdir()`` function creates a new diectory named ``path``. The permission
+bits (modified by the file creation mask) are set from ``mode``. The owner and
+group IDs for the directory are set from the effective user ID and group ID.
-The new directory may (or may not) contain entries for.. and .. but is otherwise
-empty.
+The new directory may (or may not) contain entries for ``.`` and ``..`` but is
+otherwise empty.
**NOTES:**
NONE
+.. _mkfifo:
+
mkfifo - Makes a FIFO special file
----------------------------------
.. index:: mkfifo
@@ -916,46 +925,47 @@ mkfifo - Makes a FIFO special file
**CALLING SEQUENCE:**
-.. code:: c
+.. code-block:: c
#include <sys/types.h>
#include <sys/stat.h>
int mkfifo(
- const char \*path,
- mode_t mode
+ const char *path,
+ mode_t mode
);
**STATUS CODES:**
-*EACCES*
- Search permission is denied for a directory in a file's path prefix
-
-*EEXIST*
- The named file already exists.
-
-*ENOENT*
- A file or directory does not exist.
-
-*ENOSPC*
- No space left on disk.
-
-*ENOTDIR*
- A component of the specified ``path`` was not a directory when a directory
- was expected.
-
-*EROFS*
- Read-only file system.
+.. list-table::
+ :class: rtems-table
+
+ * - ``EACCES``
+ - Search permission is denied for a directory in a file's path prefix
+ * - ``EEXIST``
+ - The named file already exists.
+ * - ``ENOENT``
+ - A file or directory does not exist.
+ * - ``ENOSPC``
+ - No space left on disk.
+ * - ``ENOTDIR``
+ - A component of the specified ``path`` was not a directory when a directory
+ was expected.
+ * - ``EROFS``
+ - Read-only file system.
**DESCRIPTION:**
-The ``mkfifo()`` function creates a new FIFO special file named ``path``.
-The permission bits (modified by the file creation mask) are set from``mode``. The owner and group IDs for the FIFO are set from the efective
-user ID and group ID.
+The ``mkfifo()`` function creates a new FIFO special file named ``path``. The
+permission bits (modified by the file creation mask) are set from ``mode``. The
+owner and group IDs for the FIFO are set from the efective user ID and
+group ID.
**NOTES:**
NONE
+.. _unlink:
+
unlink - Removes a directory entry
----------------------------------
.. index:: unlink
@@ -963,50 +973,49 @@ unlink - Removes a directory entry
**CALLING SEQUENCE:**
-.. code:: c
+.. code-block:: c
#include <unistd.h>
int unlink(
- const char path
+ const char path
);
**STATUS CODES:**
-*EACCES*
- Search permission is denied for a directory in a file's path prefix
-
-*EBUSY*
- The directory is in use.
-
-*ENAMETOOLONG*
- Length of a filename string exceeds PATH_MAX and _POSIX_NO_TRUNC is in
- effect.
-
-*ENOENT*
- A file or directory does not exist.
-
-*ENOTDIR*
- A component of the specified ``path`` was not a directory when a directory
- was expected.
-
-*EPERM*
- Operation is not permitted. Process does not have the appropriate priviledges
- or permissions to perform the requested operations.
-
-*EROFS*
- Read-only file system.
+.. list-table::
+ :class: rtems-table
+
+ * - ``EACCES``
+ - Search permission is denied for a directory in a file's path prefix
+ * - ``EBUSY``
+ - The directory is in use.
+ * - ``ENAMETOOLONG``
+ - Length of a filename string exceeds ``PATH_MAX`` and ``_POSIX_NO_TRUNC``
+ is in effect.
+ * - ``ENOENT``
+ - A file or directory does not exist.
+ * - ``ENOTDIR``
+ - A component of the specified ``path`` was not a directory when a directory
+ was expected.
+ * - ``EPERM``
+ - Operation is not permitted. Process does not have the appropriate
+ priviledges or permissions to perform the requested operations.
+ * - ``EROFS``
+ - Read-only file system.
**DESCRIPTION:**
The ``unlink`` function removes the link named by ``path`` and decrements the
link count of the file referenced by the link. When the link count goes to zero
-and no process has the file open, the space occupied by the file is freed and the
-file is no longer accessible.
+and no process has the file open, the space occupied by the file is freed and
+the file is no longer accessible.
**NOTES:**
NONE
+.. _rmdir:
+
rmdir - Delete a directory
--------------------------
.. index:: rmdir
@@ -1014,61 +1023,52 @@ rmdir - Delete a directory
**CALLING SEQUENCE:**
-.. code:: c
+.. code-block:: c
#include <unistd.h>
int rmdir(
- const char \*pathname
+ const char *pathname
);
**STATUS CODES:**
-*EPERM*
- The filesystem containing ``pathname`` does not support the removal
- of directories.
-
-*EFAULT*
- ``pathname`` points ouside your accessible address space.
-
-*EACCES*
- Write access to the directory containing ``pathname`` was not
- allowed for the process's effective uid, or one of the directories in``pathname`` did not allow search (execute) permission.
-
-*EPERM*
- The directory containing ``pathname`` has the stickybit (S_ISVTX)
- set and the process's effective uid is neither the uid of the file to
- be delected nor that of the director containing it.
-
-*ENAMETOOLONG*
- ``pathname`` was too long.
-
-*ENOENT*
- A dirctory component in ``pathname`` does not exist or is a
- dangling symbolic link.
-
-*ENOTDIR*
- ``pathname``, or a component used as a directory in ``pathname``,
- is not, in fact, a directory.
-
-*ENOTEMPTY*
- ``pathname`` contains entries other than . and .. .
-
-*EBUSY*
- ``pathname`` is the current working directory or root directory of
- some process
-
-*EBUSY*
- ``pathname`` is the current directory or root directory of some
- process.
-
-*ENOMEM*
- Insufficient kernel memory was available
-
-*EROGS*
- ``pathname`` refers to a file on a read-only filesystem.
-
-*ELOOP*
- ``pathname`` contains a reference to a circular symbolic link
+.. list-table::
+ :class: rtems-table
+
+ * - ``EPERM``
+ - The filesystem containing ``pathname`` does not support the removal of
+ directories.
+ * - ``EFAULT``
+ - ``pathname`` points ouside your accessible address space.
+ * - ``EACCES``
+ - Write access to the directory containing ``pathname`` was not allowed for
+ the process's effective uid, or one of the directories in``pathname`` did
+ not allow search (execute) permission.
+ * - ``EPERM``
+ - The directory containing ``pathname`` has the stickybit (S_ISVTX) set and
+ the process's effective uid is neither the uid of the file to be delected
+ nor that of the director containing it.
+ * - ``ENAMETOOLONG``
+ - ``pathname`` was too long.
+ * - ``ENOENT``
+ - A dirctory component in ``pathname`` does not exist or is a dangling
+ symbolic link.
+ * - ``ENOTDIR``
+ - ``pathname``, or a component used as a directory in ``pathname``, is not,
+ in fact, a directory.
+ * - ``ENOTEMPTY``
+ - ``pathname`` contains entries other than . and .. .
+ * - ``EBUSY``
+ - ``pathname`` is the current working directory or root directory of some
+ process
+ * - ``EBUSY``
+ - ``pathname`` is the current directory or root directory of some process.
+ * - ``ENOMEM``
+ - Insufficient kernel memory was available
+ * - ``EROGS``
+ - ``pathname`` refers to a file on a read-only filesystem.
+ * - ``ELOOP``
+ - ``pathname`` contains a reference to a circular symbolic link
**DESCRIPTION:**
@@ -1078,6 +1078,8 @@ rmdir - Delete a directory
NONE
+.. _rename:
+
rename - Renames a file
-----------------------
.. index:: rename
@@ -1085,75 +1087,69 @@ rename - Renames a file
**CALLING SEQUENCE:**
-.. code:: c
+.. code-block:: c
#include <unistd.h>
int rename(
- const char \*old,
- const char \*new
+ const char *old,
+ const char *new
);
**STATUS CODES:**
-*EACCES*
- Search permission is denied for a directory in a file's path prefix.
-
-*EBUSY*
- The directory is in use.
-
-*EEXIST*
- The named file already exists.
-
-*EINVAL*
- Invalid argument.
-
-*EISDIR*
- Attempt to open a directory for writing or to rename a file to be a
- directory.
-
-*EMLINK*
- The number of links would exceed LINK_MAX.
-
-*ENAMETOOLONG*
- Length of a filename string exceeds PATH_MAX and _POSIX_NO_TRUNC is
- in effect.
-
-*ENOENT*
- A file or directory does no exist.
-
-*ENOSPC*
- No space left on disk.
-
-*ENOTDIR*
- A component of the specified pathname was not a directory when a
- directory was expected.
-
-*ENOTEMPTY*
- Attempt to delete or rename a non-empty directory.
-
-*EROFS*
- Read-only file system
-
-*EXDEV*
- Attempt to link a file to another file system.
+.. list-table::
+ :class: rtems-table
+
+ * - ``EACCES``
+ - Search permission is denied for a directory in a file's path prefix.
+ * - ``EBUSY``
+ - The directory is in use.
+ * - ``EEXIST``
+ - The named file already exists.
+ * - ``EINVAL``
+ - Invalid argument.
+ * - ``EISDIR``
+ - Attempt to open a directory for writing or to rename a file to be a
+ directory.
+ * - ``EMLINK``
+ - The number of links would exceed ``LINK_MAX``.
+ * - ``ENAMETOOLONG``
+ - Length of a filename string exceeds ``PATH_MAX`` and ``_POSIX_NO_TRUNC``
+ is in effect.
+ * - ``ENOENT``
+ - A file or directory does no exist.
+ * - ``ENOSPC``
+ - No space left on disk.
+ * - ``ENOTDIR``
+ - A component of the specified pathname was not a directory when a directory
+ was expected.
+ * - ``ENOTEMPTY``
+ - Attempt to delete or rename a non-empty directory.
+ * - ``EROFS``
+ - Read-only file system
+ * - ``EXDEV``
+ - Attempt to link a file to another file system.
**DESCRIPTION:**
-The ``rename()`` function causes the file known bo ``old`` to
-now be known as ``new``.
+The ``rename()`` function causes the file known bo ``old`` to now be known as
+``new``.
-Ordinary files may be renamed to ordinary files, and directories may be
-renamed to directories; however, files cannot be converted using``rename()``. The ``new`` pathname may not contain a path prefix
-of ``old``.
+Ordinary files may be renamed to ordinary files, and directories may be renamed
+to directories; however, files cannot be converted using ``rename()``. The
+``new`` pathname may not contain a path prefix of ``old``.
**NOTES:**
-If a file already exists by the name ``new``, it is removed. The``rename()`` function is atomic. If the ``rename()`` detects an
-error, no files are removed. This guarantees that the``rename("x", "x")`` does not remove ``x``.
+If a file already exists by the name ``new``, it is removed. The ``rename()``
+function is atomic. If the ``rename()`` detects an error, no files are
+removed. This guarantees that the ``rename("x", "x")`` does not remove ``x``.
You may not rename dot or dot-dot.
-The routine is implemented in Cygnus newlib using ``link()`` and``unlink()``.
+The routine is implemented in Cygnus newlib using ``link()`` and ``unlink()``.
+
+.. _stat:
stat - Gets information about a file
------------------------------------
@@ -1162,45 +1158,46 @@ stat - Gets information about a file
**CALLING SEQUENCE:**
-.. code:: c
+.. code-block:: c
#include <sys/types.h>
#include <sys/stat.h>
int stat(
- const char \*path,
- struct stat \*buf
+ const char *path,
+ struct stat *buf
);
**STATUS CODES:**
-*EACCES*
- Search permission is denied for a directory in a file's path prefix.
-
-*EBADF*
- Invalid file descriptor.
-
-*ENAMETOOLONG*
- Length of a filename string exceeds PATH_MAX and _POSIX_NO_TRUNC is
- in effect.
-
-*ENOENT*
- A file or directory does not exist.
-
-*ENOTDIR*
- A component of the specified pathname was not a directory when a
- directory was expected.
+.. list-table::
+ :class: rtems-table
+
+ * - ``EACCES``
+ - Search permission is denied for a directory in a file's path prefix.
+ * - ``EBADF``
+ - Invalid file descriptor.
+ * - ``ENAMETOOLONG``
+ - Length of a filename string exceeds ``PATH_MAX`` and ``_POSIX_NO_TRUNC``
+ is in effect.
+ * - ``ENOENT``
+ - A file or directory does not exist.
+ * - ``ENOTDIR``
+ - A component of the specified pathname was not a directory when a directory
+ was expected.
**DESCRIPTION:**
-The ``path`` argument points to a pathname for a file. Read, write, or
-execute permission for the file is not required, but all directories listed
-in ``path`` must be searchable. The ``stat()`` function obtains
-information about the named file and writes it to the area pointed to by``buf``.
+The ``path`` argument points to a pathname for a file. Read, write, or execute
+permission for the file is not required, but all directories listed in ``path``
+must be searchable. The ``stat()`` function obtains information about the named
+file and writes it to the area pointed to by ``buf``.
**NOTES:**
NONE
+.. _fstat:
+
fstat - Gets file status
------------------------
.. index:: fstat
@@ -1208,31 +1205,35 @@ fstat - Gets file status
**CALLING SEQUENCE:**
-.. code:: c
+.. code-block:: c
#include <sys/types.h>
#include <sys/stat.h>
int fstat(
- int fildes,
- struct stat \*buf
+ int fildes,
+ struct stat *buf
);
**STATUS CODES:**
-*EBADF*
- Invalid file descriptor
+.. list-table::
+ :class: rtems-table
+
+ * - ``EBADF``
+ - Invalid file descriptor
**DESCRIPTION:**
-The ``fstat()`` function obtains information about the file
-associated with ``fildes`` and writes it to the area pointed
-to by the ``buf`` argument.
+The ``fstat()`` function obtains information about the file associated with
+``fildes`` and writes it to the area pointed to by the ``buf`` argument.
**NOTES:**
-If the filesystem object referred to by ``fildes`` is a
-link, then the information returned in ``buf`` refers
-to the destination of that link. This is in contrast to``lstat()`` which does not follow the link.
+If the filesystem object referred to by ``fildes`` is a link, then the
+information returned in ``buf`` refers to the destination of that link. This
+is in contrast to ``lstat()`` which does not follow the link.
+
+.. _lstat:
lstat - Gets file status
------------------------
@@ -1241,35 +1242,38 @@ lstat - Gets file status
**CALLING SEQUENCE:**
-.. code:: c
+.. code-block:: c
#include <sys/types.h>
#include <sys/stat.h>
int lstat(
- int fildes,
- struct stat \*buf
+ int fildes,
+ struct stat *buf
);
**STATUS CODES:**
-*EBADF*
- Invalid file descriptor
+.. list-table::
+ :class: rtems-table
+
+ * - ``EBADF``
+ - Invalid file descriptor
**DESCRIPTION:**
-The ``lstat()`` function obtains information about the file
-associated with ``fildes`` and writes it to the area pointed
-to by the ``buf`` argument.
+The ``lstat()`` function obtains information about the file associated with
+``fildes`` and writes it to the area pointed to by the ``buf`` argument.
**NOTES:**
-If the filesystem object referred to by ``fildes`` is a
-link, then the information returned in ``buf`` refers
-to the link itself. This is in contrast to ``fstat()``
-which follows the link.
+If the filesystem object referred to by ``fildes`` is a link, then the
+information returned in ``buf`` refers to the link itself. This is in contrast
+to ``fstat()`` which follows the link.
-The ``lstat()`` routine is defined by BSD 4.3 and SVR4
-and not included in POSIX 1003.1b-1996.
+The ``lstat()`` routine is defined by BSD 4.3 and SVR4 and not included in
+POSIX 1003.1b-1996.
+
+.. _access:
access - Check permissions for a file
-------------------------------------
@@ -1278,52 +1282,53 @@ access - Check permissions for a file
**CALLING SEQUENCE:**
-.. code:: c
+.. code-block:: c
#include <unistd.h>
int access(
- const char \*pathname,
- int mode
+ const char *pathname,
+ int mode
);
**STATUS CODES:**
-*EACCES*
- The requested access would be denied, either to the file itself or
- one of the directories in ``pathname``.
-
-*EFAULT*
- ``pathname`` points outside your accessible address space.
-
-*EINVAL*
- ``Mode`` was incorrectly specified.
-
-*ENAMETOOLONG*
- ``pathname`` is too long.
-
-*ENOENT*
- A directory component in ``pathname`` would have been accessible but
- does not exist or was a dangling symbolic link.
-
-*ENOTDIR*
- A component used as a directory in ``pathname`` is not, in fact,
- a directory.
-
-*ENOMEM*
- Insufficient kernel memory was available.
+.. list-table::
+ :class: rtems-table
+
+ * - ``EACCES``
+ - The requested access would be denied, either to the file itself or one of
+ the directories in ``pathname``.
+ * - ``EFAULT``
+ - ``pathname`` points outside your accessible address space.
+ * - ``EINVAL``
+ - ``Mode`` was incorrectly specified.
+ * - ``ENAMETOOLONG``
+ - ``pathname`` is too long.
+ * - ``ENOENT``
+ - A directory component in ``pathname`` would have been accessible but does
+ not exist or was a dangling symbolic link.
+ * - ``ENOTDIR``
+ - A component used as a directory in ``pathname`` is not, in fact, a
+ directory.
+ * - ``ENOMEM``
+ - Insufficient kernel memory was available.
**DESCRIPTION:**
-``Access`` checks whether the process would be allowed to read, write or
-test for existence of the file (or other file system object) whose name is``pathname``. If ``pathname`` is a symbolic link permissions of the
-file referred by this symbolic link are tested.
+``Access`` checks whether the process would be allowed to read, write or test
+for existence of the file (or other file system object) whose name is
+``pathname``. If ``pathname`` is a symbolic link permissions of the file
+referred by this symbolic link are tested.
-``Mode`` is a mask consisting of one or more of R_OK, W_OK, X_OK and F_OK.
+``Mode`` is a mask consisting of one or more of ``R_OK``, ``W_OK``, ``X_OK``
+and ``F_OK``.
**NOTES:**
NONE
+.. _chmod:
+
chmod - Changes file mode.
--------------------------
.. index:: chmod
@@ -1331,49 +1336,49 @@ chmod - Changes file mode.
**CALLING SEQUENCE:**
-.. code:: c
+.. code-block:: c
#include <sys/types.h>
#include <sys/stat.h>
int chmod(
- const char \*path,
- mode_t mode
+ const char *path,
+ mode_t mode
);
**STATUS CODES:**
-*EACCES*
- Search permission is denied for a directory in a file's path prefix
-
-*ENAMETOOLONG*
- Length of a filename string exceeds PATH_MAX and _POSIX_NO_TRUNC is in
- effect.
-
-*ENOENT*
- A file or directory does not exist.
-
-*ENOTDIR*
- A component of the specified pathname was not a directory when a directory
- was expected.
-
-*EPERM*
- Operation is not permitted. Process does not have the appropriate priviledges
- or permissions to perform the requested operations.
-
-*EROFS*
- Read-only file system.
+.. list-table::
+ :class: rtems-table
+
+ * - ``EACCES``
+ - Search permission is denied for a directory in a file's path prefix
+ * - ``ENAMETOOLONG``
+ - Length of a filename string exceeds ``PATH_MAX`` and ``_POSIX_NO_TRUNC``
+ is in effect.
+ * - ``ENOENT``
+ - A file or directory does not exist.
+ * - ``ENOTDIR``
+ - A component of the specified pathname was not a directory when a directory
+ was expected.
+ * - ``EPERM``
+ - Operation is not permitted. Process does not have the appropriate
+ priviledges or permissions to perform the requested operations.
+ * - ``EROFS``
+ - Read-only file system.
**DESCRIPTION:**
-Set the file permission bits, the set user ID bit, and the set group ID bit
-for the file named by ``path`` to ``mode``. If the effective user ID
-does not match the owner of the file and the calling process does not have
-the appropriate privileges, ``chmod()`` returns -1 and sets ``errno`` to``EPERM``.
+Set the file permission bits, the set user ID bit, and the set group ID bit for
+the file named by ``path`` to ``mode``. If the effective user ID does not match
+the owner of the file and the calling process does not have the appropriate
+privileges, ``chmod()`` returns -1 and sets ``errno`` to ``EPERM``.
**NOTES:**
NONE
+.. _fchmod:
+
fchmod - Changes permissions of a file
--------------------------------------
.. index:: fchmod
@@ -1381,61 +1386,55 @@ fchmod - Changes permissions of a file
**CALLING SEQUENCE:**
-.. code:: c
+.. code-block:: c
#include <sys/types.h>
#include <sys/stat.h>
int fchmod(
- int fildes,
- mode_t mode
+ int fildes,
+ mode_t mode
);
**STATUS CODES:**
-*EACCES*
- Search permission is denied for a directory in a file's path prefix.
-
-*EBADF*
- The descriptor is not valid.
-
-*EFAULT*
- ``path`` points outside your accessible address space.
-
-*EIO*
- A low-level I/o error occurred while modifying the inode.
-
-*ELOOP*
- ``path`` contains a circular reference
-
-*ENAMETOOLONG*
- Length of a filename string exceeds PATH_MAX and _POSIX_NO_TRUNC is
- in effect.
-
-*ENOENT*
- A file or directory does no exist.
-
-*ENOMEM*
- Insufficient kernel memory was avaliable.
-
-*ENOTDIR*
- A component of the specified pathname was not a directory when a
- directory was expected.
-
-*EPERM*
- The effective UID does not match the owner of the file, and is not
- zero
-
-*EROFS*
- Read-only file system
+.. list-table::
+ :class: rtems-table
+
+ * - ``EACCES``
+ - Search permission is denied for a directory in a file's path prefix.
+ * - ``EBADF``
+ - The descriptor is not valid.
+ * - ``EFAULT``
+ - ``path`` points outside your accessible address space.
+ * - ``EIO``
+ - A low-level I/o error occurred while modifying the inode.
+ * - ``ELOOP``
+ - ``path`` contains a circular reference
+ * - ``ENAMETOOLONG``
+ - Length of a filename string exceeds ``PATH_MAX`` and ``_POSIX_NO_TRUNC``
+ is in effect.
+ * - ``ENOENT``
+ - A file or directory does no exist.
+ * - ``ENOMEM``
+ - Insufficient kernel memory was avaliable.
+ * - ``ENOTDIR``
+ - A component of the specified pathname was not a directory when a directory
+ was expected.
+ * - ``EPERM``
+ - The effective UID does not match the owner of the file, and is not zero
+ * - ``EROFS``
+ - Read-only file system
**DESCRIPTION:**
-The mode of the file given by ``path`` or referenced by``filedes`` is changed.
+The mode of the file given by ``path`` or referenced by ``filedes`` is changed.
**NOTES:**
NONE
+.. _getdents:
+
getdents - Get directory entries
--------------------------------
.. index:: getdents
@@ -1443,48 +1442,49 @@ getdents - Get directory entries
**CALLING SEQUENCE:**
-.. code:: c
+.. code-block:: c
#include <unistd.h>
#include <linux/dirent.h>
#include <linux/unistd.h>
long getdents(
- int dd_fd,
- char \*dd_buf,
- int dd_len
+ int dd_fd,
+ char *dd_buf,
+ int dd_len
);
**STATUS CODES:**
-A successful call to ``getdents`` returns th the number of bytes read.
-On end of directory, 0 is returned. When an error occurs, -1 is returned,
-and ``errno`` is set appropriately.
-
-*EBADF*
- Invalid file descriptor ``fd``.
-
-*EFAULT*
- Argument points outside the calling process's address space.
-
-*EINVAL*
- Result buffer is too small.
+A successful call to ``getdents`` returns th the number of bytes read. On end
+of directory, 0 is returned. When an error occurs, -1 is returned, and
+``errno`` is set appropriately.
-*ENOENT*
- No such directory.
+.. list-table::
+ :class: rtems-table
-*ENOTDIR*
- File descriptor does not refer to a directory.
+ * - ``EBADF``
+ - Invalid file descriptor ``fd``.
+ * - ``EFAULT``
+ - Argument points outside the calling process's address space.
+ * - ``EINVAL``
+ - Result buffer is too small.
+ * - ``ENOENT``
+ - No such directory.
+ * - ``ENOTDIR``
+ - File descriptor does not refer to a directory.
**DESCRIPTION:**
-``getdents`` reads several ``dirent`` structures from the directory
-pointed by ``fd`` into the memory area pointed to by ``dirp``. The
-parameter ``count`` is the size of the memory area.
+``getdents`` reads several ``dirent`` structures from the directory pointed by
+``fd`` into the memory area pointed to by ``dirp``. The parameter ``count`` is
+the size of the memory area.
**NOTES:**
NONE
+.. _chown:
+
chown - Changes the owner and/or group of a file.
-------------------------------------------------
.. index:: chown
@@ -1492,59 +1492,59 @@ chown - Changes the owner and/or group of a file.
**CALLING SEQUENCE:**
-.. code:: c
+.. code-block:: c
#include <sys/types.h>
#include <unistd.h>
int chown(
- const char \*path,
- uid_t owner,
- gid_t group
+ const char *path,
+ uid_t owner,
+ gid_t group
);
**STATUS CODES:**
-*EACCES*
- Search permission is denied for a directory in a file's path prefix
-
-*EINVAL*
- Invalid argument
-
-*ENAMETOOLONG*
- Length of a filename string exceeds PATH_MAX and _POSIX_NO_TRUNC is in
- effect.
-
-*ENOENT*
- A file or directory does not exist.
-
-*ENOTDIR*
- A component of the specified pathname was not a directory when a directory
- was expected.
-
-*EPERM*
- Operation is not permitted. Process does not have the appropriate priviledges
- or permissions to perform the requested operations.
-
-*EROFS*
- Read-only file system.
+.. list-table::
+ :class: rtems-table
+
+ * - ``EACCES``
+ - Search permission is denied for a directory in a file's path prefix
+ * - ``EINVAL``
+ - Invalid argument
+ * - ``ENAMETOOLONG``
+ - Length of a filename string exceeds ``PATH_MAX`` and ``_POSIX_NO_TRUNC``
+ is in effect.
+ * - ``ENOENT``
+ - A file or directory does not exist.
+ * - ``ENOTDIR``
+ - A component of the specified pathname was not a directory when a directory
+ was expected.
+ * - ``EPERM``
+ - Operation is not permitted. Process does not have the appropriate
+ priviledges or permissions to perform the requested operations.
+ * - ``EROFS``
+ - Read-only file system.
**DESCRIPTION:**
-The user ID and group ID of the file named by ``path`` are set to``owner`` and ``path``, respectively.
+The user ID and group ID of the file named by ``path`` are set to ``owner`` and
+``path``, respectively.
-For regular files, the set group ID (S_ISGID) and set user ID (S_ISUID)
+For regular files, the set group ID (``S_ISGID``) and set user ID (``S_ISUID``)
bits are cleared.
Some systems consider it a security violation to allow the owner of a file to
-be changed, If users are billed for disk space usage, loaning a file to
-another user could result in incorrect billing. The ``chown()`` function
-may be restricted to privileged users for some or all files. The group ID can
-still be changed to one of the supplementary group IDs.
+be changed, If users are billed for disk space usage, loaning a file to another
+user could result in incorrect billing. The ``chown()`` function may be
+restricted to privileged users for some or all files. The group ID can still be
+changed to one of the supplementary group IDs.
**NOTES:**
-This function may be restricted for some file. The ``pathconf`` function
-can be used to test the ``_PC_CHOWN_RESTRICTED`` flag.
+This function may be restricted for some file. The ``pathconf`` function can be
+used to test the ``_PC_CHOWN_RESTRICTED`` flag.
+
+.. _utime:
utime - Change access and/or modification times of an inode
-----------------------------------------------------------
@@ -1553,33 +1553,37 @@ utime - Change access and/or modification times of an inode
**CALLING SEQUENCE:**
-.. code:: c
+.. code-block:: c
#include <sys/types.h>
int utime(
- const char \*filename,
- struct utimbuf \*buf
+ const char *filename,
+ struct utimbuf *buf
);
**STATUS CODES:**
-*EACCES*
- Permission to write the file is denied
+.. list-table::
+ :class: rtems-table
-*ENOENT*
- ``Filename`` does not exist
+ * - ``EACCES``
+ - Permission to write the file is denied
+ * - ``ENOENT``
+ - ``Filename`` does not exist
**DESCRIPTION:**
-``Utime`` changes the access and modification times of the inode
-specified by ``filename`` to the ``actime`` and ``modtime``
-fields of ``buf`` respectively. If ``buf`` is NULL, then the
-access and modification times of the file are set to the current time.
+``Utime`` changes the access and modification times of the inode specified by
+``filename`` to the ``actime`` and ``modtime`` fields of ``buf``
+respectively. If ``buf`` is ``NULL``, then the access and modification times of the
+file are set to the current time.
**NOTES:**
NONE
+.. _ftruncate:
+
ftruncate - truncate a file to a specified length
-------------------------------------------------
.. index:: ftruncate
@@ -1587,67 +1591,60 @@ ftruncate - truncate a file to a specified length
**CALLING SEQUENCE:**
-.. code:: c
+.. code-block:: c
#include <unistd.h>
int ftrunctate(
- int fd,
- size_t length
+ int fd,
+ size_t length
);
**STATUS CODES:**
-*ENOTDIR*
- A component of the path prefix is not a directory.
-
-*EINVAL*
- The pathname contains a character with the high-order bit set.
-
-*ENAMETOOLONG*
- A component of a pathname exceeded 255 characters, or an entire
- path name exceeded 1023 characters.
-
-*ENOENT*
- The named file does not exist.
-
-*EACCES*
- The named file is not writable by the user.
-
-*EACCES*
- Search permission is denied for a component of the path prefix.
-
-*ELOOP*
- Too many symbolic links were encountered in translating the
- pathname
-
-*EISDIR*
- The named file is a directory.
-
-*EROFS*
- The named file resides on a read-only file system
-
-*ETXTBSY*
- The file is a pure procedure (shared text) file that is being
- executed
-
-*EIO*
- An I/O error occurred updating the inode.
-
-*EFAULT*
- ``Path`` points outside the process's allocated address space.
-
-*EBADF*
- The ``fd`` is not a valid descriptor.
+.. list-table::
+ :class: rtems-table
+
+ * - ``ENOTDIR``
+ - A component of the path prefix is not a directory.
+ * - ``EINVAL``
+ - The pathname contains a character with the high-order bit set.
+ * - ``ENAMETOOLONG``
+ - The length of the specified pathname exceeds ``PATH_MAX`` bytes, or the length
+ of a component of the pathname exceeds ``NAME_MAX`` bytes.
+ * - ``ENOENT``
+ - The named file does not exist.
+ * - ``EACCES``
+ - The named file is not writable by the user.
+ * - ``EACCES``
+ - Search permission is denied for a component of the path prefix.
+ * - ``ELOOP``
+ - Too many symbolic links were encountered in translating the pathname
+ * - ``EISDIR``
+ - The named file is a directory.
+ * - ``EROFS``
+ - The named file resides on a read-only file system
+ * - ``ETXTBSY``
+ - The file is a pure procedure (shared text) file that is being executed
+ * - ``EIO``
+ - An I/O error occurred updating the inode.
+ * - ``EFAULT``
+ - ``Path`` points outside the process's allocated address space.
+ * - ``EBADF``
+ - The ``fd`` is not a valid descriptor.
**DESCRIPTION:**
-``truncate()`` causes the file named by ``path`` or referenced by``fd`` to be truncated to at most ``length`` bytes in size. If the
-file previously was larger than this size, the extra data is lost. With``ftruncate()``, the file must be open for writing.
+``truncate()`` causes the file named by ``path`` or referenced by ``fd`` to be
+truncated to at most ``length`` bytes in size. If the file previously was
+larger than this size, the extra data is lost. With ``ftruncate()``, the file
+must be open for writing.
**NOTES:**
NONE
+.. _truncate:
+
truncate - truncate a file to a specified length
------------------------------------------------
.. index:: truncate
@@ -1655,67 +1652,60 @@ truncate - truncate a file to a specified length
**CALLING SEQUENCE:**
-.. code:: c
+.. code-block:: c
#include <unistd.h>
int trunctate(
- const char \*path,
- size_t length
+ const char *path,
+ size_t length
);
**STATUS CODES:**
-*ENOTDIR*
- A component of the path prefix is not a directory.
-
-*EINVAL*
- The pathname contains a character with the high-order bit set.
-
-*ENAMETOOLONG*
- A component of a pathname exceeded 255 characters, or an entire
- path name exceeded 1023 characters.
-
-*ENOENT*
- The named file does not exist.
-
-*EACCES*
- The named file is not writable by the user.
-
-*EACCES*
- Search permission is denied for a component of the path prefix.
-
-*ELOOP*
- Too many symbolic links were encountered in translating the
- pathname
-
-*EISDIR*
- The named file is a directory.
-
-*EROFS*
- The named file resides on a read-only file system
-
-*ETXTBSY*
- The file is a pure procedure (shared text) file that is being
- executed
-
-*EIO*
- An I/O error occurred updating the inode.
-
-*EFAULT*
- ``Path`` points outside the process's allocated address space.
-
-*EBADF*
- The ``fd`` is not a valid descriptor.
+.. list-table::
+ :class: rtems-table
+
+ * - ``ENOTDIR``
+ - A component of the path prefix is not a directory.
+ * - ``EINVAL``
+ - The pathname contains a character with the high-order bit set.
+ * - ``ENAMETOOLONG``
+ - The length of the specified pathname exceeds ``PATH_MAX`` bytes, or the length
+ of a component of the pathname exceeds ``NAME_MAX`` bytes.
+ * - ``ENOENT``
+ - The named file does not exist.
+ * - ``EACCES``
+ - The named file is not writable by the user.
+ * - ``EACCES``
+ - Search permission is denied for a component of the path prefix.
+ * - ``ELOOP``
+ - Too many symbolic links were encountered in translating the pathname
+ * - ``EISDIR``
+ - The named file is a directory.
+ * - ``EROFS``
+ - The named file resides on a read-only file system
+ * - ``ETXTBSY``
+ - The file is a pure procedure (shared text) file that is being executed
+ * - ``EIO``
+ - An I/O error occurred updating the inode.
+ * - ``EFAULT``
+ - ``Path`` points outside the process's allocated address space.
+ * - ``EBADF``
+ - The ``fd`` is not a valid descriptor.
**DESCRIPTION:**
-``truncate()`` causes the file named by ``path`` or referenced by``fd`` to be truncated to at most ``length`` bytes in size. If the
-file previously was larger than this size, the extra data is lost. With``ftruncate()``, the file must be open for writing.
+``truncate()`` causes the file named by ``path`` or referenced by``fd`` to be
+truncated to at most ``length`` bytes in size. If the file previously was
+larger than this size, the extra data is lost. With ``ftruncate()``, the file
+must be open for writing.
**NOTES:**
NONE
+.. _pathconf:
+
pathconf - Gets configuration values for files
----------------------------------------------
.. index:: pathconf
@@ -1723,71 +1713,77 @@ pathconf - Gets configuration values for files
**CALLING SEQUENCE:**
-.. code:: c
+.. code-block:: c
#include <unistd.h>
int pathconf(
- const char \*path,
- int name
+ const char *path,
+ int name
);
**STATUS CODES:**
-*EINVAL*
- Invalid argument
-
-*EACCES*
- Permission to write the file is denied
-
-*ENAMETOOLONG*
- Length of a filename string exceeds PATH_MAX and _POSIX_NO_TRUNC
- is in effect.
-
-*ENOENT*
- A file or directory does not exist
-
-*ENOTDIR*
- A component of the specified ``path`` was not a directory whan a
- directory was expected.
+.. list-table::
+ :class: rtems-table
+
+ * - ``EINVAL``
+ - Invalid argument
+ * - ``EACCES``
+ - Permission to write the file is denied
+ * - ``ENAMETOOLONG``
+ - Length of a filename string exceeds ``PATH_MAX`` and ``_POSIX_NO_TRUNC``
+ is in effect.
+ * - ``ENOENT``
+ - A file or directory does not exist
+ * - ``ENOTDIR``
+ - A component of the specified ``path`` was not a directory whan a directory
+ was expected.
**DESCRIPTION:**
-``pathconf()`` gets a value for the configuration option ``name``
-for the open file descriptor ``filedes``.
+``pathconf()`` gets a value for the configuration option ``name`` for the open
+file descriptor ``filedes``.
The possible values for ``name`` are:
-*_PC_LINK_MAX*
- returns the maximum number of links to the file. If ``filedes`` or``path`` refer to a directory, then the value applies to the whole
- directory. The corresponding macro is ``_POSIX_LINK_MAX``.
-
-*_PC_MAX_CANON*
- returns the maximum length of a formatted input line, where ``filedes``
- or ``path`` must refer to a terminal. The corresponding macro is``_POSIX_MAX_CANON``.
-
-*_PC_MAX_INPUT*
- returns the maximum length of an input line, where ``filedes`` or``path`` must refer to a terminal. The corresponding macro is``_POSIX_MAX_INPUT``.
-
-*_PC_NAME_MAX*
- returns the maximum length of a filename in the directory ``path`` or``filedes``. The process is allowed to create. The corresponding macro
- is ``_POSIX_NAME_MAX``.
-
-*_PC_PATH_MAX*
- returns the maximum length of a relative pathname when ``path`` or``filedes`` is the current working directory. The corresponding macro
- is ``_POSIX_PATH_MAX``.
-
-*_PC_PIPE_BUF*
- returns the size of the pipe buffer, where ``filedes`` must refer to a
- pipe or FIFO and ``path`` must refer to a FIFO. The corresponding macro
- is ``_POSIX_PIPE_BUF``.
-
-*_PC_CHOWN_RESTRICTED*
- returns nonzero if the chown(2) call may not be used on this file. If``filedes`` or ``path`` refer to a directory, then this applies to all
- files in that directory. The corresponding macro is``_POSIX_CHOWN_RESTRICTED``.
+.. list-table::
+ :class: rtems-table
+
+ * - ``_PC_LINK_MAX``
+ - Returns the maximum number of links to the file. If ``filedes`` or``path``
+ refer to a directory, then the value applies to the whole directory. The
+ corresponding macro is ``_POSIX_LINK_MAX``.
+ * - ``_PC_MAX_CANON``
+ - Returns the maximum length of a formatted input line, where ``filedes`` or
+ ``path`` must refer to a terminal. The corresponding macro is
+ ``_POSIX_MAX_CANON``.
+ * - ``_PC_MAX_INPUT``
+ - Returns the maximum length of an input line, where ``filedes`` or ``path``
+ must refer to a terminal. The corresponding macro is``_POSIX_MAX_INPUT``.
+ * - ``_PC_NAME_MAX``
+ - Returns the maximum length of a filename in the directory ``path`` or
+ ``filedes``. The process is allowed to create. The corresponding macro is
+ ``_POSIX_NAME_MAX``.
+ * - ``_PC_PATH_MAX``
+ - returns the maximum length of a relative pathname when ``path``
+ or``filedes`` is the current working directory. The corresponding macro is
+ ``_POSIX_PATH_MAX``.
+ * - ``_PC_PIPE_BUF``
+ - returns the size of the pipe buffer, where ``filedes`` must refer to a
+ pipe or FIFO and ``path`` must refer to a FIFO. The corresponding macro is
+ ``_POSIX_PIPE_BUF``.
+ * - ``_PC_CHOWN_RESTRICTED``
+ - Returns nonzero if the ``chown(2)`` call may not be used on this
+ file. If``filedes`` or ``path`` refer to a directory, then this applies to
+ all files in that directory. The corresponding macro is
+ ``_POSIX_CHOWN_RESTRICTED``.
**NOTES:**
-Files with name lengths longer than the value returned for ``name`` equal``_PC_NAME_MAX`` may exist in the given directory.
+Files with name lengths longer than the value returned for ``name`` equal
+``_PC_NAME_MAX`` may exist in the given directory.
+
+.. _fpathconf:
fpathconf - Gets configuration values for files
-----------------------------------------------
@@ -1796,72 +1792,77 @@ fpathconf - Gets configuration values for files
**CALLING SEQUENCE:**
-.. code:: c
+.. code-block:: c
#include <unistd.h>
int fpathconf(
- int filedes,
- int name
+ int filedes,
+ int name
);
**STATUS CODES:**
-*EINVAL*
- Invalid argument
-
-*EACCES*
- Permission to write the file is denied
-
-*ENAMETOOLONG*
- Length of a filename string exceeds PATH_MAX and _POSIX_NO_TRUNC
- is in effect.
-
-*ENOENT*
- A file or directory does not exist
-
-*ENOTDIR*
- A component of the specified ``path`` was not a directory whan a
- directory was expected.
+.. list-table::
+ :class: rtems-table
+
+ * - ``EINVAL``
+ - Invalid argument
+ * - ``EACCES``
+ - Permission to write the file is denied
+ * - ``ENAMETOOLONG``
+ - Length of a filename string exceeds ``PATH_MAX`` and ``_POSIX_NO_TRUNC``
+ is in effect.
+ * - ``ENOENT``
+ - A file or directory does not exist
+ * - ``ENOTDIR``
+ - A component of the specified ``path`` was not a directory whan a directory
+ was expected.
**DESCRIPTION:**
-``pathconf()`` gets a value for the configuration option ``name``
-for the open file descriptor ``filedes``.
+``pathconf()`` gets a value for the configuration option ``name`` for the open
+file descriptor ``filedes``.
The possible values for name are:
-*_PC_LINK_MAX*
- returns the maximum number of links to the file. If ``filedes`` or``path`` refer to a directory, then the value applies to the whole
- directory. The corresponding macro is _POSIX_LINK_MAX.
-
-*_PC_MAX_CANON*
- returns the maximum length of a formatted input line, where ``filedes``
- or ``path`` must refer to a terminal. The corresponding macro is``_POSIX_MAX_CANON``.
-
-*_PC_MAX_INPUT*
- returns the maximum length of an input line, where ``filedes`` or``path`` must refer to a terminal. The corresponding macro is``_POSIX_MAX_INPUT``.
-
-*_PC_NAME_MAX*
- returns the maximum length of a filename in the directory ``path`` or``filedes``. The process is allowed to create. The corresponding macro
- is ``_POSIX_NAME_MAX``.
-
-*_PC_PATH_MAX*
- returns the maximum length of a relative pathname when ``path`` or``filedes`` is the current working directory. The corresponding macro
- is ``_POSIX_PATH_MAX``.
-
-*_PC_PIPE_BUF*
- returns the size of the pipe buffer, where ``filedes`` must refer to a
- pipe or FIFO and ``path`` must refer to a FIFO. The corresponding macro
- is ``_POSIX_PIPE_BUF``.
-
-*_PC_CHOWN_RESTRICTED*
- returns nonzero if the ``chown()`` call may not be used on this file. If``filedes`` or ``path`` refer to a directory, then this applies to all
- files in that directory. The corresponding macro is``_POSIX_CHOWN_RESTRICTED``.
+.. list-table::
+ :class: rtems-table
+
+ * - ``_PC_LINK_MAX``
+ - Returns the maximum number of links to the file. If ``filedes`` or
+ ``path`` refer to a directory, then the value applies to the whole
+ directory. The corresponding macro is ``_POSIX_LINK_MAX``.
+ * - ``_PC_MAX_CANON``
+ - returns the maximum length of a formatted input line, where ``filedes`` or
+ ``path`` must refer to a terminal. The corresponding macro is
+ ``_POSIX_MAX_CANON``.
+ * - ``_PC_MAX_INPUT``
+ - Returns the maximum length of an input line, where ``filedes`` or ``path``
+ must refer to a terminal. The corresponding macro is ``_POSIX_MAX_INPUT``.
+ * - ``_PC_NAME_MAX``
+ - Returns the maximum length of a filename in the directory ``path`` or
+ ``filedes``. The process is allowed to create. The corresponding macro is
+ ``_POSIX_NAME_MAX``.
+ * - ``_PC_PATH_MAX``
+ - Returns the maximum length of a relative pathname when ``path`` or
+ ``filedes`` is the current working directory. The corresponding macro is
+ ``_POSIX_PATH_MAX``.
+ * - ``_PC_PIPE_BUF``
+ - Returns the size of the pipe buffer, where ``filedes`` must refer to a
+ pipe or FIFO and ``path`` must refer to a FIFO. The corresponding macro is
+ ``_POSIX_PIPE_BUF``.
+ * - ``_PC_CHOWN_RESTRICTED``
+ - Returns nonzero if the ``chown()`` call may not be used on this file. If
+ ``filedes`` or ``path`` refer to a directory, then this applies to all
+ files in that directory. The corresponding macro is
+ ``_POSIX_CHOWN_RESTRICTED``.
**NOTES:**
NONE
+.. _mknod:
+
mknod - create a directory
--------------------------
.. index:: mknod
@@ -1869,16 +1870,16 @@ mknod - create a directory
**CALLING SEQUENCE:**
-.. code:: c
+.. code-block:: c
#include <unistd.h>
#include <fcntl.h>
#include <sys/types.h>
#include <sys/stat.h>
long mknod(
- const char \*pathname,
- mode_t mode,
- dev_t dev
+ const char *pathname,
+ mode_t mode,
+ dev_t dev
);
**STATUS CODES:**
@@ -1886,28 +1887,26 @@ mknod - create a directory
``mknod`` returns zero on success, or -1 if an error occurred (in which case,
errno is set appropriately).
-*ENAMETOOLONG*
- ``pathname`` was too long.
-
-*ENOENT*
- A directory component in ``pathname`` does not exist or is a dangling symbolic
- link.
-
-*ENOTDIR*
- A component used in the directory ``pathname`` is not, in fact, a directory.
-
-*ENOMEM*
- Insufficient kernel memory was available
-
-*EROFS*
- ``pathname`` refers to a file on a read-only filesystem.
-
-*ELOOP*
- ``pathname`` contains a reference to a circular symbolic link, ie a symbolic
- link whose expansion contains a reference to itself.
-
-*ENOSPC*
- The device containing ``pathname`` has no room for the new node.
+.. list-table::
+ :class: rtems-table
+
+ * - ``ENAMETOOLONG``
+ - ``pathname`` was too long.
+ * - ``ENOENT``
+ - A directory component in ``pathname`` does not exist or is a dangling
+ symbolic link.
+ * - ``ENOTDIR``
+ - A component used in the directory ``pathname`` is not, in fact, a
+ directory.
+ * - ``ENOMEM``
+ - Insufficient kernel memory was available
+ * - ``EROFS``
+ - ``pathname`` refers to a file on a read-only filesystem.
+ * - ``ELOOP``
+ - ``pathname`` contains a reference to a circular symbolic link, ie a
+ symbolic link whose expansion contains a reference to itself.
+ * - ``ENOSPC``
+ - The device containing ``pathname`` has no room for the new node.
**DESCRIPTION:**
@@ -1922,26 +1921,21 @@ below and the permissions for the new node.
The permissions are modified by the process's ``umask`` in the usual way: the
permissions of the created node are ``(mode & ~umask)``.
-The file type should be one of ``S_IFREG``, ``S_IFCHR``, ``S_IFBLK`` and``S_IFIFO`` to specify a normal file (which will be created empty), character
-special file, block special file or FIFO (named pipe), respectively, or zero, which
-will create a normal file.
+The file type should be one of ``S_IFREG``, ``S_IFCHR``, ``S_IFBLK`` and
+``S_IFIFO`` to specify a normal file (which will be created empty), character
+special file, block special file or FIFO (named pipe), respectively, or zero,
+which will create a normal file.
If the file type is ``S_IFCHR`` or ``S_IFBLK`` then ``dev`` specifies the major
-and minor numbers of the newly created device special file; otherwise it is ignored.
+and minor numbers of the newly created device special file; otherwise it is
+ignored.
-The newly created node will be owned by the effective uid of the process. If the
-directory containing the node has the set group id bit set, or if the filesystem
-is mounted with BSD group semantics, the new node will inherit the group ownership
-from its parent directory; otherwise it will be owned by the effective gid of the
-process.
+The newly created node will be owned by the effective uid of the process. If
+the directory containing the node has the set group id bit set, or if the
+filesystem is mounted with BSD group semantics, the new node will inherit the
+group ownership from its parent directory; otherwise it will be owned by the
+effective gid of the process.
**NOTES:**
NONE
-
-.. COMMENT: COPYRIGHT (c) 1988-2002.
-
-.. COMMENT: On-Line Applications Research Corporation (OAR).
-
-.. COMMENT: All rights reserved.
-
diff --git a/posix_users/index.rst b/posix_users/index.rst
index c75c6f7..8a59f08 100644
--- a/posix_users/index.rst
+++ b/posix_users/index.rst
@@ -2,45 +2,41 @@
RTEMS POSIX API User's Guide
============================
-COPYRIGHT (c) 1988 - 2015.
-
-On-Line Applications Research Corporation (OAR).
-
-The authors have used their best efforts in preparing
-this material. These efforts include the development, research,
-and testing of the theories and programs to determine their
-effectiveness. No warranty of any kind, expressed or implied,
-with regard to the software or the material contained in this
-document is provided. No liability arising out of the
-application or use of any product described in this document is
-assumed. The authors reserve the right to revise this material
-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
-inquiries concerning RTEMS, its related support components, or its
-documentation should be directed to the Community Project hosted athttp://www.rtems.org.
-
-Any inquiries for commercial services including training, support, custom
-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
-
+RTEMS POSIX API User's Guide
+----------------------------
+
+ | COPYRIGHT (c) 1988 - 2015.
+ | On-Line Applications Research Corporation (OAR).
+
+The authors have used their best efforts in preparing this material. These
+efforts include the development, research, and testing of the theories and
+programs to determine their effectiveness. No warranty of any kind, expressed
+or implied, with regard to the software or the material contained in this
+document is provided. No liability arising out of the application or use of
+any product described in this document is assumed. The authors reserve the
+right to revise this material 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 inquiries concerning
+RTEMS, its related support components, or its documentation should be directed
+to the Community Project hosted at http://www.rtems.org/.
+
+.. topic:: RTEMS Online Resources
+
+ ================ =============================
+ 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`
diff --git a/posix_users/input_and_output.rst b/posix_users/input_and_output.rst
index 4ecd4bc..638d000 100644
--- a/posix_users/input_and_output.rst
+++ b/posix_users/input_and_output.rst
@@ -1,3 +1,7 @@
+.. COMMENT: COPYRIGHT (c) 1988-2002.
+.. COMMENT: On-Line Applications Research Corporation (OAR).
+.. COMMENT: All rights reserved.
+
Input and Output Primitives Manager
###################################
@@ -8,51 +12,51 @@ The input and output primitives manager is ...
The directives provided by the input and output primitives manager are:
-- ``pipe`` - Create an Inter-Process Channel
+- pipe_ - Create an Inter-Process Channel
-- ``dup`` - Duplicates an open file descriptor
+- dup_ - Duplicates an open file descriptor
-- ``dup2`` - Duplicates an open file descriptor
+- dup2_ - Duplicates an open file descriptor
-- ``close`` - Closes a file
+- close_ - Closes a file
-- ``read`` - Reads from a file
+- read_ - Reads from a file
-- ``write`` - Writes to a file
+- write_ - Writes to a file
-- ``fcntl`` - Manipulates an open file descriptor
+- fcntl_ - Manipulates an open file descriptor
-- ``lseek`` - Reposition read/write file offset
+- lseek_ - Reposition read/write file offset
-- ``fsync`` - Synchronize file complete in-core state with that on disk
+- fsync_ - Synchronize file complete in-core state with that on disk
-- ``fdatasync`` - Synchronize file in-core data with that on disk
+- fdatasync_ - Synchronize file in-core data with that on disk
-- ``sync`` - Schedule file system updates
+- sync_ - Schedule file system updates
-- ``mount`` - Mount a file system
+- mount_ - Mount a file system
-- ``unmount`` - Unmount file systems
+- unmount_ - Unmount file systems
-- ``readv`` - Vectored read from a file
+- readv_ - Vectored read from a file
-- ``writev`` - Vectored write to a file
+- writev_ - Vectored write to a file
-- ``aio_read`` - Asynchronous Read
+- aio_read_ - Asynchronous Read
-- ``aio_write`` - Asynchronous Write
+- aio_write_ - Asynchronous Write
-- ``lio_listio`` - List Directed I/O
+- lio_listio_ - List Directed I/O
-- ``aio_error`` - Retrieve Error Status of Asynchronous I/O Operation
+- aio_error_ - Retrieve Error Status of Asynchronous I/O Operation
-- ``aio_return`` - Retrieve Return Status Asynchronous I/O Operation
+- aio_return_ - Retrieve Return Status Asynchronous I/O Operation
-- ``aio_cancel`` - Cancel Asynchronous I/O Request
+- aio_cancel_ - Cancel Asynchronous I/O Request
-- ``aio_suspend`` - Wait for Asynchronous I/O Request
+- aio_suspend_ - Wait for Asynchronous I/O Request
-- ``aio_fsync`` - Asynchronous File Synchronization
+- aio_fsync_ - Asynchronous File Synchronization
Background
==========
@@ -67,10 +71,11 @@ There is currently no text in this section.
Directives
==========
-This section details the input and output primitives manager's directives.
-A subsection is dedicated to each of this manager's directives
-and describes the calling sequence, related constants, usage,
-and status codes.
+This section details the input and output primitives manager's directives. A
+subsection is dedicated to each of this manager's directives and describes the
+calling sequence, related constants, usage, and status codes.
+
+.. _pipe:
pipe - Create an Inter-Process Channel
--------------------------------------
@@ -79,15 +84,18 @@ pipe - Create an Inter-Process Channel
**CALLING SEQUENCE:**
-.. code:: c
+.. code-block:: c
int pipe(
);
**STATUS CODES:**
-*E*
- The
+.. list-table::
+ :class: rtems-table
+
+ * - ``E``
+ - The
**DESCRIPTION:**
@@ -96,6 +104,8 @@ pipe - Create an Inter-Process Channel
This routine is not currently supported by RTEMS but could be
in a future version.
+.. _dup:
+
dup - Duplicates an open file descriptor
----------------------------------------
.. index:: dup
@@ -103,35 +113,38 @@ dup - Duplicates an open file descriptor
**CALLING SEQUENCE:**
-.. code:: c
+.. code-block:: c
#include <unistd.h>
int dup(
- int fildes
+ int fildes
);
**STATUS CODES:**
-*EBADF*
- Invalid file descriptor.
-
-*EINTR*
- Function was interrupted by a signal.
+.. list-table::
+ :class: rtems-table
-*EMFILE*
- The process already has the maximum number of file descriptors open
- and tried to open a new one.
+ * - ``EBADF``
+ - Invalid file descriptor.
+ * - ``EINTR``
+ - Function was interrupted by a signal.
+ * - ``EMFILE``
+ - The process already has the maximum number of file descriptors open and
+ tried to open a new one.
**DESCRIPTION:**
The ``dup`` function returns the lowest numbered available file
-descriptor. This new desciptor refers to the same open file as the
-original descriptor and shares any locks.
+descriptor. This new desciptor refers to the same open file as the original
+descriptor and shares any locks.
**NOTES:**
NONE
+.. _dup2:
+
dup2 - Duplicates an open file descriptor
-----------------------------------------
.. index:: dup2
@@ -139,37 +152,42 @@ dup2 - Duplicates an open file descriptor
**CALLING SEQUENCE:**
-.. code:: c
+.. code-block:: c
#include <unistd.h>
int dup2(
- int fildes,
- int fildes2
+ int fildes,
+ int fildes2
);
**STATUS CODES:**
-*EBADF*
- Invalid file descriptor.
+.. list-table::
+ :class: rtems-table
-*EINTR*
- Function was interrupted by a signal.
-
-*EMFILE*
- The process already has the maximum number of file descriptors open
- and tried to open a new one.
+ * - ``EBADF``
+ - Invalid file descriptor.
+ * - ``EINTR``
+ - Function was interrupted by a signal.
+ * - ``EMFILE``
+ - The process already has the maximum number of file descriptors open and
+ tried to open a new one.
**DESCRIPTION:**
``dup2`` creates a copy of the file descriptor ``oldfd``.
The old and new descriptors may be used interchangeably. They share locks, file
-position pointers and flags; for example, if the file position is modified by using``lseek`` on one of the descriptors, the position is also changed for the other.
+position pointers and flags; for example, if the file position is modified by
+using ``lseek`` on one of the descriptors, the position is also changed for the
+other.
**NOTES:**
NONE
+.. _close:
+
close - Closes a file
---------------------
.. index:: close
@@ -177,30 +195,35 @@ close - Closes a file
**CALLING SEQUENCE:**
-.. code:: c
+.. code-block:: c
#include <unistd.h>
int close(
- int fildes
+ int fildes
);
**STATUS CODES:**
-*EBADF*
- Invalid file descriptor
+.. list-table::
+ :class: rtems-table
-*EINTR*
- Function was interrupted by a signal.
+ * - ``EBADF``
+ - Invalid file descriptor
+ * - ``EINTR``
+ - Function was interrupted by a signal.
**DESCRIPTION:**
-The ``close()`` function deallocates the file descriptor named by``fildes`` and makes it available for reuse. All outstanding
-record locks owned by this process for the file are unlocked.
+The ``close()`` function deallocates the file descriptor named by ``fildes``
+and makes it available for reuse. All outstanding record locks owned by this
+process for the file are unlocked.
**NOTES:**
-A signal can interrupt the ``close()`` function. In that case,``close()`` returns -1 with ``errno`` set to EINTR. The file
-may or may not be closed.
+A signal can interrupt the ``close()`` function. In that case, ``close()``
+returns -1 with ``errno`` set to EINTR. The file may or may not be closed.
+
+.. _read:
read - Reads from a file
------------------------
@@ -209,43 +232,41 @@ read - Reads from a file
**CALLING SEQUENCE:**
-.. code:: c
+.. code-block:: c
#include <unistd.h>
int read(
- int fildes,
- void \*buf,
- unsigned int nbyte
+ int fildes,
+ void *buf,
+ unsigned int nbyte
);
**STATUS CODES:**
-On error, this routine returns -1 and sets ``errno`` to one of
-the following:
-
-*EAGAIN*
- The O_NONBLOCK flag is set for a file descriptor and the process
- would be delayed in the I/O operation.
-
-*EBADF*
- Invalid file descriptor
-
-*EINTR*
- Function was interrupted by a signal.
+On error, this routine returns -1 and sets ``errno`` to one of the following:
-*EIO*
- Input or output error
+.. list-table::
+ :class: rtems-table
-*EINVAL*
- Bad buffer pointer
+ * - ``EAGAIN``
+ - The O_NONBLOCK flag is set for a file descriptor and the process would be
+ delayed in the I/O operation.
+ * - ``EBADF``
+ - Invalid file descriptor
+ * - ``EINTR``
+ - Function was interrupted by a signal.
+ * - ``EIO``
+ - Input or output error
+ * - ``EINVAL``
+ - Bad buffer pointer
**DESCRIPTION:**
-The ``read()`` function reads ``nbyte`` bytes from the file
-associated with ``fildes`` into the buffer pointed to by ``buf``.
+The ``read()`` function reads ``nbyte`` bytes from the file associated with
+``fildes`` into the buffer pointed to by ``buf``.
-The ``read()`` function returns the number of bytes actually read
-and placed in the buffer. This will be less than ``nbyte`` if:
+The ``read()`` function returns the number of bytes actually read and placed in
+the buffer. This will be less than ``nbyte`` if:
- The number of bytes left in the file is less than ``nbyte``.
@@ -256,21 +277,21 @@ and placed in the buffer. This will be less than ``nbyte`` if:
When attempting to read from any empty pipe or FIFO:
-- If no process has the pipe open for writing, zero is returned to
- indicate end-of-file.
+- If no process has the pipe open for writing, zero is returned to indicate
+ end-of-file.
- If some process has the pipe open for writing and O_NONBLOCK is set,
-1 is returned and ``errno`` is set to EAGAIN.
-- If some process has the pipe open for writing and O_NONBLOCK is clear,``read()`` waits for some data to be written or the pipe to be closed.
+- If some process has the pipe open for writing and O_NONBLOCK is clear,
+ ``read()`` waits for some data to be written or the pipe to be closed.
-When attempting to read from a file other than a pipe or FIFO and no data
-is available.
+When attempting to read from a file other than a pipe or FIFO and no data is
+available.
- If O_NONBLOCK is set, -1 is returned and ``errno`` is set to EAGAIN.
-- If O_NONBLOCK is clear, ``read()`` waits for some data to become
- available.
+- If O_NONBLOCK is clear, ``read()`` waits for some data to become available.
- The O_NONBLOCK flag is ignored if data is available.
@@ -278,6 +299,8 @@ is available.
NONE
+.. _write:
+
write - Writes to a file
------------------------
.. index:: write
@@ -285,60 +308,57 @@ write - Writes to a file
**CALLING SEQUENCE:**
-.. code:: c
+.. code-block:: c
#include <unistd.h>
int write(
int fildes,
- const void \*buf,
- unsigned int nbytes
+ const void *buf,
+ unsigned int nbytes
);
**STATUS CODES:**
-*EAGAIN*
- The O_NONBLOCK flag is set for a file descriptor and the process
- would be delayed in the I/O operation.
-
-*EBADF*
- Invalid file descriptor
-
-*EFBIG*
- An attempt was made to write to a file that exceeds the maximum file
- size
-
-*EINTR*
- The function was interrupted by a signal.
-
-*EIO*
- Input or output error.
-
-*ENOSPC*
- No space left on disk.
-
-*EPIPE*
- Attempt to write to a pope or FIFO with no reader.
-
-*EINVAL*
- Bad buffer pointer
+.. list-table::
+ :class: rtems-table
+
+ * - ``EAGAIN``
+ - The O_NONBLOCK flag is set for a file descriptor and the process would be
+ delayed in the I/O operation.
+ * - ``EBADF``
+ - Invalid file descriptor
+ * - ``EFBIG``
+ - An attempt was made to write to a file that exceeds the maximum file size
+ * - ``EINTR``
+ - The function was interrupted by a signal.
+ * - ``EIO``
+ - Input or output error.
+ * - ``ENOSPC``
+ - No space left on disk.
+ * - ``EPIPE``
+ - Attempt to write to a pope or FIFO with no reader.
+ * - ``EINVAL``
+ - Bad buffer pointer
**DESCRIPTION:**
-The ``write()`` function writes ``nbyte`` from the array pointed
-to by ``buf`` into the file associated with ``fildes``.
+The ``write()`` function writes ``nbyte`` from the array pointed to by ``buf``
+into the file associated with ``fildes``.
-If ``nybte`` is zero and the file is a regular file, the ``write()``
-function returns zero and has no other effect. If ``nbyte`` is zero
-and the file is a special file, te results are not portable.
+If ``nybte`` is zero and the file is a regular file, the ``write()`` function
+returns zero and has no other effect. If ``nbyte`` is zero and the file is a
+special file, te results are not portable.
-The ``write()`` function returns the number of bytes written. This
-number will be less than ``nbytes`` if there is an error. It will never
-be greater than ``nbytes``.
+The ``write()`` function returns the number of bytes written. This number will
+be less than ``nbytes`` if there is an error. It will never be greater than
+``nbytes``.
**NOTES:**
NONE
+.. _fcntl:
+
fcntl - Manipulates an open file descriptor
-------------------------------------------
.. index:: fcntl
@@ -346,106 +366,97 @@ fcntl - Manipulates an open file descriptor
**CALLING SEQUENCE:**
-.. code:: c
+.. code-block:: c
#include <sys/types.h>
#include <fcntl.h>
#include <unistd.h>
int fcntl(
- int fildes,
- int cmd
+ int fildes,
+ int cmd
);
**STATUS CODES:**
-*EACCESS*
- Search permission is denied for a direcotry in a file's path
- prefix.
-
-*EAGAIN*
- The O_NONBLOCK flag is set for a file descriptor and the process
- would be delayed in the I/O operation.
-
-*EBADF*
- Invalid file descriptor
-
-*EDEADLK*
- An ``fcntl`` with function F_SETLKW would cause a deadlock.
-
-*EINTR*
- The functioin was interrupted by a signal.
-
-*EINVAL*
- Invalid argument
-
-*EMFILE*
- Too many file descriptor or in use by the process.
-
-*ENOLCK*
- No locks available
+.. list-table::
+ :class: rtems-table
+
+ * - ``EACCESS``
+ - Search permission is denied for a direcotry in a file's path prefix.
+ * - ``EAGAIN``
+ - The O_NONBLOCK flag is set for a file descriptor and the process would be
+ delayed in the I/O operation.
+ * - ``EBADF``
+ - Invalid file descriptor
+ * - ``EDEADLK``
+ - An ``fcntl`` with function ``F_SETLKW`` would cause a deadlock.
+ * - ``EINTR``
+ - The functioin was interrupted by a signal.
+ * - ``EINVAL``
+ - Invalid argument
+ * - ``EMFILE``
+ - Too many file descriptor or in use by the process.
+ * - ``ENOLCK``
+ - No locks available
**DESCRIPTION:**
-``fcntl()`` performs one of various miscellaneous operations on``fd``. The operation in question is determined by ``cmd``:
-
-*F_DUPFD*
- Makes ``arg`` be a copy of ``fd``, closing ``fd`` first if necessary.
- The same functionality can be more easily achieved by using ``dup2()``.
- The old and new descriptors may be used interchangeably. They share locks,
- file position pointers and flags; for example, if the file position is
- modified by using ``lseek()`` on one of the descriptors, the position is
- also changed for the other.
- The two descriptors do not share the close-on-exec flag, however. The
- close-on-exec flag of the copy is off, meaning that it will be closed on
- exec.
- On success, the new descriptor is returned.
-
-*F_GETFD*
- Read the close-on-exec flag. If the low-order bit is 0, the file will
- remain open across exec, otherwise it will be closed.
-
-*F_SETFD*
- Set the close-on-exec flag to the value specified by ``arg`` (only the least
- significant bit is used).
-
-*F_GETFL*
- Read the descriptor's flags (all flags (as set by open()) are returned).
-
-*F_SETFL*
- Set the descriptor's flags to the value specified by ``arg``. Only``O_APPEND`` and ``O_NONBLOCK`` may be set.
- The flags are shared between copies (made with ``dup()`` etc.) of the same
- file descriptor.
- The flags and their semantics are described in ``open()``.
-
-*F_GETLK, F_SETLK and F_SETLKW*
- Manage discretionary file locks. The third argument ``arg`` is a pointer to a
- struct flock (that may be overwritten by this call).
-
-*F_GETLK*
- Return the flock structure that prevents us from obtaining the lock, or set the``l_type`` field of the lock to ``F_UNLCK`` if there is no obstruction.
-
-*F_SETLK*
- The lock is set (when ``l_type`` is ``F_RDLCK`` or ``F_WRLCK``) or
- cleared (when it is ``F_UNLCK``. If lock is held by someone else, this
- call returns -1 and sets ``errno`` to EACCES or EAGAIN.
-
-*F_SETLKW*
- Like ``F_SETLK``, but instead of returning an error we wait for the lock to
- be released.
-
-*F_GETOWN*
- Get the process ID (or process group) of the owner of a socket.
- Process groups are returned as negative values.
-
-*F_SETOWN*
- Set the process or process group that owns a socket.
- For these commands, ownership means receiving ``SIGIO`` or ``SIGURG``
- signals.
- Process groups are specified using negative values.
+``fcntl()`` performs one of various miscellaneous operations on``fd``. The
+operation in question is determined by ``cmd``:
+
+.. list-table::
+ :class: rtems-table
+
+ * - ``F_DUPFD``
+ - Makes ``arg`` be a copy of ``fd``, closing ``fd`` first if necessary. The
+ same functionality can be more easily achieved by using ``dup2()``. The
+ old and new descriptors may be used interchangeably. They share locks,
+ file position pointers and flags; for example, if the file position is
+ modified by using ``lseek()`` on one of the descriptors, the position is
+ also changed for the other. The two descriptors do not share the
+ close-on-exec flag, however. The close-on-exec flag of the copy is off,
+ meaning that it will be closed on exec. On success, the new descriptor is
+ returned.
+ * - ``F_GETFD``
+ - Read the close-on-exec flag. If the low-order bit is 0, the file will
+ remain open across exec, otherwise it will be closed.
+ * - ``F_SETFD``
+ - Set the close-on-exec flag to the value specified by ``arg`` (only the
+ least significant bit is used).
+ * - ``F_GETFL``
+ - Read the descriptor's flags (all flags (as set by open()) are returned).
+ * - ``F_SETFL``
+ - Set the descriptor's flags to the value specified by
+ ``arg``. Only``O_APPEND`` and ``O_NONBLOCK`` may be set. The flags are
+ shared between copies (made with ``dup()`` etc.) of the same file
+ descriptor. The flags and their semantics are described in ``open()``.
+ * - ``F_GETLK``, ``F_SETLK`` and ``F_SETLKW``
+ - Manage discretionary file locks. The third argument ``arg`` is a pointer
+ to a struct flock (that may be overwritten by this call).
+ * - ``F_GETLK``
+ - Return the flock structure that prevents us from obtaining the lock, or
+ set the``l_type`` field of the lock to ``F_UNLCK`` if there is no
+ obstruction.
+ * - ``F_SETLK``
+ - The lock is set (when ``l_type`` is ``F_RDLCK`` or ``F_WRLCK``) or cleared
+ (when it is ``F_UNLCK``. If lock is held by someone else, this call
+ returns -1 and sets ``errno`` to EACCES or EAGAIN.
+ * - ``F_SETLKW``
+ - Like ``F_SETLK``, but instead of returning an error we wait for the lock
+ to be released.
+ * - ``F_GETOWN``
+ - Get the process ID (or process group) of the owner of a socket. Process
+ groups are returned as negative values.
+ * - ``F_SETOWN``
+ - Set the process or process group that owns a socket. For these commands,
+ ownership means receiving ``SIGIO`` or ``SIGURG`` signals. Process groups
+ are specified using negative values.
**NOTES:**
-The errors returned by ``dup2`` are different from those returned by``F_DUPFD``.
+The errors returned by ``dup2`` are different from those returned by ``F_DUPFD``.
+
+.. _lseek:
lseek - Reposition read/write file offset
-----------------------------------------
@@ -454,32 +465,34 @@ lseek - Reposition read/write file offset
**CALLING SEQUENCE:**
-.. code:: c
+.. code-block:: c
#include <sys/types.h>
#include <unistd.h>
int lseek(
- int fildes,
- off_t offset,
- int whence
+ int fildes,
+ off_t offset,
+ int whence
);
**STATUS CODES:**
-*EBADF*
- ``fildes`` is not an open file descriptor.
-
-*ESPIPE*
- ``fildes`` is associated with a pipe, socket or FIFO.
+.. list-table::
+ :class: rtems-table
-*EINVAL*
- ``whence`` is not a proper value.
+ * - ``EBADF``
+ - ``fildes`` is not an open file descriptor.
+ * - ``ESPIPE``
+ - ``fildes`` is associated with a pipe, socket or FIFO.
+ * - ``EINVAL``
+ - ``whence`` is not a proper value.
**DESCRIPTION:**
-The ``lseek`` function repositions the offset of the file descriptor``fildes`` to the argument offset according to the directive whence.
-The argument ``fildes`` must be an open file descriptor. ``Lseek``
-repositions the file pointer fildes as follows:
+The ``lseek`` function repositions the offset of the file descriptor ``fildes``
+to the argument offset according to the directive whence. The argument
+``fildes`` must be an open file descriptor. ``Lseek`` repositions the file
+pointer fildes as follows:
- If ``whence`` is SEEK_SET, the offset is set to ``offset`` bytes.
@@ -489,18 +502,20 @@ repositions the file pointer fildes as follows:
- If ``whence`` is SEEK_END, the offset is set to the size of the
file plus ``offset`` bytes.
-The ``lseek`` function allows the file offset to be set beyond the end
-of the existing end-of-file of the file. If data is later written at this
-point, subsequent reads of the data in the gap return bytes of zeros
-(until data is actually written into the gap).
+The ``lseek`` function allows the file offset to be set beyond the end of the
+existing end-of-file of the file. If data is later written at this point,
+subsequent reads of the data in the gap return bytes of zeros (until data is
+actually written into the gap).
-Some devices are incapable of seeking. The value of the pointer associated
-with such a device is undefined.
+Some devices are incapable of seeking. The value of the pointer associated with
+such a device is undefined.
**NOTES:**
NONE
+.. _fsync:
+
fsync - Synchronize file complete in-core state with that on disk
-----------------------------------------------------------------
.. index:: fsync
@@ -508,28 +523,30 @@ fsync - Synchronize file complete in-core state with that on disk
**CALLING SEQUENCE:**
-.. code:: c
+.. code-block:: c
int fsync(
- int fd
+ int fd
);
**STATUS CODES:**
-On success, zero is returned. On error, -1 is returned, and ``errno``
-is set appropriately.
-
-*EBADF*
- ``fd`` is not a valid descriptor open for writing
-
-*EINVAL*
- ``fd`` is bound to a special file which does not support support synchronization
+On success, zero is returned. On error, -1 is returned, and ``errno`` is set
+appropriately.
-*EROFS*
- ``fd`` is bound to a special file which does not support support synchronization
+.. list-table::
+ :class: rtems-table
-*EIO*
- An error occurred during synchronization
+ * - ``EBADF``
+ - ``fd`` is not a valid descriptor open for writing
+ * - ``EINVAL``
+ - ``fd`` is bound to a special file which does not support support
+ synchronization
+ * - ``EROFS``
+ - ``fd`` is bound to a special file which does not support support
+ synchronization
+ * - ``EIO``
+ - An error occurred during synchronization
**DESCRIPTION:**
@@ -539,6 +556,8 @@ is set appropriately.
NONE
+.. _fdatasync:
+
fdatasync - Synchronize file in-core data with that on disk
-----------------------------------------------------------
.. index:: fdatasync
@@ -546,47 +565,50 @@ fdatasync - Synchronize file in-core data with that on disk
**CALLING SEQUENCE:**
-.. code:: c
+.. code-block:: c
int fdatasync(
- int fd
+ int fd
);
**STATUS CODES:**
-On success, zero is returned. On error, -1 is returned, and ``errno`` is
-set appropriately.
-
-*EBADF*
- ``fd`` is not a valid file descriptor open for writing.
-
-*EINVAL*
- ``fd`` is bound to a special file which does not support synchronization.
+On success, zero is returned. On error, -1 is returned, and ``errno`` is set
+appropriately.
-*EIO*
- An error occurred during synchronization.
+.. list-table::
+ :class: rtems-table
-*EROFS*
- ``fd`` is bound to a special file which dows not support synchronization.
+ * - ``EBADF``
+ - ``fd`` is not a valid file descriptor open for writing.
+ * - ``EINVAL``
+ - ``fd`` is bound to a special file which does not support synchronization.
+ * - ``EIO``
+ - An error occurred during synchronization.
+ * - ``EROFS``
+ - ``fd`` is bound to a special file which dows not support synchronization.
**DESCRIPTION:**
-``fdatasync`` flushes all data buffers of a file to disk (before the system call
-returns). It resembles ``fsync`` but is not required to update the metadata such
-as access time.
+``fdatasync`` flushes all data buffers of a file to disk (before the system
+call returns). It resembles ``fsync`` but is not required to update the
+metadata such as access time.
-Applications that access databases or log files often write a tiny data fragment
-(e.g., one line in a log file) and then call ``fsync`` immediately in order to
-ensure that the written data is physically stored on the harddisk. Unfortunately,
-fsync will always initiate two write operations: one for the newly written data and
-another one in order to update the modification time stored in the inode. If the
-modification time is not a part of the transaction concept ``fdatasync`` can be
-used to avoid unnecessary inode disk write operations.
+Applications that access databases or log files often write a tiny data
+fragment (e.g., one line in a log file) and then call ``fsync`` immediately in
+order to ensure that the written data is physically stored on the
+harddisk. Unfortunately, fsync will always initiate two write operations: one
+for the newly written data and another one in order to update the modification
+time stored in the inode. If the modification time is not a part of the
+transaction concept ``fdatasync`` can be used to avoid unnecessary inode disk
+write operations.
**NOTES:**
NONE
+.. _sync:
+
sync - Schedule file system updates
-----------------------------------
.. index:: sync
@@ -594,7 +616,7 @@ sync - Schedule file system updates
**CALLING SEQUENCE:**
-.. code:: c
+.. code-block:: c
void sync(void);
@@ -604,14 +626,15 @@ NONE
**DESCRIPTION:**
-The ``sync`` service causes all information in memory that updates
-file systems to be scheduled for writing out to all file systems.
+The ``sync`` service causes all information in memory that updates file systems
+to be scheduled for writing out to all file systems.
**NOTES:**
-The writing of data to the file systems is only guaranteed to be
-scheduled upon return. It is not necessarily complete upon return
-from ``sync``.
+The writing of data to the file systems is only guaranteed to be scheduled upon
+return. It is not necessarily complete upon return from ``sync``.
+
+.. _mount:
mount - Mount a file system
---------------------------
@@ -620,15 +643,15 @@ mount - Mount a file system
**CALLING SEQUENCE:**
-.. code:: c
+.. code-block:: c
#include <libio.h>
int mount(
- rtems_filesystem_mount_table_entry_t \**mt_entry,
- rtems_filesystem_operations_table \*fs_ops,
- rtems_filesystem_options_t fsoptions,
- char \*device,
- char \*mount_point
+ rtems_filesystem_mount_table_entry_t **mt_entry,
+ rtems_filesystem_operations_table *fs_ops,
+ rtems_filesystem_options_t fsoptions,
+ char *device,
+ char *mount_point
);
**STATUS CODES:**
@@ -637,19 +660,21 @@ mount - Mount a file system
**DESCRIPTION:**
-The ``mount`` routines mounts the filesystem class
-which uses the filesystem operations specified by ``fs_ops``
-and ``fsoptions``. The filesystem is mounted at the directory``mount_point`` and the mode of the mounted filesystem is
-specified by ``fsoptions``. If this filesystem class requires
-a device, then the name of the device must be specified by ``device``.
+The ``mount`` routines mounts the filesystem class which uses the filesystem
+operations specified by ``fs_ops`` and ``fsoptions``. The filesystem is
+mounted at the directory ``mount_point`` and the mode of the mounted filesystem
+is specified by ``fsoptions``. If this filesystem class requires a device,
+then the name of the device must be specified by ``device``.
-If this operation succeeds, the mount table entry for the mounted
-filesystem is returned in ``mt_entry``.
+If this operation succeeds, the mount table entry for the mounted filesystem is
+returned in ``mt_entry``.
**NOTES:**
NONE
+.. _unmount:
+
unmount - Unmount file systems
------------------------------
.. index:: unmount
@@ -657,11 +682,11 @@ unmount - Unmount file systems
**CALLING SEQUENCE:**
-.. code:: c
+.. code-block:: c
#include <libio.h>
int unmount(
- const char \*mount_path
+ const char \*mount_path
);
**STATUS CODES:**
@@ -670,13 +695,15 @@ unmount - Unmount file systems
**DESCRIPTION:**
-The ``unmount`` routine removes the attachment of the filesystem specified
-by ``mount_path``.
+The ``unmount`` routine removes the attachment of the filesystem specified by
+``mount_path``.
**NOTES:**
NONE
+.. _readv:
+
readv - Vectored read from a file
---------------------------------
.. index:: readv
@@ -684,43 +711,48 @@ readv - Vectored read from a file
**CALLING SEQUENCE:**
-.. code:: c
+.. code-block:: c
#include <sys/uio.h>
ssize_t readv(
- int fd,
- const struct iovec \*iov,
- int iovcnt
+ int fd,
+ const struct iovec *iov,
+ int iovcnt
);
**STATUS CODES:**
-In addition to the errors detected by``Input and Output Primitives Manager read - Reads from a file, read()``,
-this routine may return -1 and sets ``errno`` based upon the following
-errors:
+In addition to the errors detected by *Input and Output Primitives Manager
+read - Reads from a file, read()*, this routine may return -1 and sets
+``errno`` based upon the following errors:
-*EINVAL*
- The sum of the ``iov_len`` values in the iov array overflowed an``ssize_t``.
+.. list-table::
+ :class: rtems-table
-*EINVAL*
- The ``iovcnt`` argument was less than or equal to 0, or greater
- than ``IOV_MAX``.
+ * - ``EINVAL``
+ - The sum of the ``iov_len`` values in the iov array overflowed
+ an ``ssize_t``.
+ * - ``EINVAL``
+ - The ``iovcnt`` argument was less than or equal to 0, or greater than
+ ``IOV_MAX``.
**DESCRIPTION:**
-The ``readv()`` function is equivalent to ``read()``
-except as described here. The ``readv()`` function shall place
-the input data into the ``iovcnt`` buffers specified by the
-members of the ``iov`` array: ``iov[0], iov[1], ..., iov[iovcnt-1]``.
+The ``readv()`` function is equivalent to ``read()`` except as described
+here. The ``readv()`` function shall place the input data into the ``iovcnt``
+buffers specified by the members of the ``iov`` array: ``iov[0], iov[1], ...,
+iov[iovcnt-1]``.
-Each ``iovec`` entry specifies the base address and length of an area
-in memory where data should be placed. The ``readv()`` function
-always fills an area completely before proceeding to the next.
+Each ``iovec`` entry specifies the base address and length of an area in memory
+where data should be placed. The ``readv()`` function always fills an area
+completely before proceeding to the next.
**NOTES:**
NONE
+.. _writev:
+
writev - Vectored write to a file
---------------------------------
.. index:: writev
@@ -728,50 +760,53 @@ writev - Vectored write to a file
**CALLING SEQUENCE:**
-.. code:: c
+.. code-block:: c
#include <sys/uio.h>
ssize_t writev(
- int fd,
- const struct iovec \*iov,
- int iovcnt
+ int fd,
+ const struct iovec \*iov,
+ int iovcnt
);
**STATUS CODES:**
-In addition to the errors detected by``Input and Output Primitives Manager write - Write to a file, write()``,
-this routine may return -1 and sets ``errno`` based upon the following
-errors:
+In addition to the errors detected by *Input and Output Primitives Manager
+write - Write to a file, write()*, this routine may return -1 and sets
+``errno`` based upon the following errors:
-*EINVAL*
- The sum of the ``iov_len`` values in the iov array overflowed an``ssize_t``.
+.. list-table::
+ :class: rtems-table
-*EINVAL*
- The ``iovcnt`` argument was less than or equal to 0, or greater
- than ``IOV_MAX``.
+ * - ``EINVAL``
+ - The sum of the ``iov_len`` values in the iov array overflowed
+ an ``ssize_t``.
+ * - ``EINVAL``
+ - The ``iovcnt`` argument was less than or equal to 0, or greater than
+ ``IOV_MAX``.
**DESCRIPTION:**
-The ``writev()`` function is equivalent to ``write()``,
-except as noted here. The ``writev()`` function gathers output
-data from the ``iovcnt`` buffers specified by the members of
-the ``iov array``: ``iov[0], iov[1], ..., iov[iovcnt-1]``.
-The ``iovcnt`` argument is valid if greater than 0 and less
+The ``writev()`` function is equivalent to ``write()``, except as noted
+here. The ``writev()`` function gathers output data from the ``iovcnt`` buffers
+specified by the members of the ``iov array``: ``iov[0], iov[1], ...,
+iov[iovcnt-1]``. The ``iovcnt`` argument is valid if greater than 0 and less
than or equal to ``IOV_MAX``.
-Each ``iovec`` entry specifies the base address and length of
-an area in memory from which data should be written. The ``writev()``
-function always writes a complete area before proceeding to the next.
+Each ``iovec`` entry specifies the base address and length of an area in memory
+from which data should be written. The ``writev()`` function always writes a
+complete area before proceeding to the next.
-If ``fd`` refers to a regular file and all of the ``iov_len``
-members in the array pointed to by ``iov`` are 0, ``writev()``
-returns 0 and has no other effect. For other file types, the behavior
-is unspecified by POSIX.
+If ``fd`` refers to a regular file and all of the ``iov_len`` members in the
+array pointed to by ``iov`` are 0, ``writev()`` returns 0 and has no other
+effect. For other file types, the behavior is unspecified by POSIX.
**NOTES:**
NONE
+.. _aio_read:
+
aio_read - Asynchronous Read
----------------------------
.. index:: aio_read
@@ -779,22 +814,27 @@ aio_read - Asynchronous Read
**CALLING SEQUENCE:**
-.. code:: c
+.. code-block:: c
int aio_read(
);
**STATUS CODES:**
-*E*
- The
+.. list-table::
+ :class: rtems-table
+
+ * - ``E``
+ - The
**DESCRIPTION:**
**NOTES:**
-This routine is not currently supported by RTEMS but could be
-in a future version.
+This routine is not currently supported by RTEMS but could be in a future
+version.
+
+.. _aio_write:
aio_write - Asynchronous Write
------------------------------
@@ -803,22 +843,27 @@ aio_write - Asynchronous Write
**CALLING SEQUENCE:**
-.. code:: c
+.. code-block:: c
int aio_write(
);
**STATUS CODES:**
-*E*
- The
+.. list-table::
+ :class: rtems-table
+
+ * - ``E``
+ - The
**DESCRIPTION:**
**NOTES:**
-This routine is not currently supported by RTEMS but could be
-in a future version.
+This routine is not currently supported by RTEMS but could be in a future
+version.
+
+.. _lio_listio:
lio_listio - List Directed I/O
------------------------------
@@ -827,22 +872,27 @@ lio_listio - List Directed I/O
**CALLING SEQUENCE:**
-.. code:: c
+.. code-block:: c
int lio_listio(
);
**STATUS CODES:**
-*E*
- The
+.. list-table::
+ :class: rtems-table
+
+ * - ``E``
+ - The
**DESCRIPTION:**
**NOTES:**
-This routine is not currently supported by RTEMS but could be
-in a future version.
+This routine is not currently supported by RTEMS but could be in a future
+version.
+
+.. _aio_error:
aio_error - Retrieve Error Status of Asynchronous I/O Operation
---------------------------------------------------------------
@@ -851,22 +901,27 @@ aio_error - Retrieve Error Status of Asynchronous I/O Operation
**CALLING SEQUENCE:**
-.. code:: c
+.. code-block:: c
int aio_error(
);
**STATUS CODES:**
-*E*
- The
+.. list-table::
+ :class: rtems-table
+
+ * - ``E``
+ - The
**DESCRIPTION:**
**NOTES:**
-This routine is not currently supported by RTEMS but could be
-in a future version.
+This routine is not currently supported by RTEMS but could be in a future
+version.
+
+.. _aio_return:
aio_return - Retrieve Return Status Asynchronous I/O Operation
--------------------------------------------------------------
@@ -875,22 +930,27 @@ aio_return - Retrieve Return Status Asynchronous I/O Operation
**CALLING SEQUENCE:**
-.. code:: c
+.. code-block:: c
int aio_return(
);
**STATUS CODES:**
-*E*
- The
+.. list-table::
+ :class: rtems-table
+
+ * - ``E``
+ - The
**DESCRIPTION:**
**NOTES:**
-This routine is not currently supported by RTEMS but could be
-in a future version.
+This routine is not currently supported by RTEMS but could be in a future
+version.
+
+.. _aio_cancel:
aio_cancel - Cancel Asynchronous I/O Request
--------------------------------------------
@@ -899,22 +959,27 @@ aio_cancel - Cancel Asynchronous I/O Request
**CALLING SEQUENCE:**
-.. code:: c
+.. code-block:: c
int aio_cancel(
);
**STATUS CODES:**
-*E*
- The
+.. list-table::
+ :class: rtems-table
+
+ * - ``E``
+ - The
**DESCRIPTION:**
**NOTES:**
-This routine is not currently supported by RTEMS but could be
-in a future version.
+This routine is not currently supported by RTEMS but could be in a future
+version.
+
+.. _aio_suspend:
aio_suspend - Wait for Asynchronous I/O Request
-----------------------------------------------
@@ -923,22 +988,27 @@ aio_suspend - Wait for Asynchronous I/O Request
**CALLING SEQUENCE:**
-.. code:: c
+.. code-block:: c
int aio_suspend(
);
**STATUS CODES:**
-*E*
- The
+.. list-table::
+ :class: rtems-table
+
+ * - ``E``
+ - The
**DESCRIPTION:**
**NOTES:**
-This routine is not currently supported by RTEMS but could be
-in a future version.
+This routine is not currently supported by RTEMS but could be in a future
+version.
+
+.. _aio_fsync:
aio_fsync - Asynchronous File Synchronization
---------------------------------------------
@@ -947,26 +1017,22 @@ aio_fsync - Asynchronous File Synchronization
**CALLING SEQUENCE:**
-.. code:: c
+.. code-block:: c
int aio_fsync(
);
**STATUS CODES:**
-*E*
- The
+.. list-table::
+ :class: rtems-table
+
+ * - ``E``
+ - The
**DESCRIPTION:**
**NOTES:**
-This routine is not currently supported by RTEMS but could be
-in a future version.
-
-.. COMMENT: COPYRIGHT (c) 1988-2002.
-
-.. COMMENT: On-Line Applications Research Corporation (OAR).
-
-.. COMMENT: All rights reserved.
-
+This routine is not currently supported by RTEMS but could be in a future
+version.
diff --git a/posix_users/key.rst b/posix_users/key.rst
index 71b04c7..2c6af32 100644
--- a/posix_users/key.rst
+++ b/posix_users/key.rst
@@ -1,3 +1,7 @@
+.. COMMENT: COPYRIGHT (c) 1988-2002.
+.. COMMENT: On-Line Applications Research Corporation (OAR).
+.. COMMENT: All rights reserved.
+
Key Manager
###########
@@ -9,13 +13,13 @@ specific to threads.
The directives provided by the key manager are:
-- ``pthread_key_create`` - Create Thread Specific Data Key
+- pthread_key_create_ - Create Thread Specific Data Key
-- ``pthread_key_delete`` - Delete Thread Specific Data Key
+- pthread_key_delete_ - Delete Thread Specific Data Key
-- ``pthread_setspecific`` - Set Thread Specific Key Value
+- pthread_setspecific_ - Set Thread Specific Key Value
-- ``pthread_getspecific`` - Get Thread Specific Key Value
+- pthread_getspecific_ - Get Thread Specific Key Value
Background
==========
@@ -30,166 +34,177 @@ There is currently no text in this section.
Directives
==========
-This section details the key manager's directives.
-A subsection is dedicated to each of this manager's directives
-and describes the calling sequence, related constants, usage,
-and status codes.
+This section details the key manager's directives. A subsection is dedicated
+to each of this manager's directives and describes the calling sequence,
+related constants, usage, and status codes.
+
+.. _pthread_key_create:
pthread_key_create - Create Thread Specific Data Key
----------------------------------------------------
**CALLING SEQUENCE:**
-.. code:: c
+.. code-block:: c
#include <pthread.h>
int pthread_key_create(
- pthread_key_t \*key,
- void (\*destructor)( void )
+ pthread_key_t *key,
+ void (*destructor)( void )
);
**STATUS CODES:**
-*EAGAIN*
- There were not enough resources available to create another key.
+.. list-table::
+ :class: rtems-table
-*ENOMEM*
- Insufficient memory exists to create the key.
+ * - ``EAGAIN``
+ - There were not enough resources available to create another key.
+ * - ``ENOMEM``
+ - Insufficient memory exists to create the key.
**DESCRIPTION**
-The pthread_key_create() function shall create a thread-specific data
-key visible to all threads in the process. Key values provided by
-pthread_key_create() are opaque objects used to locate thread-specific
-data. Although the same key value may be used by different threads, the
-values bound to the key by pthread_setspecific() are maintained on a
-per-thread basis and persist for the life of the calling thread.
+The ``pthread_key_create()`` function shall create a thread-specific data key
+visible to all threads in the process. Key values provided by
+``pthread_key_create()`` are opaque objects used to locate thread-specific
+data. Although the same key value may be used by different threads, the values
+bound to the key by ``pthread_setspecific()`` are maintained on a per-thread
+basis and persist for the life of the calling thread.
-Upon key creation, the value NULL shall be associated with the new key
-in all active threads. Upon thread creation, the value NULL shall be
+Upon key creation, the value ``NULL`` shall be associated with the new key in
+all active threads. Upon thread creation, the value ``NULL`` shall be
associated with all defined keys in the new thread.
**NOTES**
-An optional destructor function may be associated with each key value.
-At thread exit, if a key value has a non-NULL destructor pointer, and
-the thread has a non-NULL value associated with that key, the value of
-the key is set to NULL, and then the function pointed to is called with
-the previously associated value as its sole argument. The order of
-destructor calls is unspecified if more than one destructor exists for
-a thread when it exits.
+An optional destructor function may be associated with each key value. At
+thread exit, if a key value has a non-``NULL`` destructor pointer, and the
+thread has a non-``NULL`` value associated with that key, the value of the key
+is set to NULL, and then the function pointed to is called with the previously
+associated value as its sole argument. The order of destructor calls is
+unspecified if more than one destructor exists for a thread when it exits.
+
+.. _pthread_key_delete:
pthread_key_delete - Delete Thread Specific Data Key
----------------------------------------------------
**CALLING SEQUENCE:**
-.. code:: c
+.. code-block:: c
#include <pthread.h>
int pthread_key_delete(
- pthread_key_t key);
+ pthread_key_t key
+ );
**STATUS CODES:**
-*EINVAL*
- The key was invalid
+.. list-table::
+ :class: rtems-table
+
+ * - ``EINVAL``
+ - The key was invalid
**DESCRIPTION:**
-The pthread_key_delete() function shall delete a thread-specific data key
-previously returned by pthread_key_create(). The thread-specific data
-values associated with key need not be NULL at the time pthread_key_delete()
-is called. It is the responsibility of the application to free any
-application storage or perform any cleanup actions for data structures related
-to the deleted key or associated thread-specific data in any
+The ``pthread_key_delete()`` function shall delete a thread-specific data key
+previously returned by ``pthread_key_create()``. The thread-specific data
+values associated with key need not be NULL at the time
+``pthread_key_delete()`` is called. It is the responsibility of the application
+to free any application storage or perform any cleanup actions for data
+structures related to the deleted key or associated thread-specific data in any
threads; this cleanup can be done either before or after
-pthread_key_delete() is called. Any attempt to use key following the call to
-pthread_key_delete() results in undefined behavior.
+``pthread_key_delete()`` is called. Any attempt to use key following the call
+to ``pthread_key_delete()`` results in undefined behavior.
**NOTES:**
-The pthread_key_delete() function shall be callable from within
-destructor functions. No destructor functions shall be invoked by
-pthread_key_delete(). Any destructor function that may have been
-associated with key shall no longer be called upon thread exit.
+The ``pthread_key_delete()`` function shall be callable from within destructor
+functions. No destructor functions shall be invoked by
+``pthread_key_delete()``. Any destructor function that may have been associated
+with key shall no longer be called upon thread exit.
+
+.. _pthread_setspecific:
pthread_setspecific - Set Thread Specific Key Value
---------------------------------------------------
**CALLING SEQUENCE:**
-.. code:: c
+.. code-block:: c
#include <pthread.h>
int pthread_setspecific(
- pthread_key_t key,
- const void \*value
+ pthread_key_t key,
+ const void *value
);
**STATUS CODES:**
-*EINVAL*
- The specified key is invalid.
+.. list-table::
+ :class: rtems-table
+
+ * - ``EINVAL``
+ - The specified key is invalid.
**DESCRIPTION:**
-The pthread_setspecific() function shall associate a thread-specific value
-with a key obtained via a previous call to pthread_key_create().
-Different threads may bind different values to the same key. These values
-are typically pointers to blocks of dynamically allocated memory that
-have been reserved for use by the calling thread.
+The ``pthread_setspecific()`` function shall associate a thread-specific value
+with a key obtained via a previous call to ``pthread_key_create()``. Different
+threads may bind different values to the same key. These values are typically
+pointers to blocks of dynamically allocated memory that have been reserved for
+use by the calling thread.
**NOTES:**
-The effect of calling pthread_setspecific() with a key value not obtained
-from pthread_key_create() or after key has
-been deleted with pthread_key_delete() is undefined.
+The effect of calling ``pthread_setspecific()`` with a key value not obtained
+from ``pthread_key_create()`` or after key has been deleted with
+``pthread_key_delete()`` is undefined.
+
+``pthread_setspecific()`` may be called from a thread-specific data destructor
+function. Calling ``pthread_setspecific()`` from a thread-specific data
+destructor routine may result either in lost storage (after at least
+``PTHREAD_DESTRUCTOR_ITERATIONS`` attempts at destruction) or in an infinite
+loop.
-pthread_setspecific() may be called from a thread-specific data
-destructor function. Calling pthread_setspecific() from a thread-specific
-data destructor routine may result either in lost storage (after at least
-PTHREAD_DESTRUCTOR_ITERATIONS attempts at destruction) or in an infinite loop.
+.. _pthread_getspecific:
pthread_getspecific - Get Thread Specific Key Value
---------------------------------------------------
**CALLING SEQUENCE:**
-.. code:: c
+.. code-block:: c
#include <pthread.h>
- void \*pthread_getspecific(
- pthread_key_t key
+ void *pthread_getspecific(
+ pthread_key_t key
);
**STATUS CODES:**
-*NULL*
- There is no thread-specific data associated with the specified key.
+.. list-table::
+ :class: rtems-table
-*non-NULL*
- The data associated with the specified key.
+ * - ``NULL``
+ - There is no thread-specific data associated with the specified key.
+ * - ``non-NULL``
+ - The data associated with the specified key.
**DESCRIPTION:**
-The pthread_getspecific() function shall return the value currently bound to
-the specified key on behalf of the calling thread.
+The ``pthread_getspecific()`` function shall return the value currently bound
+to the specified key on behalf of the calling thread.
**NOTES:**
-The effect of calling pthread_getspecific() with a key value not obtained from
-pthread_key_create() or after key has
-been deleted with pthread_key_delete() is undefined.
-
-pthread_getspecific() may be called from a thread-specific data destructor
-function. A call to pthread_getspecific() for the thread-specific data key
-being destroyed shall return the value NULL, unless the value is changed
-(after the destructor starts) by a call to pthread_setspecific().
-
-.. COMMENT: COPYRIGHT (c) 1988-2002.
-
-.. COMMENT: On-Line Applications Research Corporation (OAR).
-
-.. COMMENT: All rights reserved.
+The effect of calling ``pthread_getspecific()`` with a key value not obtained
+from ``pthread_key_create()`` or after key has been deleted with
+``pthread_key_delete()`` is undefined.
+``pthread_getspecific()`` may be called from a thread-specific data destructor
+function. A call to ``pthread_getspecific()`` for the thread-specific data key
+being destroyed shall return the value ``NULL``, unless the value is changed
+(after the destructor starts) by a call to ``pthread_setspecific()``.
diff --git a/posix_users/language_specific_services.rst b/posix_users/language_specific_services.rst
index 5c08933..b38c25c 100644
--- a/posix_users/language_specific_services.rst
+++ b/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
-language-specific services for the C programming language manager is ...
+The 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.
-A subsection is dedicated to each of this manager's directives
-and describes the calling sequence, related constants, usage,
-and status codes.
+This section details the language-specific services for the C programming
+language manager's directives. A subsection is dedicated to each of this
+manager's directives and describes the calling sequence, related constants,
+usage, and status codes.
+
+.. _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*
- The
+.. list-table::
+ :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*
- The
+.. list-table::
+ :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*
- The
+.. list-table::
+ :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*
- The
+.. list-table::
+ :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*
- The
+.. list-table::
+ :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*
- The
+.. list-table::
+ :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*
- The
+.. list-table::
+ :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*
- The
+.. list-table::
+ :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*
- The
+.. list-table::
+ :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*
- The
+.. list-table::
+ :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*
- The
+.. list-table::
+ :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*
- The
+.. list-table::
+ :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*
- The
+.. list-table::
+ :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*
- The
+.. list-table::
+ :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*
- The
+.. list-table::
+ :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*
- The
+.. list-table::
+ :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*
- The
+.. list-table::
+ :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*
- The
+.. list-table::
+ :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*
- The
+.. list-table::
+ :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*
- The
+.. list-table::
+ :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*
- The
+.. list-table::
+ :class: rtems-table
+
+ * - ``E``
+ - The
**DESCRIPTION:**
**NOTES:**
-
-.. COMMENT: COPYRIGHT (c) 1988-2002.
-
-.. COMMENT: On-Line Applications Research Corporation (OAR).
-
-.. COMMENT: All rights reserved.
-
diff --git a/posix_users/memory_managment.rst b/posix_users/memory_managment.rst
index 1095b39..38e8542 100644
--- a/posix_users/memory_managment.rst
+++ b/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.
-A subsection is dedicated to each of this manager's directives
-and describes the calling sequence, related constants, usage,
-and status codes.
+This section details the memory management manager's directives. A subsection
+is dedicated to each of this manager's directives and describes the calling
+sequence, related constants, usage, and status codes.
+
+.. _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*
- The
+.. list-table::
+ :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*
- The
+.. list-table::
+ :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*
- The
+.. list-table::
+ :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*
- The
+.. list-table::
+ :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*
- The
+.. list-table::
+ :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*
- The
+.. list-table::
+ :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*
- The
+.. list-table::
+ :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*
- The
+.. list-table::
+ :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*
- The
+.. list-table::
+ :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*
- The
+.. list-table::
+ :class: rtems-table
+
+ * - ``E``
+ - The
**DESCRIPTION:**
**NOTES:**
-
-.. COMMENT: COPYRIGHT (c) 1988-2002.
-
-.. COMMENT: On-Line Applications Research Corporation (OAR).
-
-.. COMMENT: All rights reserved.
-
diff --git a/posix_users/message_passing.rst b/posix_users/message_passing.rst
index 2900ac6..c147a57 100644
--- a/posix_users/message_passing.rst
+++ b/posix_users/message_passing.rst
@@ -1,3 +1,7 @@
+.. COMMENT: COPYRIGHT (c) 1988-2014.
+.. COMMENT: On-Line Applications Research Corporation (OAR).
+.. COMMENT: All rights reserved.
+
Message Passing Manager
#######################
@@ -9,21 +13,21 @@ synchronization capabilities using POSIX message queues.
The directives provided by the message passing manager are:
-- ``mq_open`` - Open a Message Queue
+- mq_open_ - Open a Message Queue
-- ``mq_close`` - Close a Message Queue
+- mq_close_ - Close a Message Queue
-- ``mq_unlink`` - Remove a Message Queue
+- mq_unlink_ - Remove a Message Queue
-- ``mq_send`` - Send a Message to a Message Queue
+- mq_send_ - Send a Message to a Message Queue
-- ``mq_receive`` - Receive a Message from a Message Queue
+- mq_receive_ - Receive a Message from a Message Queue
-- ``mq_notify`` - Notify Process that a Message is Available
+- mq_notify_ - Notify Process that a Message is Available
-- ``mq_setattr`` - Set Message Queue Attributes
+- mq_setattr_ - Set Message Queue Attributes
-- ``mq_getattr`` - Get Message Queue Attributes
+- mq_getattr_ - Get Message Queue Attributes
Background
==========
@@ -31,33 +35,34 @@ Background
Theory
------
-Message queues are named objects that operate with readers and writers.
-In addition, a message queue is a priority queue of discrete messages.
-POSIX message queues offer a certain, basic amount of application access
-to, and control over, the message queue geometry that can be changed.
+Message queues are named objects that operate with readers and writers. In
+addition, a message queue is a priority queue of discrete messages. POSIX
+message queues offer a certain, basic amount of application access to, and
+control over, the message queue geometry that can be changed.
Messages
--------
A message is a variable length buffer where information can be stored to
-support communication. The length of the message and the information
-stored in that message are user-defined and can be actual data,
-pointer(s), or empty. There is a maximum acceptable length for a message
-that is associated with each message queue.
+support communication. The length of the message and the information stored in
+that message are user-defined and can be actual data, pointer(s), or
+empty. There is a maximum acceptable length for a message that is associated
+with each message queue.
Message Queues
--------------
-Message queues are named objects similar to the pipes of POSIX. They are
-a means of communicating data between multiple processes and for passing
-messages among tasks and ISRs. Message queues can contain a variable
-number of messages from 0 to an upper limit that is user defined. The
-maximum length of the message can be set on a per message queue basis.
-Normally messages are sent and received from the message queue in FIFO
-order. However, messages can also be prioritized and a priority queue
-established for the passing of messages. Synchronization is needed when a
-task waits for a message to arrive at a queue. Also, a task may poll a
-queue for the arrival of a message... index:: mqd_t
+Message queues are named objects similar to the pipes of POSIX. They are a
+means of communicating data between multiple processes and for passing messages
+among tasks and ISRs. Message queues can contain a variable number of messages
+from 0 to an upper limit that is user defined. The maximum length of the
+message can be set on a per message queue basis. Normally messages are sent
+and received from the message queue in FIFO order. However, messages can also
+be prioritized and a priority queue established for the passing of
+messages. Synchronization is needed when a task waits for a message to arrive
+at a queue. Also, a task may poll a queue for the arrival of a message.
+
+.. index:: mqd_t
The message queue descriptor ``mqd_t`` represents the message queue. It is
passed as an argument to all of the message queue functions.
@@ -65,37 +70,39 @@ passed as an argument to all of the message queue functions.
Building a Message Queue Attribute Set
--------------------------------------
-The mq_attr structure is used to define the characteristics of the message
-queue... index:: mq_attr
+The ``mq_attr`` structure is used to define the characteristics of the message
+queue.
+
+.. index:: mq_attr
-.. code:: c
+.. code-block:: c
typedef struct mq_attr{
- long mq_flags;
- long mq_maxmsg;
- long mq_msgsize;
- long mq_curmsgs;
+ long mq_flags;
+ long mq_maxmsg;
+ long mq_msgsize;
+ long mq_curmsgs;
};
All of these attributes are set when the message queue is created using
-mq_open. The mq_flags field is not used in the creation of a message
-queue, it is only used by mq_setattr and mq_getattr. The structure
-mq_attr is passed as an argument to mq_setattr and mq_getattr.
+mq_open. The mq_flags field is not used in the creation of a message queue, it
+is only used by ``mq_setattr`` and ``mq_getattr``. The structure ``mq_attr`` is
+passed as an argument to ``mq_setattr`` and ``mq_getattr``.
The mq_flags contain information affecting the behavior of the message
-queue. The O_NONBLOCK mq_flag is the only flag that is defined. In
-mq_setattr, the mq_flag can be set to dynamically change the blocking and
-non-blocking behavior of the message queue. If the non-block flag is set
+queue. The ``O_NONBLOCK`` ``mq_flag`` is the only flag that is defined. In
+``mq_setattr``, the ``mq_flag`` can be set to dynamically change the blocking
+and non-blocking behavior of the message queue. If the non-block flag is set
then the message queue is non-blocking, and requests to send and receive
-messages do not block waiting for resources. For a blocking message
-queue, a request to send might have to wait for an empty message queue,
-and a request to receive might have to wait for a message to arrive on the
-queue. Both mq_maxmsg and mq_msgsize affect the sizing of the message
-queue. mq_maxmsg specifies how many messages the queue can hold at any
-one time. mq_msgsize specifies the size of any one message on the queue.
-If either of these limits is exceeded, an error message results.
-
-Upon return from mq_getattr, the mq_curmsgs is set according to the
+messages do not block waiting for resources. For a blocking message queue, a
+request to send might have to wait for an empty message queue, and a request to
+receive might have to wait for a message to arrive on the queue. Both
+``mq_maxmsg`` and ``mq_msgsize`` affect the sizing of the message
+queue. ``mq_maxmsg`` specifies how many messages the queue can hold at any one
+time. ``mq_msgsize`` specifies the size of any one message on the queue. If
+either of these limits is exceeded, an error message results.
+
+Upon return from ``mq_getattr``, the ``mq_curmsgs`` is set according to the
current state of the message queue. This specifies the number of messages
currently on the queue.
@@ -103,43 +110,41 @@ Notification of a Message on the Queue
--------------------------------------
Every message queue has the ability to notify one (and only one) process
-whenever the queue's state changes from empty (0 messages) to nonempty.
-This means that the process does not have to block or constantly poll
-while it waits for a message. By calling mq_notify, you can attach a
-notification request to a message queue. When a message is received by an
-empty queue, if there are no processes blocked and waiting for the
-message, then the queue notifies the requesting process of a message
-arrival. There is only one signal sent by the message queue, after that
-the notification request is de-registered and another process can attach
-its notification request. After receipt of a notification, a process must
-re-register if it wishes to be notified again.
-
-If there is a process blocked and waiting for the message, that process
-gets the message, and notification is not sent. It is also possible for
-another process to receive the message after the notification is sent but
-before the notified process has sent its receive request.
-
-Only one process can have a notification request attached to a message
-queue at any one time. If another process attempts to register a
-notification request, it fails. You can de-register for a message queue
-by passing a NULL to mq_notify, this removes any notification request
-attached to the queue. Whenever the message queue is closed, all
-notification attachments are removed.
+whenever the queue's state changes from empty (0 messages) to nonempty. This
+means that the process does not have to block or constantly poll while it waits
+for a message. By calling ``mq_notify``, you can attach a notification request
+to a message queue. When a message is received by an empty queue, if there are
+no processes blocked and waiting for the message, then the queue notifies the
+requesting process of a message arrival. There is only one signal sent by the
+message queue, after that the notification request is de-registered and another
+process can attach its notification request. After receipt of a notification, a
+process must re-register if it wishes to be notified again.
+
+If there is a process blocked and waiting for the message, that process gets
+the message, and notification is not sent. It is also possible for another
+process to receive the message after the notification is sent but before the
+notified process has sent its receive request.
+
+Only one process can have a notification request attached to a message queue at
+any one time. If another process attempts to register a notification request,
+it fails. You can de-register for a message queue by passing a NULL to
+mq_notify, this removes any notification request attached to the
+queue. Whenever the message queue is closed, all notification attachments are
+removed.
POSIX Interpretation Issues
---------------------------
-There is one significant point of interpretation related to
-the RTEMS implementation of POSIX message queues:
+There is one significant point of interpretation related to the RTEMS
+implementation of POSIX message queues:
-*What happens to threads already blocked on a message queue when the
-mode of that same message queue is changed from blocking to non-blocking?*
+ | What happens to threads already blocked on a message queue when the mode
+ | of that same message queue is changed from blocking to non-blocking?
-The RTEMS POSIX implementation decided to unblock all waiting tasks
-with an ``EAGAIN`` status just as if a non-blocking version of
-the same operation had returned unsatisfied. This case is not
-discussed in the POSIX standard and other implementations may have
-chosen alternative behaviors.
+The RTEMS POSIX implementation decided to unblock all waiting tasks with an
+``EAGAIN`` status just as if a non-blocking version of the same operation had
+returned unsatisfied. This case is not discussed in the POSIX standard and
+other implementations may have chosen alternative behaviors.
Operations
==========
@@ -147,127 +152,127 @@ Operations
Opening or Creating a Message Queue
-----------------------------------
-If the message queue already exists, mq_open() opens it, if the message
-queue does not exist, mq_open() creates it. When a message queue is
+If the message queue already exists, ``mq_open()`` opens it, if the message
+queue does not exist, ``mq_open()`` creates it. When a message queue is
created, the geometry of the message queue is contained in the attribute
structure that is passed in as an argument. This includes mq_msgsize that
-dictates the maximum size of a single message, and the mq_maxmsg that
-dictates the maximum number of messages the queue can hold at one time.
-The blocking or non-blocking behavior of the queue can also specified.
+dictates the maximum size of a single message, and the mq_maxmsg that dictates
+the maximum number of messages the queue can hold at one time. The blocking or
+non-blocking behavior of the queue can also specified.
Closing a Message Queue
-----------------------
-The mq_close() function is used to close the connection made to a message
-queue that was made during mq_open. The message queue itself and the
-messages on the queue are persistent and remain after the queue is closed.
+The ``mq_close()`` function is used to close the connection made to a message
+queue that was made during mq_open. The message queue itself and the messages
+on the queue are persistent and remain after the queue is closed.
Removing a Message Queue
------------------------
-The mq_unlink() function removes the named message queue. If the message
+The ``mq_unlink()`` function removes the named message queue. If the message
queue is not open when mq_unlink is called, then the queue is immediately
-eliminated. Any messages that were on the queue are lost, and the queue
-can not be opened again. If processes have the queue open when mq_unlink
-is called, the removal of the queue is delayed until the last process
-using the queue has finished. However, the name of the message queue is
-removed so that no other process can open it.
+eliminated. Any messages that were on the queue are lost, and the queue can not
+be opened again. If processes have the queue open when mq_unlink is called, the
+removal of the queue is delayed until the last process using the queue has
+finished. However, the name of the message queue is removed so that no other
+process can open it.
Sending a Message to a Message Queue
------------------------------------
-The mq_send() function adds the message in priority order to the message
-queue. Each message has an assigned a priority. The highest priority
-message is be at the front of the queue.
+The ``mq_send()`` function adds the message in priority order to the message
+queue. Each message has an assigned a priority. The highest priority message is
+be at the front of the queue.
-The maximum number of messages that a message queue may accept is
-specified at creation by the mq_maxmsg field of the attribute structure.
-If this amount is exceeded, the behavior of the process is determined
-according to what oflag was used when the message queue was opened. If
-the queue was opened with O_NONBLOCK flag set, the process does not block,
-and an error is returned. If the O_NONBLOCK flag was not set, the process
-does block and wait for space on the queue.
+The maximum number of messages that a message queue may accept is specified at
+creation by the ``mq_maxmsg`` field of the attribute structure. If this amount
+is exceeded, the behavior of the process is determined according to what
+``oflag`` was used when the message queue was opened. If the queue was opened
+with ``O_NONBLOCK`` flag set, the process does not block, and an error is
+returned. If the ``O_NONBLOCK`` flag was not set, the process does block and
+wait for space on the queue.
Receiving a Message from a Message Queue
----------------------------------------
-The mq_receive() function is used to receive the oldest of the highest
-priority message(s) from the message queue specified by mqdes. The
-messages are received in FIFO order within the priorities. The received
-message's priority is stored in the location referenced by the msg_prio.
-If the msg_prio is a NULL, the priority is discarded. The message is
-removed and stored in an area pointed to by msg_ptr whose length is of
-msg_len. The msg_len must be at least equal to the mq_msgsize attribute
-of the message queue.
-
-The blocking behavior of the message queue is set by O_NONBLOCK at mq_open
-or by setting O_NONBLOCK in mq_flags in a call to mq_setattr. If this is
-a blocking queue, the process does block and wait on an empty queue. If
-this a non-blocking queue, the process does not block. Upon successful
-completion, mq_receive returns the length of the selected message in bytes
-and the message is removed from the queue.
+The ``mq_receive()`` function is used to receive the oldest of the highest
+priority message(s) from the message queue specified by mqdes. The messages are
+received in FIFO order within the priorities. The received message's priority
+is stored in the location referenced by the ``msg_prio``. If the ``msg_prio``
+is a ``NULL``, the priority is discarded. The message is removed and stored in
+an area pointed to by ``msg_ptr`` whose length is of ``msg_len``. The
+``msg_len`` must be at least equal to the ``mq_msgsize`` attribute of the
+message queue.
+
+The blocking behavior of the message queue is set by ``O_NONBLOCK`` at
+``mq_open`` or by setting ``O_NONBLOCK`` in ``mq_flags`` in a call to
+``mq_setattr``. If this is a blocking queue, the process does block and wait on
+an empty queue. If this a non-blocking queue, the process does not block. Upon
+successful completion, ``mq_receive`` returns the length of the selected
+message in bytes and the message is removed from the queue.
Notification of Receipt of a Message on an Empty Queue
------------------------------------------------------
-The mq_notify() function registers the calling process to be notified of
-message arrival at an empty message queue. Every message queue has the
-ability to notify one (and only one) process whenever the queue's state
-changes from empty (0 messages) to nonempty. This means that the process
-does not have to block or constantly poll while it waits for a message.
-By calling mq_notify, a notification request is attached to a message
-queue. When a message is received by an empty queue, if there are no
-processes blocked and waiting for the message, then the queue notifies the
-requesting process of a message arrival. There is only one signal sent by
-the message queue, after that the notification request is de-registered
-and another process can attach its notification request. After receipt of
-a notification, a process must re-register if it wishes to be notified
-again.
+The ``mq_notify()`` function registers the calling process to be notified of
+message arrival at an empty message queue. Every message queue has the ability
+to notify one (and only one) process whenever the queue's state changes from
+empty (0 messages) to nonempty. This means that the process does not have to
+block or constantly poll while it waits for a message. By calling
+``mq_notify``, a notification request is attached to a message queue. When a
+message is received by an empty queue, if there are no processes blocked and
+waiting for the message, then the queue notifies the requesting process of a
+message arrival. There is only one signal sent by the message queue, after that
+the notification request is de-registered and another process can attach its
+notification request. After receipt of a notification, a process must
+re-register if it wishes to be notified again.
-If there is a process blocked and waiting for the message, that process
-gets the message, and notification is not sent. Only one process can have
-a notification request attached to a message queue at any one time. If
-another process attempts to register a notification request, it fails.
-You can de-register for a message queue by passing a NULL to mq_notify,
-this removes any notification request attached to the queue. Whenever the
-message queue is closed, all notification attachments are removed.
+If there is a process blocked and waiting for the message, that process gets
+the message, and notification is not sent. Only one process can have a
+notification request attached to a message queue at any one time. If another
+process attempts to register a notification request, it fails. You can
+de-register for a message queue by passing a ``NULL`` to ``mq_notify``, this
+removes any notification request attached to the queue. Whenever the message
+queue is closed, all notification attachments are removed.
Setting the Attributes of a Message Queue
-----------------------------------------
-The mq_setattr() function is used to set attributes associated with the
+The ``mq_setattr()`` function is used to set attributes associated with the
open message queue description referenced by the message queue descriptor
-specified by mqdes. The \*omqstat represents the old or previous
-attributes. If omqstat is non-NULL, the function mq_setattr() stores, in
-the location referenced by omqstat, the previous message queue attributes
-and the current queue status. These values are the same as would be
-returned by a call to mq_getattr() at that point.
-
-There is only one mq_attr.mq_flag that can be altered by this call. This
-is the flag that deals with the blocking and non-blocking behavior of the
-message queue. If the flag is set then the message queue is non-blocking,
-and requests to send or receive do not block while waiting for resources.
-If the flag is not set, then message send and receive may involve waiting
-for an empty queue or waiting for a message to arrive.
+specified by mqdes. The ``*omqstat`` represents the old or previous
+attributes. If ``omqstat`` is non-``NULL``, the function ``mq_setattr()``
+stores, in the location referenced by omqstat, the previous message queue
+attributes and the current queue status. These values are the same as would be
+returned by a call to ``mq_getattr()`` at that point.
+
+There is only one ``mq_attr.mq_flag`` that can be altered by this call. This is
+the flag that deals with the blocking and non-blocking behavior of the message
+queue. If the flag is set then the message queue is non-blocking, and requests
+to send or receive do not block while waiting for resources. If the flag is
+not set, then message send and receive may involve waiting for an empty queue
+or waiting for a message to arrive.
Getting the Attributes of a Message Queue
-----------------------------------------
-The mq_getattr() function is used to get status information and attributes
-of the message queue associated with the message queue descriptor. The
-results are returned in the mq_attr structure referenced by the mqstat
-argument. All of these attributes are set at create time, except the
-blocking/non-blocking behavior of the message queue which can be
-dynamically set by using mq_setattr. The attribute mq_curmsg is set to
-reflect the number of messages on the queue at the time that mq_getattr
-was called.
+The ``mq_getattr()`` function is used to get status information and attributes
+of the message queue associated with the message queue descriptor. The results
+are returned in the mq_attr structure referenced by the mqstat argument. All of
+these attributes are set at create time, except the blocking/non-blocking
+behavior of the message queue which can be dynamically set by using
+mq_setattr. The attribute mq_curmsg is set to reflect the number of messages on
+the queue at the time that ``mq_getattr`` was called.
Directives
==========
-This section details the message passing manager's directives. A
-subsection is dedicated to each of this manager's directives and describes
-the calling sequence, related constants, usage, and status codes.
+This section details the message passing manager's directives. A subsection is
+dedicated to each of this manager's directives and describes the calling
+sequence, related constants, usage, and status codes.
+
+.. _mq_open:
mq_open - Open a Message Queue
------------------------------
@@ -276,87 +281,99 @@ mq_open - Open a Message Queue
**CALLING SEQUENCE:**
-.. code:: c
+.. code-block:: c
#include <mqueue.h>
mqd_t mq_open(
- const char \*name,
- int oflag,
- mode_t mode,
- struct mq_attr \*attr
+ const char *name,
+ int oflag,
+ mode_t mode,
+ struct mq_attr *attr
);
**STATUS CODES:**
-``EACCES`` - Either the message queue exists and the permissions
-requested in oflags were denied, or the message does not exist and
-permission to create one is denied.
-
-``EEXIST`` - You tried to create a message queue that already exists.
-
-``EINVAL`` - An inappropriate name was given for the message queue, or
-the values of mq-maxmsg or mq_msgsize were less than 0.
-
-``ENOENT`` - The message queue does not exist, and you did not specify
-to create it.
-
-``EINTR`` - The call to mq_open was interrupted by a signal.
-
-``EMFILE`` - The process has too many files or message queues open.
-This is a process limit error.
-
-``ENFILE`` - The system has run out of resources to support more open
-message queues. This is a system error.
-
-``ENAMETOOLONG`` - mq_name is too long.
+.. list-table::
+ :class: rtems-table
+
+ * - ``EACCES``
+ - Either the message queue exists and the permissions requested in
+ ``oflags`` were denied, or the message does not exist and permission to
+ create one is denied.
+ * - ``EEXIST``
+ - You tried to create a message queue that already exists.
+ * - ``EINVAL``
+ - An inappropriate name was given for the message queue, or the values of
+ ``mq-maxmsg`` or ``mq_msgsize`` were less than 0.
+ * - ``ENOENT``
+ - The message queue does not exist, and you did not specify to create it.
+ * - ``EINTR``
+ - The call to mq_open was interrupted by a signal.
+ * - ``EMFILE``
+ - The process has too many files or message queues open. This is a process
+ limit error.
+ * - ``ENFILE``
+ - The system has run out of resources to support more open message
+ queues. This is a system error.
+ * - ``ENAMETOOLONG``
+ - ``mq_name`` is too long.
**DESCRIPTION:**
-The mq_open () function establishes the connection between a process and a
-message queue with a message queue descriptor. If the message queue
-already exists, mq_open opens it, if the message queue does not exist,
-mq_open creates it. Message queues can have multiple senders and
-receivers. If mq_open is successful, the function returns a message queue
-descriptor. Otherwise, the function returns a -1 and sets 'errno' to
-indicate the error.
+The ``mq_open()`` function establishes the connection between a process and a
+message queue with a message queue descriptor. If the message queue already
+exists, ``mq_open`` opens it, if the message queue does not exist, ``mq_open``
+creates it. Message queues can have multiple senders and receivers. If
+``mq_open`` is successful, the function returns a message queue
+descriptor. Otherwise, the function returns a -1 and sets ``errno`` to indicate
+the error.
The name of the message queue is used as an argument. For the best of
-portability, the name of the message queue should begin with a "/" and no
-other "/" should be in the name. Different systems interpret the name in
-different ways.
+portability, the name of the message queue should begin with a "/" and no other
+"/" should be in the name. Different systems interpret the name in different
+ways.
-The oflags contain information on how the message is opened if the queue
-already exists. This may be O_RDONLY for read only, O_WRONLY for write
+The ``oflags`` contain information on how the message is opened if the queue
+already exists. This may be ``O_RDONLY`` for read only, ``O_WRONLY`` for write
only, of O_RDWR, for read and write.
-In addition, the oflags contain information needed in the creation of a
-message queue. ``O_NONBLOCK`` - If the non-block flag is set then the
-message queue is non-blocking, and requests to send and receive messages
-do not block waiting for resources. If the flag is not set then the
-message queue is blocking, and a request to send might have to wait for an
-empty message queue. Similarly, a request to receive might have to wait
-for a message to arrive on the queue. ``O_CREAT`` - This call specifies
-that the call the mq_open is to create a new message queue. In this case
-the mode and attribute arguments of the function call are utilized. The
-message queue is created with a mode similar to the creation of a file,
-read and write permission creator, group, and others.
-
-The geometry of the message queue is contained in the attribute structure.
-This includes mq_msgsize that dictates the maximum size of a single
-message, and the mq_maxmsg that dictates the maximum number of messages
-the queue can hold at one time. If a NULL is used in the mq_attr
-argument, then the message queue is created with implementation defined
-defaults. ``O_EXCL`` - is always set if O_CREAT flag is set. If the
-message queue already exists, O_EXCL causes an error message to be
-returned, otherwise, the new message queue fails and appends to the
-existing one.
+In addition, the ``oflags`` contain information needed in the creation of a message
+queue.
+
+.. list-table::
+ :class: rtems-table
+
+ * - ``O_NONBLOCK``
+ - If the non-block flag is set then the message queue is non-blocking, and
+ requests to send and receive messages do not block waiting for
+ resources. If the flag is not set then the message queue is blocking, and
+ a request to send might have to wait for an empty message
+ queue. Similarly, a request to receive might have to wait for a message to
+ arrive on the queue.
+ * - ``O_CREAT``
+ - This call specifies that the call the mq_open is to create a new message
+ queue. In this case the mode and attribute arguments of the function call
+ are utilized. The message queue is created with a mode similar to the
+ creation of a file, read and write permission creator, group, and others.
+ The geometry of the message queue is contained in the attribute structure.
+ This includes mq_msgsize that dictates the maximum size of a single
+ message, and the mq_maxmsg that dictates the maximum number of messages
+ the queue can hold at one time. If a ``NULL`` is used in the mq_attr
+ argument, then the message queue is created with implementation defined
+ defaults.
+ * - ``O_EXCL``
+ - is always set if ``O_CREAT`` flag is set. If the message queue already
+ exists, ``O_EXCL`` causes an error message to be returned, otherwise, the
+ new message queue fails and appends to the existing one.
**NOTES:**
-The mq_open () function does not add or remove messages from the queue.
-When a new message queue is being created, the mq_flag field of the
+The ``mq_open()`` function does not add or remove messages from the queue.
+When a new message queue is being created, the ``mq_flag`` field of the
attribute structure is not used.
+.. _mq_close:
+
mq_close - Close a Message Queue
--------------------------------
.. index:: mq_close
@@ -364,32 +381,37 @@ mq_close - Close a Message Queue
**CALLING SEQUENCE:**
-.. code:: c
+.. code-block:: c
#include <mqueue.h>
int mq_close(
- mqd_t mqdes
+ mqd_t mqdes
);
**STATUS CODES:**
-``EINVAL`` - The descriptor does not represent a valid open message
-queue
+.. list-table::
+ :class: rtems-table
+
+ * - ``EINVAL``
+ - The descriptor does not represent a valid open message queue
**DESCRIPTION:**
-The mq_close function removes the association between the message queue
-descriptor, mqdes, and its message queue. If mq_close() is successfully
+The ``mq_close`` function removes the association between the message queue
+descriptor, mqdes, and its message queue. If ``mq_close()`` is successfully
completed, the function returns a value of zero; otherwise, the function
-returns a value of -1 and sets errno to indicate the error.
+returns a value of -1 and sets ``errno`` to indicate the error.
**NOTES:**
-If the process had successfully attached a notification request to the
-message queue via mq_notify, this attachment is removed, and the message
-queue is available for another process to attach for notification.
-mq_close has no effect on the contents of the message queue, all the
-messages that were in the queue remain in the queue.
+If the process had successfully attached a notification request to the message
+queue via ``mq_notify``, this attachment is removed, and the message queue is
+available for another process to attach for notification. ``mq_close`` has no
+effect on the contents of the message queue, all the messages that were in the
+queue remain in the queue.
+
+.. _mq_unlink:
mq_unlink - Remove a Message Queue
----------------------------------
@@ -398,36 +420,42 @@ mq_unlink - Remove a Message Queue
**CALLING SEQUENCE:**
-.. code:: c
+.. code-block:: c
#include <mqueue.h>
int mq_unlink(
- const char \*name
+ const char *name
);
**STATUS CODES:**
-``EINVAL`` - The descriptor does not represent a valid message queue
+.. list-table::
+ :class: rtems-table
+
+ * - ``EINVAL``
+ - The descriptor does not represent a valid message queue
**DESCRIPTION:**
-The mq_unlink() function removes the named message queue. If the message
-queue is not open when mq_unlink is called, then the queue is immediately
-eliminated. Any messages that were on the queue are lost, and the queue
-can not be opened again. If processes have the queue open when mq_unlink
-is called, the removal of the queue is delayed until the last process
-using the queue has finished. However, the name of the message queue is
-removed so that no other process can open it. Upon successful completion,
-the function returns a value of zero. Otherwise, the named message queue
-is not changed by this function call, and the function returns a value of
--1 and sets errno to indicate the error.
+The ``mq_unlink()`` function removes the named message queue. If the message
+queue is not open when ``mq_unlink`` is called, then the queue is immediately
+eliminated. Any messages that were on the queue are lost, and the queue can not
+be opened again. If processes have the queue open when ``mq_unlink`` is called,
+the removal of the queue is delayed until the last process using the queue has
+finished. However, the name of the message queue is removed so that no other
+process can open it. Upon successful completion, the function returns a value
+of zero. Otherwise, the named message queue is not changed by this function
+call, and the function returns a value of
+-1 and sets ``errno`` to indicate the error.
**NOTES:**
-Calls to mq_open() to re-create the message queue may fail until the
-message queue is actually removed. However, the mq_unlink() call need not
+Calls to ``mq_open()`` to re-create the message queue may fail until the
+message queue is actually removed. However, the ``mq_unlink()`` call need not
block until all references have been closed; it may return immediately.
+.. _mq_send:
+
mq_send - Send a Message to a Message Queue
-------------------------------------------
.. index:: mq_send
@@ -435,44 +463,63 @@ mq_send - Send a Message to a Message Queue
**CALLING SEQUENCE:**
-.. code:: c
+.. code-block:: c
#include<mqueue.h>
int mq_send(
- mqd_t mqdes,
- const char \*msg_ptr,
- size_t msg_len,
- unsigned int msg_prio
+ mqd_t mqdes,
+ const char *msg_ptr,
+ size_t msg_len,
+ unsigned int msg_prio
);
**STATUS CODES:**
-``EBADF`` - The descriptor does not represent a valid message queue, or the queue was opened for read only O_RDONLY``EINVAL`` - The value of msg_prio was greater than the MQ_PRIO_MAX.``EMSGSIZE`` - The msg_len is greater than the mq_msgsize attribute of the message queue``EAGAIN`` - The message queue is non-blocking, and there is no room on the queue for another message as specified by the mq_maxmsg.``EINTR`` - The message queue is blocking. While the process was waiting for free space on the queue, a signal arrived that interrupted the wait.
+.. list-table::
+ :class: rtems-table
+
+ * - ``EBADF``
+ - The descriptor does not represent a valid message queue, or the queue was
+ opened for read only ``O_RDONLY``
+ * - ``EINVAL``
+ - The value of msg_prio was greater than the ``MQ_PRIO_MAX``.
+ * - ``EMSGSIZE``
+ - The msg_len is greater than the ``mq_msgsize`` attribute of the message
+ queue
+ * - ``EAGAIN``
+ - The message queue is non-blocking, and there is no room on the queue for
+ another message as specified by the ``mq_maxmsg``.
+ * - ``EINTR``
+ - The message queue is blocking. While the process was waiting for free
+ space on the queue, a signal arrived that interrupted the wait.
**DESCRIPTION:**
-The mq_send() function adds the message pointed to by the argument msg_ptr
-to the message queue specified by mqdes. Each message is assigned a
-priority , from 0 to MQ_PRIO_MAX. MQ_PRIO_MAX is defined in <limits.h> and
-must be at least 32. Messages are added to the queue in order of their
-priority. The highest priority message is at the front of the queue.
-
-The maximum number of messages that a message queue may accept is
-specified at creation by the mq_maxmsg field of the attribute structure.
-If this amount is exceeded, the behavior of the process is determined
-according to what oflag was used when the message queue was opened. If
-the queue was opened with O_NONBLOCK flag set, then the EAGAIN error is
-returned. If the O_NONBLOCK flag was not set, the process blocks and
-waits for space on the queue, unless it is interrupted by a signal.
-
-Upon successful completion, the mq_send () function returns a value of
-zero. Otherwise, no message is enqueued, the function returns -1, and
-errno is set to indicate the error.
+The ``mq_send()`` function adds the message pointed to by the argument
+``msg_ptr`` to the message queue specified by mqdes. Each message is assigned a
+priority , from 0 to ``MQ_PRIO_MAX``. ``MQ_PRIO_MAX`` is defined in
+``<limits.h>`` and must be at least 32. Messages are added to the queue in
+order of their priority. The highest priority message is at the front of the
+queue.
+
+The maximum number of messages that a message queue may accept is specified at
+creation by the ``mq_maxmsg`` field of the attribute structure. If this amount is
+exceeded, the behavior of the process is determined according to what oflag was
+used when the message queue was opened. If the queue was opened with ``O_NONBLOCK``
+flag set, then the ``EAGAIN`` error is returned. If the ``O_NONBLOCK`` flag was not
+set, the process blocks and waits for space on the queue, unless it is
+interrupted by a signal.
+
+Upon successful completion, the ``mq_send()`` function returns a value of
+zero. Otherwise, no message is enqueued, the function returns -1, and ``errno``
+is set to indicate the error.
**NOTES:**
-If the specified message queue is not full, mq_send inserts the message at
-the position indicated by the msg_prio argument.
+If the specified message queue is not full, ``mq_send`` inserts the message at
+the position indicated by the ``msg_prio`` argument.
+
+.. _mq_receive:
mq_receive - Receive a Message from a Message Queue
---------------------------------------------------
@@ -481,46 +528,60 @@ mq_receive - Receive a Message from a Message Queue
**CALLING SEQUENCE:**
-.. code:: c
+.. code-block:: c
#include <mqueue.h>
size_t mq_receive(
- mqd_t mqdes,
- char \*msg_ptr,
- size_t msg_len,
- unsigned int \*msg_prio
+ mqd_t mqdes,
+ char *msg_ptr,
+ size_t msg_len,
+ unsigned int *msg_prio
);
**STATUS CODES:**
-``EBADF`` - The descriptor does not represent a valid message queue, or the queue was opened for write only O_WRONLY``EMSGSIZE`` - The msg_len is less than the mq_msgsize attribute of the message queue``EAGAIN`` - The message queue is non-blocking, and the queue is empty``EINTR`` - The message queue is blocking. While the process was waiting for a message to arrive on the queue, a signal arrived that interrupted the wait.
+.. list-table::
+ :class: rtems-table
+
+ * - ``EBADF``
+ - The descriptor does not represent a valid message queue, or the queue was
+ opened for write only ``O_WRONLY``
+ * - ``EMSGSIZE``
+ - The msg_len is less than the ``mq_msgsize`` attribute of the message queue
+ * - ``EAGAIN``
+ - The message queue is non-blocking, and the queue is empty
+ * - ``EINTR``
+ - The message queue is blocking. While the process was waiting for a message
+ to arrive on the queue, a signal arrived that interrupted the wait.
**DESCRIPTION:**
-The mq_receive function is used to receive the oldest of the highest
-priority message(s) from the message queue specified by mqdes. The
-messages are received in FIFO order within the priorities. The received
-message's priority is stored in the location referenced by the msg_prio.
-If the msg_prio is a NULL, the priority is discarded. The message is
-removed and stored in an area pointed to by msg_ptr whose length is of
-msg_len. The msg_len must be at least equal to the mq_msgsize attribute
-of the message queue.
-
-The blocking behavior of the message queue is set by O_NONBLOCK at mq_open
-or by setting O_NONBLOCK in mq_flags in a call to mq_setattr. If this is
-a blocking queue, the process blocks and waits on an empty queue. If this
-a non-blocking queue, the process does not block.
-
-Upon successful completion, mq_receive returns the length of the selected
+The ``mq_receive`` function is used to receive the oldest of the highest
+priority message(s) from the message queue specified by mqdes. The messages are
+received in FIFO order within the priorities. The received message's priority
+is stored in the location referenced by the ``msg_prio``. If the ``msg_prio``
+is a ``NULL``, the priority is discarded. The message is removed and stored in
+an area pointed to by ``msg_ptr`` whose length is of ``msg_len``. The
+``msg_len`` must be at least equal to the mq_msgsize attribute of the message
+queue.
+
+The blocking behavior of the message queue is set by ``O_NONBLOCK`` at
+``mq_open`` or by setting ``O_NONBLOCK`` in ``mq_flags`` in a call to
+``mq_setattr``. If this is a blocking queue, the process blocks and waits on an
+empty queue. If this a non-blocking queue, the process does not block.
+
+Upon successful completion, ``mq_receive`` returns the length of the selected
message in bytes and the message is removed from the queue. Otherwise, no
-message is removed from the queue, the function returns a value of -1, and
-sets errno to indicate the error.
+message is removed from the queue, the function returns a value of -1, and sets
+``errno`` to indicate the error.
**NOTES:**
-If the size of the buffer in bytes, specified by the msg_len argument, is
-less than the mq_msgsize attribute of the message queue, the function
-fails and returns an error
+If the size of the buffer in bytes, specified by the ``msg_len`` argument, is
+less than the ``mq_msgsize`` attribute of the message queue, the function fails
+and returns an error
+
+.. _mq_notify:
mq_notify - Notify Process that a Message is Available
------------------------------------------------------
@@ -529,35 +590,40 @@ mq_notify - Notify Process that a Message is Available
**CALLING SEQUENCE:**
-.. code:: c
+.. code-block:: c
#include <mqueue.h>
int mq_notify(
- mqd_t mqdes,
- const struct sigevent \*notification
+ mqd_t mqdes,
+ const struct sigevent *notification
);
**STATUS CODES:**
-``EBADF`` - The descriptor does not refer to a valid message queue``EBUSY`` - A notification request is already attached to the queue
+.. list-table::
+ :class: rtems-table
+
+ * - ``EBADF``
+ - The descriptor does not refer to a valid message queue
+ * - ``EBUSY``
+ - A notification request is already attached to the queue
**DESCRIPTION:**
-If the argument notification is not NULL, this function registers the
-calling process to be notified of message arrival at an empty message
-queue associated with the specified message queue descriptor, mqdes.
+If the argument notification is not ``NULL``, this function registers the
+calling process to be notified of message arrival at an empty message queue
+associated with the specified message queue descriptor, ``mqdes``.
Every message queue has the ability to notify one (and only one) process
-whenever the queue's state changes from empty (0 messages) to nonempty.
-This means that the process does not have to block or constantly poll
-while it waits for a message. By calling mq_notify, a notification
-request is attached to a message queue. When a message is received by an
-empty queue, if there are no processes blocked and waiting for the
-message, then the queue notifies the requesting process of a message
-arrival. There is only one signal sent by the message queue, after that
-the notification request is de-registered and another process can attach
-its notification request. After receipt of a notification, a process must
-re-register if it wishes to be notified again.
+whenever the queue's state changes from empty (0 messages) to nonempty. This
+means that the process does not have to block or constantly poll while it waits
+for a message. By calling ``mq_notify``, a notification request is attached to
+a message queue. When a message is received by an empty queue, if there are no
+processes blocked and waiting for the message, then the queue notifies the
+requesting process of a message arrival. There is only one signal sent by the
+message queue, after that the notification request is de-registered and another
+process can attach its notification request. After receipt of a notification, a
+process must re-register if it wishes to be notified again.
If there is a process blocked and waiting for the message, that process
gets the message, and notification is not be sent. Only one process can
@@ -567,12 +633,16 @@ You can de-register for a message queue by passing a NULL to mq_notify;
this removes any notification request attached to the queue. Whenever the
message queue is closed, all notification attachments are removed.
-Upon successful completion, mq_notify returns a value of zero; otherwise,
-the function returns a value of -1 and sets errno to indicate the error.
+Upon successful completion, mq_notify returns a value of zero; otherwise, the
+function returns a value of -1 and sets ``errno`` to indicate the error.
**NOTES:**
-It is possible for another process to receive the message after the notification is sent but before the notified process has sent its receive request.
+It is possible for another process to receive the message after the
+notification is sent but before the notified process has sent its receive
+request.
+
+.. _mq_setattr:
mq_setattr - Set Message Queue Attributes
-----------------------------------------
@@ -581,44 +651,52 @@ mq_setattr - Set Message Queue Attributes
**CALLING SEQUENCE:**
-.. code:: c
+.. code-block:: c
#include <mqueue.h>
int mq_setattr(
- mqd_t mqdes,
- const struct mq_attr \*mqstat,
- struct mq_attr \*omqstat
+ mqd_t mqdes,
+ const struct mq_attr *mqstat,
+ struct mq_attr *omqstat
);
**STATUS CODES:**
-``EBADF`` - The message queue descriptor does not refer to a valid, open queue.``EINVAL`` - The mq_flag value is invalid.
+.. list-table::
+ :class: rtems-table
+
+ * - ``EBADF``
+ - The message queue descriptor does not refer to a valid, open queue.
+ * - ``EINVAL``
+ - The mq_flag value is invalid.
**DESCRIPTION:**
-The mq_setattr function is used to set attributes associated with the open
-message queue description referenced by the message queue descriptor
-specified by mqdes. The \*omqstat represents the old or previous
-attributes. If omqstat is non-NULL, the function mq_setattr() stores, in
-the location referenced by omqstat, the previous message queue attributes
-and the current queue status. These values are the same as would be
-returned by a call to mq_getattr() at that point.
-
-There is only one mq_attr.mq_flag which can be altered by this call.
-This is the flag that deals with the blocking and non-blocking behavior of
-the message queue. If the flag is set then the message queue is
-non-blocking, and requests to send or receive do not block while waiting
-for resources. If the flag is not set, then message send and receive may
-involve waiting for an empty queue or waiting for a message to arrive.
+The ``mq_setattr`` function is used to set attributes associated with the open
+message queue description referenced by the message queue descriptor specified
+by mqdes. The ``*omqstat`` represents the old or previous attributes. If
+``omqstat`` is non-``NULL``, the function ``mq_setattr()`` stores, in the
+location referenced by ``omqstat``, the previous message queue attributes and
+the current queue status. These values are the same as would be returned by a
+call to ``mq_getattr()`` at that point.
+
+There is only one mq_attr.mq_flag which can be altered by this call. This is
+the flag that deals with the blocking and non-blocking behavior of the message
+queue. If the flag is set then the message queue is non-blocking, and requests
+to send or receive do not block while waiting for resources. If the flag is not
+set, then message send and receive may involve waiting for an empty queue or
+waiting for a message to arrive.
Upon successful completion, the function returns a value of zero and the
-attributes of the message queue have been changed as specified.
-Otherwise, the message queue attributes is unchanged, and the function
-returns a value of -1 and sets errno to indicate the error.
+attributes of the message queue have been changed as specified. Otherwise, the
+message queue attributes is unchanged, and the function returns a value of -1
+and sets ``errno`` to indicate the error.
**NOTES:**
-All other fields in the mq_attr are ignored by this call.
+All other fields in the ``mq_attr`` are ignored by this call.
+
+.. _mq_getattr:
mq_getattr - Get Message Queue Attributes
-----------------------------------------
@@ -627,39 +705,35 @@ mq_getattr - Get Message Queue Attributes
**CALLING SEQUENCE:**
-.. code:: c
+.. code-block:: c
#include <mqueue.h>
int mq_getattr(
- mqd_t mqdes,
- struct mq_attr \*mqstat
+ mqd_t mqdes,
+ struct mq_attr *mqstat
);
**STATUS CODES:**
-``EBADF`` - The message queue descriptor does not refer to a valid,
-open message queue.
+.. list-table::
+ :class: rtems-table
+
+ * - ``EBADF``
+ - The message queue descriptor does not refer to a valid, open message
+ queue.
**DESCRIPTION:**
-The mqdes argument specifies a message queue descriptor. The mq_getattr
-function is used to get status information and attributes of the message
-queue associated with the message queue descriptor. The results are
-returned in the mq_attr structure referenced by the mqstat argument. All
-of these attributes are set at create time, except the
-blocking/non-blocking behavior of the message queue which can be
-dynamically set by using mq_setattr. The attribute mq_curmsg is set to
-reflect the number of messages on the queue at the time that mq_getattr
-was called.
+The ``mqdes`` argument specifies a message queue descriptor. The ``mq_getattr``
+function is used to get status information and attributes of the message queue
+associated with the message queue descriptor. The results are returned in the
+``mq_attr`` structure referenced by the mqstat argument. All of these
+attributes are set at create time, except the blocking/non-blocking behavior of
+the message queue which can be dynamically set by using mq_setattr. The
+attribute ``mq_curmsg`` is set to reflect the number of messages on the queue
+at the time that ``mq_getattr`` was called.
-Upon successful completion, the mq_getattr function returns zero.
-Otherwise, the function returns -1 and sets errno to indicate the error.
+Upon successful completion, the ``mq_getattr`` function returns zero.
+Otherwise, the function returns -1 and sets ``errno`` to indicate the error.
**NOTES:**
-
-.. COMMENT: COPYRIGHT (c) 1988-2014.
-
-.. COMMENT: On-Line Applications Research Corporation (OAR).
-
-.. COMMENT: All rights reserved.
-
diff --git a/posix_users/mutex.rst b/posix_users/mutex.rst
index 0198664..2116f63 100644
--- a/posix_users/mutex.rst
+++ b/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
-manager as defined by POSIX 1003.1b-1996. This standard requires that
-a compliant operating system provide the facilties to ensure that
-threads can operate with mutual exclusion from one another and
-defines the API that must be provided.
+The mutex manager implements the functionality required of the mutex manager as
+defined by POSIX 1003.1b-1996. This standard requires that a compliant
+operating system provide the facilties to ensure that threads can operate with
+mutual exclusion from one another and 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
-attribute structure may be initialized and passed as an argument to
-the ``mutex_init`` routine. Note that the priority ceiling of
-a mutex may be set at run-time.
-
-*blocking protcol*
- is the XXX
+Mutex attributes are utilized only at mutex creation time. A mutex attribute
+structure may be initialized and passed as an argument to the ``mutex_init``
+routine. Note that the priority ceiling of a mutex may be set at run-time.
-*priority ceiling*
- is the XXX
+.. list-table::
+ :class: rtems-table
-*pshared*
- is the XXX
+ * - *blocking protcol*
+ - is the XXX
+ * - *priority ceiling*
+ - is the XXX
+ * - *pshared*
+ - is the XXX
PTHREAD_MUTEX_INITIALIZER
-------------------------
-This is a special value that a variable of type ``pthread_mutex_t``
-may be statically initialized to as shown below:
-.. code:: c
+This is a special value that a variable of type ``pthread_mutex_t`` may be
+statically initialized to as shown below:
+
+.. code-block:: c
pthread_mutex_t my_mutex = PTHREAD_MUTEX_INITIALIZER;
-This indicates that ``my_mutex`` will be automatically initialized
-by an implicit call to ``pthread_mutex_init`` the first time
-the mutex is used.
+This indicates that ``my_mutex`` will be automatically initialized by an
+implicit call to ``pthread_mutex_init`` the first time 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.
-A subsection is dedicated to each of this manager's services
-and describes the calling sequence, related constants, usage,
-and status codes.
+This section details the mutex manager's services. A subsection is dedicated
+to each of this manager's services and describes the calling sequence, related
+constants, usage, and status codes.
+
+.. _pthread_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
-object specified by ``attr`` with the default value for all of the
-individual attributes.
+The ``pthread_mutexattr_init`` routine initializes the mutex attributes object
+specified by ``attr`` with the default value for all of the individual
+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(
- pthread_mutexattr_t \*attr
+ int pthread_mutexattr_destroy(
+ pthread_mutexattr_t *attr
);
**STATUS CODES:**
-*EINVAL*
- The attribute pointer argument is invalid.
+.. list-table::
+ :class: rtems-table
-*EINVAL*
- The attribute set is not initialized.
+ * - ``EINVAL``
+ - 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
-it is destroyed is implementation dependent.
+attributes object. The behavior of using an attributes object after it is
+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,
- int protocol
+ pthread_mutexattr_t *attr,
+ int protocol
);
**STATUS CODES:**
-*EINVAL*
- The attribute pointer argument is invalid.
-
-*EINVAL*
- The attribute set is not initialized.
+.. list-table::
+ :class: rtems-table
-*EINVAL*
- The protocol argument is invalid.
+ * - ``EINVAL``
+ - The attribute pointer argument is invalid.
+ * - ``EINVAL``
+ - The attribute set is not initialized.
+ * - ``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
-threads waiting on this mutex will receive it.
+The ``pthread_mutexattr_setprotocol`` routine is used to set value of the
+``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``*
- in which case blocking order is FIFO.
-
-*``PTHREAD_PRIO_INHERIT``*
- in which case blocking order is priority with the priority inheritance
- protocol in effect.
+.. list-table::
+ :class: rtems-table
-*``PTHREAD_PRIO_PROTECT``*
- in which case blocking order is priority with the priority ceiling
- protocol in effect.
+ * - ``PTHREAD_PRIO_NONE``
+ - in which case blocking order is FIFO.
+ * - ``PTHREAD_PRIO_INHERIT``
+ - in which case blocking order is priority with the priority inheritance
+ protocol in effect.
+ * - ``PTHREAD_PRIO_PROTECT``
+ - 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
-with POSIX mutexes even though this could easily by supported by RTEMS.
+There is currently no way to get simple priority blocking ordering with POSIX
+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,
- int \*protocol
+ pthread_mutexattr_t *attr,
+ int *protocol
);
**STATUS CODES:**
-*EINVAL*
- The attribute pointer argument is invalid.
-
-*EINVAL*
- The attribute set is not initialized.
+.. list-table::
+ :class: rtems-table
-*EINVAL*
- The protocol pointer argument is invalid.
+ * - ``EINVAL``
+ - The attribute pointer argument is invalid.
+ * - ``EINVAL``
+ - The attribute set is not initialized.
+ * - ``EINVAL``
+ - The protocol pointer argument is invalid.
**DESCRIPTION:**
-The ``pthread_mutexattr_getprotocol`` routine is used to obtain
-the value of the ``protocol`` attribute. This attribute controls
-the order in which threads waiting on this mutex will receive it.
+The ``pthread_mutexattr_getprotocol`` routine is used to obtain the value of
+the ``protocol`` attribute. This attribute controls the order in which threads
+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,
- int prioceiling
+ pthread_mutexattr_t *attr,
+ int prioceiling
);
**STATUS CODES:**
-*EINVAL*
- The attribute pointer argument is invalid.
-
-*EINVAL*
- The attribute set is not initialized.
+.. list-table::
+ :class: rtems-table
-*EINVAL*
- The prioceiling argument is invalid.
+ * - ``EINVAL``
+ - The attribute pointer argument is invalid.
+ * - ``EINVAL``
+ - The attribute set is not initialized.
+ * - ``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
-is the ceiling for threads obtaining this mutex. Any task obtaining this
-mutex may not be of greater priority that the ceiling. If it is of lower
-priority, then its priority will be elevated to ``prioceiling``.
+The ``pthread_mutexattr_setprioceiling`` routine is used to set value of the
+``prioceiling`` attribute. This attribute specifies the priority that is the
+ceiling for threads obtaining this mutex. Any task obtaining this mutex may not
+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,
- int \*prioceiling
+ const pthread_mutexattr_t *attr,
+ int *prioceiling
);
**STATUS CODES:**
-*EINVAL*
- The attribute pointer argument is invalid.
+.. list-table::
+ :class: rtems-table
-*EINVAL*
- The attribute set is not initialized.
-
-*EINVAL*
- The prioceiling pointer argument is invalid.
+ * - ``EINVAL``
+ - The attribute pointer argument is invalid.
+ * - ``EINVAL``
+ - The attribute set is not initialized.
+ * - ``EINVAL``
+ - The prioceiling pointer argument is invalid.
**DESCRIPTION:**
-The ``pthread_mutexattr_getprioceiling`` routine is used to obtain the
-value of the ``prioceiling`` attribute. This attribute specifies the
-priority ceiling for this mutex.
+The ``pthread_mutexattr_getprioceiling`` routine is used to obtain the value of
+the ``prioceiling`` attribute. This attribute specifies the priority ceiling
+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,
- int pshared
+ pthread_mutexattr_t *attr,
+ int pshared
);
**STATUS CODES:**
-*EINVAL*
- The attribute pointer argument is invalid.
+.. list-table::
+ :class: rtems-table
-*EINVAL*
- The attribute set is not initialized.
-
-*EINVAL*
- The pshared argument is invalid.
+ * - ``EINVAL``
+ - The attribute pointer argument is invalid.
+ * - ``EINVAL``
+ - The attribute set is not initialized.
+ * - ``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,
- int \*pshared
+ const pthread_mutexattr_t *attr,
+ int *pshared
);
**STATUS CODES:**
-*EINVAL*
- The attribute pointer argument is invalid.
+.. list-table::
+ :class: rtems-table
-*EINVAL*
- The attribute set is not initialized.
-
-*EINVAL*
- The pshared pointer argument is invalid.
+ * - ``EINVAL``
+ - The attribute pointer argument is invalid.
+ * - ``EINVAL``
+ - The attribute set is not initialized.
+ * - ``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,
- const pthread_mutexattr_t \*attr
+ pthread_mutex_t *mutex,
+ const pthread_mutexattr_t *attr
);
**STATUS CODES:**
-*EINVAL*
- The attribute set is not initialized.
-
-*EINVAL*
- The specified protocol is invalid.
-
-*EAGAIN*
- The system lacked the necessary resources to initialize another mutex.
-
-*ENOMEM*
- Insufficient memory exists to initialize the mutex.
-
-*EBUSY*
- Attempted to reinialize the object reference by mutex, a previously
- initialized, but not yet destroyed.
+.. list-table::
+ :class: rtems-table
+
+ * - ``EINVAL``
+ - The attribute set is not initialized.
+ * - ``EINVAL``
+ - The specified protocol is invalid.
+ * - ``EAGAIN``
+ - The system lacked the necessary resources to initialize another mutex.
+ * - ``ENOMEM``
+ - Insufficient memory exists to initialize the mutex.
+ * - ``EBUSY``
+ - Attempted to reinialize the object reference by mutex, a previously
+ 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(
- pthread_mutex_t \*mutex
+ int pthread_mutex_destroy(
+ pthread_mutex_t *mutex
);
**STATUS CODES:**
-*EINVAL*
- The specified mutex is invalid.
+.. list-table::
+ :class: rtems-table
-*EBUSY*
- Attempted to destroy the object reference by mutex, while it is locked or
- referenced by another thread.
+ * - ``EINVAL``
+ - The specified mutex is invalid.
+ * - ``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*
- The specified mutex is invalid.
-
-*EINVAL*
- The mutex has the protocol attribute of PTHREAD_PRIO_PROTECT and the
- priority of the calling thread is higher than the current priority
- ceiling.
+.. list-table::
+ :class: rtems-table
-*EDEADLK*
- The current thread already owns the mutex.
+ * - ``EINVAL``
+ - The specified mutex is invalid.
+ * - ``EINVAL``
+ - The mutex has the protocol attribute of ``PTHREAD_PRIO_PROTECT`` and the
+ priority of the calling thread is higher than the current priority
+ ceiling.
+ * - ``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*
- The specified mutex is invalid.
+.. list-table::
+ :class: rtems-table
-*EINVAL*
- 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*
- The mutex is already locked.
+ * - ``EINVAL``
+ - The specified mutex is invalid.
+ * - ``EINVAL``
+ - 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``
+ - 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,
- const struct timespec \*timeout
+ pthread_mutex_t *mutex,
+ const struct timespec *timeout
);
**STATUS CODES:**
-*EINVAL*
- The specified mutex is invalid.
-
-*EINVAL*
- The nanoseconds field of timeout is invalid.
-
-*EINVAL*
- The mutex has the protocol attribute of PTHREAD_PRIO_PROTECT and the
- priority of the calling thread is higher than the current priority
- ceiling.
-
-*EDEADLK*
- The current thread already owns the mutex.
-
-*ETIMEDOUT*
- The calling thread was unable to obtain the mutex within the specified
- timeout period.
+.. list-table::
+ :class: rtems-table
+
+ * - ``EINVAL``
+ - The specified mutex is invalid.
+ * - ``EINVAL``
+ - The nanoseconds field of timeout is invalid.
+ * - ``EINVAL``
+ - The mutex has the protocol attribute of ``PTHREAD_PRIO_PROTECT`` and the
+ priority of the calling thread is higher than the current priority
+ ceiling.
+ * - ``EDEADLK``
+ - The current thread already owns the mutex.
+ * - ``ETIMEDOUT``
+ - The calling thread was unable to obtain the mutex within the specified
+ 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*
- The specified mutex is invalid.
+.. list-table::
+ :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,
- int prioceiling,
- int \*oldceiling
+ pthread_mutex_t *mutex,
+ int prioceiling,
+ int *oldceiling
);
**STATUS CODES:**
-*EINVAL*
- The oldceiling pointer parameter is invalid.
-
-*EINVAL*
- The prioceiling parameter is an invalid priority.
+.. list-table::
+ :class: rtems-table
-*EINVAL*
- The specified mutex is invalid.
+ * - ``EINVAL``
+ - The oldceiling pointer parameter is invalid.
+ * - ``EINVAL``
+ - The prioceiling parameter is an invalid priority.
+ * - ``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,
- int \*prioceiling
+ pthread_mutex_t *mutex,
+ int *prioceiling
);
**STATUS CODES:**
-*EINVAL*
- The prioceiling pointer parameter is invalid.
+.. list-table::
+ :class: rtems-table
-*EINVAL*
- The specified mutex is invalid.
+ * - ``EINVAL``
+ - 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.
-
diff --git a/posix_users/preface.rst b/posix_users/preface.rst
index d4065b5..1d5fcd4 100644
--- a/posix_users/preface.rst
+++ b/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
-provided in RTEMS.
+This is the User's Guide for the POSIX API support provided in RTEMS.
-The functionality described in this document is based
-on the following standards:
+The functionality described in this document is based on the following
+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
-Cygnus Newlib ANSI C Library. Please refer to documentation on
-Newlib for more information on the functionality it supplies.
+Much of the POSIX API standard is actually implemented in the Cygnus Newlib
+ANSI C Library. Please refer to documentation on Newlib for more information
+on the functionality it supplies.
-This manual is still under construction and improvements
-are welcomed from users.
+This manual is still under construction and improvements are welcomed from
+users.
Acknowledgements
================
-.. COMMENT: COPYRIGHT (c) 1988-2009.
-
-.. COMMENT: On-Line Applications Research Corporation (OAR).
-
-.. COMMENT: All rights reserved.
-
-.. COMMENT: The RTEMS Project has been granted permission from The Open Group
-
-.. COMMENT: IEEE to excerpt and use portions of the POSIX standards documents
-
-.. COMMENT: in the RTEMS POSIX API User's Guide and RTEMS Shell User's Guide.
-
-.. COMMENT: We have to include a specific acknowledgement paragraph in these
-
-.. COMMENT: documents (e.g. preface or copyright page) and another slightly
-
-.. 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.
+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.
+
+This file should help ensure that the paragraphs are consistent 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 at
+ http://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.
-
diff --git a/posix_users/process_creation_and_execution.rst b/posix_users/process_creation_and_execution.rst
index 7ba4588..5701c44 100644
--- a/posix_users/process_creation_and_execution.rst
+++ b/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
-functionality associated with the creation and termination
-of processes.
+The process creation and execution manager provides the functionality
+associated with the creation and termination 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
-supported by RTEMS. This is because RTEMS provides no memory
-protection and implements a *single process, multi-threaded
-execution model*. In this light, RTEMS provides none of the
-routines that are associated with the creation of new processes.
-However, since the entire RTEMS application (e.g. executable)
-is logically a single POSIX process, RTEMS is able to provide
-implementations of many operations on processes. The rule of
-thumb is that those routines provide a meaningful result.
-For example, ``getpid()`` returns the node number.
+POSIX process functionality can not be completely supported by RTEMS. This is
+because RTEMS provides no memory protection and implements a *single process,
+multi-threaded execution model*. In this light, RTEMS provides none of the
+routines that are associated with the creation of new processes. However,
+since the entire RTEMS application (e.g. executable) is logically a single
+POSIX process, RTEMS is able to provide implementations of many operations on
+processes. The rule of 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
-supported by RTEMS is the ``_exit`` service. The
-implementation of ``_exit`` shuts the application down and
-is equivalent to invoking either ``exit`` or``rtems_shutdown_executive``.
+The only functionality method defined by this manager which is supported by
+RTEMS is the ``_exit`` service. The implementation of ``_exit`` shuts the
+application down and is equivalent to invoking either ``exit`` or
+``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
-and describes the calling sequence, related constants, usage,
-and status codes.
+A subsection is dedicated to each of this manager's directives and describes
+the calling sequence, related constants, usage, 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*
- This routine is not supported by RTEMS.
+.. list-table::
+ :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 \*arg,
- ...
+ const char *path,
+ const char *arg,
+ ...
);
**STATUS CODES:**
-*ENOSYS*
- This routine is not supported by RTEMS.
+.. list-table::
+ :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,
- char const \*argv[],
- ...
+ const char *path,
+ char const *argv[],
+ ...
);
**STATUS CODES:**
-*ENOSYS*
- This routine is not supported by RTEMS.
+.. list-table::
+ :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 \*arg,
- ...
+ const char *path,
+ const char *arg,
+ ...
);
**STATUS CODES:**
-*ENOSYS*
- This routine is not supported by RTEMS.
+.. list-table::
+ :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,
- char \*const argv[],
- char \*const envp[]
+ const char *path,
+ char *const argv[],
+ char *const envp[]
);
**STATUS CODES:**
-*ENOSYS*
- This routine is not supported by RTEMS.
+.. list-table::
+ :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 \*arg,
- ...
+ const char *file,
+ const char *arg,
+ ...
);
**STATUS CODES:**
-*ENOSYS*
- This routine is not supported by RTEMS.
+.. list-table::
+ :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,
- char \*const argv[]
- ...
+ const char *file,
+ char *const argv[],
+ ...
);
**STATUS CODES:**
-*ENOSYS*
- This routine is not supported by RTEMS.
+.. list-table::
+ :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 (\*parent)(void),
- void (\*child)(void)
+ void (*prepare)(void),
+ void (*parent)(void),
+ void (*child)(void)
);
**STATUS CODES:**
-*ENOSYS*
- This routine is not supported by RTEMS.
+.. list-table::
+ :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*
- This routine is not supported by RTEMS.
+.. list-table::
+ :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,
- int \*stat_loc,
- int options
+ pid_t pid,
+ int *stat_loc,
+ int options
);
**STATUS CODES:**
-*ENOSYS*
- This routine is not supported by RTEMS.
+.. list-table::
+ :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.
-
diff --git a/posix_users/process_environment.rst b/posix_users/process_environment.rst
index 50c89b0..4d65d58 100644
--- a/posix_users/process_environment.rst
+++ b/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
-functions related to user and group Id management.
+The process environment manager is responsible for providing the functions
+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.
-In this light, the notion of user and group is somewhat without meaning.
-But RTEMS does provide services to provide a synthetic version of
-user and group. By default, a single user and group is associated
-with the application. Thus unless special actions are taken,
-every thread in the application shares the same user and group Id.
-The initial rationale for providing user and group Id functionality
-in RTEMS was for the filesystem infrastructure to implement
-file permission checks. The effective user/group Id capability
-has since been used to implement permissions checking by
-the ``ftpd`` server.
-
-In addition to the "real" user and group Ids, a process may
-have an effective user/group Id. This allows a process to
-function using a more limited permission set for certain operations.
+RTEMS provides a single process, multi-threaded execution environment. In this
+light, the notion of user and group is somewhat without meaning. But RTEMS
+does provide services to provide a synthetic version of user and group. By
+default, a single user and group is associated with the application. Thus
+unless special actions are taken, every thread in the application shares the
+same user and group Id. The initial rationale for providing user and group Id
+functionality in RTEMS was for the filesystem infrastructure to implement file
+permission checks. The effective user/group Id capability has since been used
+to implement permissions checking by the ``ftpd`` server.
+
+In addition to the "real" user and group Ids, a process may have an effective
+user/group Id. This allows a process to function using a more limited
+permission set for certain operations.
User and Group Names
--------------------
-POSIX considers user and group Ids to be a unique integer that
-may be associated with a name. This is usually accomplished
-via a file named ``/etc/passwd`` for user Id mapping and``/etc/groups`` for group Id mapping. Again, although
-RTEMS is effectively a single process and thus single user
-system, it provides limited support for user and group
-names. When configured with an appropriate filesystem, RTEMS
-will access the appropriate files to map user and group Ids
-to names.
-
-If these files do not exist, then RTEMS will synthesize
-a minimal version so this family of services return without
-error. It is important to remember that a design goal of
-the RTEMS POSIX services is to provide useable and
-meaningful results even though a full process model
-is not available.
+POSIX considers user and group Ids to be a unique integer that may be
+associated with a name. This is usually accomplished via a file named
+:file:`/etc/passwd` for user Id mapping and :file:`/etc/groups` for group Id
+mapping. Again, although RTEMS is effectively a single process and thus single
+user system, it provides limited support for user and group names. When
+configured with an appropriate filesystem, RTEMS will access the appropriate
+files to map user and group Ids to names.
+
+If these files do not exist, then RTEMS will synthesize a minimal version so
+this family of services return without error. It is important to remember that
+a design goal of the RTEMS POSIX services is to provide useable and meaningful
+results even though a full process model is not available.
Environment Variables
---------------------
-POSIX allows for variables in the run-time environment. These are
-name/value pairs that make be dynamically set and obtained by
-programs. In a full POSIX environment with command line shell
-and multiple processes, environment variables may be set in
-one process - such as the shell - and inherited by child
-processes. In RTEMS, there is only one process and thus
-only one set of environment variables across all processes.
+POSIX allows for variables in the run-time environment. These are name/value
+pairs that make be dynamically set and obtained by programs. In a full POSIX
+environment with command line shell and multiple processes, environment
+variables may be set in one process - such as the shell - and inherited by
+child processes. In RTEMS, there is only one process and thus 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
-using the ``getuid()`` service. Similarly, the group Id
-may be obtained using the ``getgid()`` service.
+The user Id associated with the current thread may be obtain using the
+``getuid()`` service. Similarly, the group Id may be obtained using the
+``getgid()`` service.
Accessing Environment Variables
-------------------------------
-The value associated with an environment variable may be
-obtained using the ``getenv()`` service and set using
-the ``putenv()`` service.
+The value associated with an environment variable may be obtained using the
+``getenv()`` service and set using the ``putenv()`` service.
Directives
==========
-This section details the process environment manager's directives.
-A subsection is dedicated to each of this manager's directives
-and describes the calling sequence, related constants, usage,
-and status codes.
+This section details the process environment manager's directives. A
+subsection is dedicated to each of this manager's directives and describes the
+calling sequence, related constants, usage, and status codes.
+
+.. _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,
- gid_t grouplist[]
+ int gidsetsize,
+ gid_t grouplist[]
);
**STATUS CODES:**
@@ -340,13 +354,13 @@ NA
**DESCRIPTION:**
-This service is not implemented as RTEMS has no notion of
-supplemental groups.
+This service is not implemented as RTEMS has no notion of supplemental groups.
**NOTES:**
-If supported, this routine would only be allowed for
-the super-user.
+If supported, this routine would only be allowed for 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
-current user.
+Returns a pointer to a string containing the name of the 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,
- size_t namesize
+ char *name,
+ size_t namesize
);
**STATUS CODES:**
-*EINVAL*
- The arguments were invalid.
+.. list-table::
+ :class: rtems-table
+
+ * - ``EINVAL``
+ - The arguments were invalid.
**DESCRIPTION:**
-This is a reentrant version of the ``getlogin()`` service. The
-caller specified their own buffer, ``name``, as well as the
-length of this buffer, ``namesize``.
+This is a reentrant version of the ``getlogin()`` service. The caller
+specified their own buffer, ``name``, as well as the length of this buffer,
+``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
-way for RTEMS but is truly not functional.
+This routine is implemented in a somewhat meaningful way for RTEMS but is truly
+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*
- The application does not have permission to create a process group.
+.. list-table::
+ :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
-to create new processes and thus no way to create a new process
-group.
+This routine always returns ``EPERM`` as RTEMS has no way to create new
+processes and thus no way to create a new process 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 pgid
+ pid_t pid,
+ pid_t pgid
);
**STATUS CODES:**
-*ENOSYS*
- The routine is not implemented.
+.. list-table::
+ :class: rtems-table
+
+ * - ``ENOSYS``
+ - The routine is not implemented.
**DESCRIPTION:**
-This service is not implemented for RTEMS as process groups are not
-supported.
+This service is not implemented for RTEMS as process groups are not 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*
- The provided structure pointer is invalid.
+.. list-table::
+ :class: rtems-table
+
+ * - ``EPERM``
+ - The provided structure pointer is invalid.
**DESCRIPTION:**
-This service returns system information to the caller. It does this
-by filling in the ``struct utsname`` format structure for the
-caller.
+This service returns system information to the caller. It does this by filling
+in the ``struct utsname`` format structure for the caller.
**NOTES:**
-The information provided includes the operating system (RTEMS in
-all configurations), the node number, the release as the RTEMS
-version, and the CPU family and model. The CPU model name
-will indicate the multilib executive variant being used.
+The information provided includes the operating system (RTEMS in all
+configurations), the node number, the release as the RTEMS version, and the CPU
+family and model. The CPU model name will indicate the multilib executive
+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
-since the system was initialized (e.g. the application was
-started).
+This routine returns the number of clock ticks that have elapsed since the
+system was initialized (e.g. the application was started).
**DESCRIPTION:**
-``times`` stores the current process times in ``ptms``. The
-format of ``struct tms`` is as defined in``<sys/times.h>``. RTEMS fills in the field ``tms_utime``
-with the number of ticks that the calling thread has executed
-and the field ``tms_stime`` with the number of clock ticks
-since system boot (also returned). All other fields in the``ptms`` are left zero.
+``times`` stores the current process times in ``ptms``. The format of ``struct
+tms`` is as defined in ``<sys/times.h>``. RTEMS fills in the field
+``tms_utime`` with the number of ticks that the calling thread has executed and
+the field ``tms_stime`` with the number of clock ticks since system boot (also
+returned). All other fields in the ``ptms`` are left zero.
**NOTES:**
-RTEMS has no way to distinguish between user and system time
-so this routine returns the most meaningful information
-possible.
+RTEMS has no way to distinguish between user and system time so this routine
+returns the most meaningful information possible.
+
+.. _getenv:
getenv - Get Environment Variables
----------------------------------
@@ -552,30 +587,33 @@ getenv - Get Environment Variables
**CALLING SEQUENCE:**
-.. code:: c
+.. code-block:: c
- char \*getenv(
- const char \*name
+ char *getenv(
+ const char \*name
);
**STATUS CODES:**
-*NULL*
- when no match
+.. list-table::
+ :class: rtems-table
-*pointer to value*
- when successful
+ * - ``NULL``
+ - when no match
+ * - `pointer to value`
+ - when successful
**DESCRIPTION:**
-This service searches the set of environment variables for
-a string that matches the specified ``name``. If found,
-it returns the associated value.
+This service searches the set of environment variables for a string that
+matches the specified ``name``. If found, it returns the associated value.
**NOTES:**
-The environment list consists of name value pairs that
-are of the form *name = value*.
+The environment list consists of name value pairs that are of the form ``name =
+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 \*value,
- int overwrite
+ const char *name,
+ const char *value,
+ 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
-created. If ``name`` exists and ``overwrite`` is zero, then
-the previous value is not overwritten.
+This service adds the variable ``name`` to the environment with ``value``. If
+``name`` is not already exist, then it is created. If ``name`` exists and
+``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 \*s
+ char *ctermid(
+ char *s
);
**STATUS CODES:**
@@ -626,18 +666,19 @@ terminal.
**DESCRIPTION:**
-This service returns the name of the terminal device associated with
-this process. If ``s`` is NULL, then a pointer to a static buffer
-is returned. Otherwise, ``s`` is assumed to have a buffer of
-sufficient size to contain the name of the controlling terminal.
+This service returns the name of the terminal device associated with this
+process. If ``s`` is NULL, then a pointer to a static buffer is returned.
+Otherwise, ``s`` is assumed to have a buffer of sufficient size to contain the
+name of the controlling terminal.
**NOTES:**
-By default on RTEMS systems, the controlling terminal is ``/dev/console``.
-Again this implementation is of limited meaning, but it provides
-true and useful results which should be sufficient to ease porting
-applications from a full POSIX implementation to the reduced
-profile supported by RTEMS.
+By default on RTEMS systems, the controlling terminal is :file:`/dev/console`.
+Again this implementation is of limited meaning, but it provides true and
+useful results which should be sufficient to ease porting applications from a
+full POSIX implementation to the reduced 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(
- int fd
+ char *ttyname(
+ int fd
);
**STATUS CODES:**
-Pointer to a string containing the terminal device name or
-NULL is returned on any error.
+Pointer to a string containing the terminal device name or ``NULL`` is returned
+on any error.
**DESCRIPTION:**
-This service returns a pointer to the pathname of the terminal
-device that is open on the file descriptor ``fd``. If``fd`` is not a valid descriptor for a terminal device,
-then NULL is returned.
+This service returns a pointer to the pathname of the terminal device that is
+open on the file descriptor ``fd``. If ``fd`` is not a valid descriptor for a
+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,
- char \*name,
- int namesize
+ int fd,
+ char *name,
+ int namesize
);
**STATUS CODES:**
This routine returns -1 and sets ``errno`` as follows:
-*EBADF*
- If not a valid descriptor for a terminal device.
+.. list-table::
+ :class: rtems-table
-*EINVAL*
- If ``name`` is NULL or ``namesize`` are insufficient.
+ * - ``EBADF``
+ - 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
-on the file descriptor ``fd``.
+This service the pathname of the terminal device that is open on the file
+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
-connected to a terminal and 0 otherwise.
+This service returns 1 if ``fd`` is an open file descriptor connected to a
+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.
-If the requested configuration name is a feature flag, then
-1 is returned if the available and 0 if it is not. On any
-other error condition, -1 is returned.
+The value returned is the actual value of the system resource. If the
+requested configuration name is a feature flag, then 1 is returned if the
+available and 0 if it is not. On any other error condition, -1 is returned.
**DESCRIPTION:**
-This service is the mechanism by which an application determines
-values for system limits or options at runtime.
+This service is the mechanism by which an application determines values for
+system limits or options at runtime.
**NOTES:**
-Much of the information that may be obtained via ``sysconf``
-has equivalent macros in ``<unistd.h``. However, those
-macros reflect conservative limits which may have been altered
-by application configuration.
-
-.. COMMENT: COPYRIGHT (c) 1988-2002.
-
-.. COMMENT: On-Line Applications Research Corporation (OAR).
-
-.. COMMENT: All rights reserved.
-
+Much of the information that may be obtained via ``sysconf`` has equivalent
+macros in ``unistd.h``. However, those macros reflect conservative limits
+which may have been altered by application configuration.
diff --git a/posix_users/scheduler.rst b/posix_users/scheduler.rst
index 9d249b0..68eefc0 100644
--- a/posix_users/scheduler.rst
+++ b/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
-the low priority of ``sched_get_priority_min()`` to the highest priority of``sched_get_priority_max()``. Numerically higher values represent higher
+In the RTEMS implementation of the POSIX API, the priorities range from the low
+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
- to what is called "manual round-robin" scheduling.
+ Priority-based, preemptive scheduling with no timeslicing. This is
+ 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:
- budget, replenishment period, and low priority. Under this policy, the
- thread is allowed to execute for "budget" amount of time before its priority
- is lowered to "low priority". At the end of each replenishment period,
- the thread resumes its initial priority and has its budget replenished.
+ Priority-based, preemptive scheduling utilizing three additional
+ parameters: budget, replenishment period, and low priority. Under this
+ policy, the thread is allowed to execute for "budget" amount of time before
+ its priority is lowered to "low priority". At the end of each replenishment
+ 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.
-A subsection is dedicated to each of this manager's directives
-and describes the calling sequence, related constants, usage,
-and status codes.
+This section details the scheduler manager's directives. A subsection is
+dedicated to each of this manager's directives and describes the calling
+sequence, related constants, usage, and status codes.
+
+.. _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*
- The indicated policy is invalid.
+.. list-table::
+ :class: rtems-table
+
+ * - ``EINVAL``
+ - The indicated policy is invalid.
**DESCRIPTION:**
-This routine return the minimum (numerically and logically lowest) priority
-for the specified ``policy``.
+This routine return the minimum (numerically and logically lowest) priority for
+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:
+
+.. list-table::
+ :class: rtems-table
-*EINVAL*
- The indicated policy is invalid.
+ * - ``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,
- struct timespec \*interval
+ pid_t pid,
+ 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*
- The indicated process id is invalid.
+.. list-table::
+ :class: rtems-table
-*EINVAL*
- The specified interval pointer parameter is invalid.
+ * - ``ESRCH``
+ - 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
-task scheduling.
+thread. Normally this is used to implement voluntary round-robin task
+scheduling.
**NOTES:**
NONE
-
-.. COMMENT: COPYRIGHT (c) 1988-2002.
-
-.. COMMENT: On-Line Applications Research Corporation (OAR).
-
-.. COMMENT: All rights reserved.
-
diff --git a/posix_users/semaphore.rst b/posix_users/semaphore.rst
index 47628df..71b1684 100644
--- a/posix_users/semaphore.rst
+++ b/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.
-A subsection is dedicated to each of this manager's directives
-and describes the calling sequence, related constants, usage,
-and status codes.
+This section details the semaphore manager's directives. A subsection is
+dedicated to each of this manager's directives and describes the calling
+sequence, related constants, usage, and status codes.
+
+.. _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,
- int pshared,
- unsigned int value
+ sem_t *sem,
+ int pshared,
+ unsigned int value
);
**STATUS CODES:**
-*EINVAL*
- The value argument exceeds SEM_VALUE_MAX
+.. list-table::
+ :class: rtems-table
-*ENOSPC*
- A resource required to initialize the semaphore has been exhausted
- The limit on semaphores (SEM_VALUE_MAX) has been reached
-
-*ENOSYS*
- The function sem_init is not supported by this implementation
-
-*EPERM*
- The process lacks appropriate privileges to initialize the semaphore
+ * - ``EINVAL``
+ - The value argument exceeds ``SEM_VALUE_MAX``
+ * - ``ENOSPC``
+ - A resource required to initialize the semaphore has been exhausted The
+ limit on semaphores (``SEM_VALUE_MAX``) has been reached
+ * - ``ENOSYS``
+ - The function sem_init is not supported by this implementation
+ * - ``EPERM``
+ - The process lacks appropriate privileges to initialize the semaphore
**DESCRIPTION:**
-The sem_init function is used to initialize the unnamed semaphore referred to
-by "sem". The value of the initialized semaphore is the parameter "value". The
-semaphore remains valid until it is destroyed.
+The ``sem_init`` function is used to initialize the unnamed semaphore referred
+to by ``sem``. The value of the initialized semaphore is the parameter
+``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*
- The value argument exceeds SEM_VALUE_MAX
+.. list-table::
+ :class: rtems-table
-*ENOSYS*
- The function sem_init is not supported by this implementation
-
-*EBUSY*
- There are currently processes blocked on the semaphore
+ * - ``EINVAL``
+ - The value argument exceeds ``SEM_VALUE_MAX``
+ * - ``ENOSYS``
+ - The function ``sem_init`` is not supported by this implementation
+ * - ``EBUSY``
+ - There are currently processes blocked on the semaphore
**DESCRIPTION:**
-The sem_destroy function is used to destroy an unnamed semaphore refered to by
-"sem". sem_destroy can only be used on a semaphore that was created using
-sem_init.
+The ``sem_destroy`` function is used to destroy an unnamed semaphore refered to
+by ``sem``. ``sem_destroy`` can only be used on a semaphore that was created
+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,
- int oflag
+ const char *name,
+ 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
-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.
+.. list-table::
+ :class: rtems-table
-``O_EXCL`` - If O_EXCL and O_CREAT are set, all call to sem_open() shall fail
-if the semaphore name exists
+ * - ``O_CREAT``
+ - 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*
- Valid name specified but oflag permissions are denied, or the semaphore name
- specified does not exist and permission to create the named semaphore is denied.
-
-*EEXIST*
- O_CREAT and O_EXCL are set and the named semaphore already exists.
-
-*EINTR*
- The sem_open() operation was interrupted by a signal.
-
-*EINVAL*
- The sem_open() operation is not supported for the given name.
-
-*EMFILE*
- Too many semaphore descriptors or file descriptors in use by this process.
-
-*ENAMETOOLONG*
- The length of the name exceed PATH_MAX or name component is longer than NAME_MAX
- while POSIX_NO_TRUNC is in effect.
-
-*ENOENT*
- 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.
-
-*ENOSYS*
- The function sem_open() is not supported by this implementation.
+.. list-table::
+ :class: rtems-table
+
+ * - ``EACCES``
+ - Valid name specified but oflag permissions are denied, or the semaphore
+ name specified does not exist and permission to create the named semaphore
+ is denied.
+ * - ``EEXIST``
+ - ``O_CREAT`` and ``O_EXCL`` are set and the named semaphore already exists.
+ * - ``EINTR``
+ - The ``sem_open()`` operation was interrupted by a signal.
+ * - ``EINVAL``
+ - The ``sem_open()`` operation is not supported for the given name.
+ * - ``EMFILE``
+ - Too many semaphore descriptors or file descriptors in use by this process.
+ * - ``ENAMETOOLONG``
+ - The length of the name exceed ``PATH_MAX`` or name component is longer
+ than ``NAME_MAX`` while ``POSIX_NO_TRUNC`` is in effect.
+ * - ``ENOENT``
+ - ``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.
+ * - ``ENOSYS``
+ - The function ``sem_open()`` is not supported by this implementation.
**DESCRIPTION:**
-The sem_open() function establishes a connection between a specified semaphore and
-a process. After a call to sem_open with a specified semaphore name, a process
-can reference to semaphore by the associated name using the address returned by
-the call. The oflag arguments listed above control the state of the semaphore by
-determining if the semaphore is created or accessed by a call to sem_open().
+The ``sem_open()`` function establishes a connection between a specified
+semaphore and a process. After a call to sem_open with a specified semaphore
+name, a process can reference to semaphore by the associated name using the
+address returned by the call. The oflag arguments listed above control the
+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*
- The semaphore argument is not a valid semaphore descriptor.
+.. list-table::
+ :class: rtems-table
-*ENOSYS*
- The function sem_close is not supported by this implementation.
+ * - ``EACCES``
+ - 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
-using the named semaphore indicated by sem. The function sem_close deallocates
-any system resources that were previously allocated by a sem_open system call. If
-sem_close() completes successfully it returns a 1, otherwise a value of -1 is
-return and errno is set.
+The ``sem_close()`` function is used to indicate that the calling process is
+finished using the named semaphore indicated by ``sem``. The function
+``sem_close`` deallocates any system resources that were previously allocated
+by a ``sem_open`` system call. If ``sem_close()`` completes successfully it
+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*
- Permission is denied to unlink a semaphore.
-
-*ENAMETOOLONG*
- The length of the strong name exceed NAME_MAX while POSIX_NO_TRUNC is in effect.
-
-*ENOENT*
- The name of the semaphore does not exist.
-
-*ENOSPC*
- There is insufficient space for the creation of a new named semaphore.
-
-*ENOSYS*
- The function sem_unlink is not supported by this implementation.
+.. list-table::
+ :class: rtems-table
+
+ * - ``EACCESS``
+ - Permission is denied to unlink a semaphore.
+ * - ``ENAMETOOLONG``
+ - The length of the strong name exceed ``NAME_MAX`` while ``POSIX_NO_TRUNC``
+ is in effect.
+ * - ``ENOENT``
+ - The name of the semaphore does not exist.
+ * - ``ENOSPC``
+ - There is insufficient space for the creation of a new named semaphore.
+ * - ``ENOSYS``
+ - 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
-a process is currently accessing the name semaphore, the sem_unlink command has
-no effect. If one or more processes have the semaphore open when the sem_unlink
-function is called, the destruction of semaphores shall be postponed until all
-reference to semaphore are destroyed by calls to sem_close, _exit(), or exec.
-After all references have been destroyed, it returns immediately.
+The ``sem_unlink()`` function shall remove the semaphore name by the string
+name. If a process is currently accessing the name semaphore, the
+``sem_unlink`` command has no effect. If one or more processes have the
+semaphore open when the ``sem_unlink`` function is called, the destruction of
+semaphores shall be postponed until all reference to semaphore are destroyed by
+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*
- The "sem" argument does not refer to a valid semaphore
+.. list-table::
+ :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
-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_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*
- The semaphore is not available (i.e., the semaphore value is zero), so the
- semaphore could not be locked.
+.. list-table::
+ :class: rtems-table
-*EINVAL*
- The ``sem`` argument does not refewr to a valid semaphore
+ * - ``EAGAIN``
+ - 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
-value is decremented) and the function returns a value of 0. The semaphore
-remains locked until released by a ``sem_post()`` call. If the semaphore
-is unavailable (i.e., the semaphore value is zero), then the function will
-return a value of -1 immediately and set ``errno`` to EAGAIN.
+semaphore is available, then the semaphore is locked (i.e., the semaphore value
+is decremented) and the function returns a value of 0. The semaphore remains
+locked until released by a ``sem_post()`` call. If the semaphore is unavailable
+(i.e., the semaphore value is zero), then the function will return a value
+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,
- const struct timespec \*abstime
+ sem_t *sem,
+ const struct timespec *abstime
);
**STATUS CODES:**
-*EAGAIN*
- The semaphore is not available (i.e., the semaphore value is zero), so the
- semaphore could not be locked.
+.. list-table::
+ :class: rtems-table
-*EINVAL*
- The ``sem`` argument does not refewr to a valid semaphore
+ * - ``EAGAIN``
+ - 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``,
-and will wait for the semaphore until the absolute time specified by``abstime``. If the semaphore is available, then the semaphore is
-locked (i.e., the semaphore value is decremented) and the function
-returns a value of 0. The semaphore remains locked until released by
-a ``sem_post()`` call. If the semaphore is unavailable, then the
-function will wait for the semaphore to become available 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 any other error occurs, the function returns -1 and sets ``errno`` to
-the appropriate error code.
+This function attemtps to lock a semaphore specified by ``sem``, and will wait
+for the semaphore until the absolute time specified by ``abstime``. If the
+semaphore is available, then the semaphore is locked (i.e., the semaphore value
+is decremented) and the function returns a value of 0. The semaphore remains
+locked until released by a ``sem_post()`` call. If the semaphore is
+unavailable, then the function will wait for the semaphore to become available
+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
+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*
- The ``sem`` argument does not refer to a valid semaphore
+.. list-table::
+ :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
-other tasks are waiting on the semaphore, then one of those tasks (which one
-depends on the scheduler being used) is allowed to lock the semaphore and
-return from its ``sem_wait()``, ``sem_trywait()``, or``sem_timedwait()`` call. If there are no other tasks waiting on the
-semaphore, then the semaphore value is simply incremented. ``sem_post()``
-returns 0 upon successful completion.
+This function attempts to release the semaphore specified by ``sem``. If other
+tasks are waiting on the semaphore, then one of those tasks (which one depends
+on the scheduler being used) is allowed to lock the semaphore and return from
+its ``sem_wait()``, ``sem_trywait()``, or ``sem_timedwait()`` call. If there
+are no other tasks waiting on the semaphore, then the semaphore value is simply
+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,
- int \*sval
+ sem_t *sem,
+ int *sval
);
**STATUS CODES:**
-*EINVAL*
- The "sem" argument does not refer to a valid semaphore
+.. list-table::
+ :class: rtems-table
-*ENOSYS*
- The function sem_getvalue is not supported by this implementation
+ * - ``EINVAL``
+ - 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
-to the value of the semaphore without affecting the state of the semaphore. The
-updated value represents a semaphore value that occurred at some point during
-the call, but is not necessarily the actual value of the semaphore when it
-returns to the calling process.
+The ``sem_getvalue`` functions sets the location referenced by the ``sval``
+argument to the value of the semaphore without affecting the state of the
+semaphore. The updated value represents a semaphore value that occurred at some
+point during the call, but is not necessarily the actual value of the semaphore
+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.
-
diff --git a/posix_users/services_provided_by_c.rst b/posix_users/services_provided_by_c.rst
index e061d0b..a856009 100644
--- a/posix_users/services_provided_by_c.rst
+++ b/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.
-
diff --git a/posix_users/signal.rst b/posix_users/signal.rst
index 6ad79b1..117a6dd 100644
--- a/posix_users/signal.rst
+++ b/posix_users/signal.rst
@@ -1,52 +1,55 @@
+.. COMMENT: COPYRIGHT (c) 1988-2002.
+.. COMMENT: On-Line Applications Research Corporation (OAR).
+.. COMMENT: All rights reserved.
+
Signal Manager
##############
Introduction
============
-The signal manager provides the functionality associated with
-the generation, delivery, and management of process-oriented
-signals.
+The signal manager provides the functionality associated with the generation,
+delivery, and management of process-oriented signals.
The directives provided by the signal manager are:
-- ``sigaddset`` - Add a Signal to a Signal Set
+- sigaddset_ - Add a Signal to a Signal Set
-- ``sigdelset`` - Delete a Signal from a Signal Set
+- sigdelset_ - Delete a Signal from a Signal Set
-- ``sigfillset`` - Fill a Signal Set
+- sigfillset_ - Fill a Signal Set
-- ``sigismember`` - Is Signal a Member of a Signal Set
+- sigismember_ - Is Signal a Member of a Signal Set
-- ``sigemptyset`` - Empty a Signal Set
+- sigemptyset_ - Empty a Signal Set
-- ``sigaction`` - Examine and Change Signal Action
+- sigaction_ - Examine and Change Signal Action
-- ``pthread_kill`` - Send a Signal to a Thread
+- pthread_kill_ - Send a Signal to a Thread
-- ``sigprocmask`` - Examine and Change Process Blocked Signals
+- sigprocmask_ - Examine and Change Process Blocked Signals
-- ``pthread_sigmask`` - Examine and Change Thread Blocked Signals
+- pthread_sigmask_ - Examine and Change Thread Blocked Signals
-- ``kill`` - Send a Signal to a Process
+- kill_ - Send a Signal to a Process
-- ``sigpending`` - Examine Pending Signals
+- sigpending_ - Examine Pending Signals
-- ``sigsuspend`` - Wait for a Signal
+- sigsuspend_ - Wait for a Signal
-- ``pause`` - Suspend Process Execution
+- pause_ - Suspend Process Execution
-- ``sigwait`` - Synchronously Accept a Signal
+- sigwait_ - Synchronously Accept a Signal
-- ``sigwaitinfo`` - Synchronously Accept a Signal
+- sigwaitinfo_ - Synchronously Accept a Signal
-- ``sigtimedwait`` - Synchronously Accept a Signal with Timeout
+- sigtimedwait_ - Synchronously Accept a Signal with Timeout
-- ``sigqueue`` - Queue a Signal to a Process
+- sigqueue_ - Queue a Signal to a Process
-- ``alarm`` - Schedule Alarm
+- alarm_ - Schedule Alarm
-- ``ualarm`` - Schedule Alarm in Microseconds
+- ualarm_ - Schedule Alarm in Microseconds
Background
==========
@@ -54,57 +57,55 @@ Background
Signals
-------
-POSIX signals are an asynchronous event mechanism. Each process
-and thread has a set of signals associated with it. Individual
-signals may be enabled (e.g. unmasked) or blocked (e.g. ignored)
-on both a per-thread and process level. Signals which are
-enabled have a signal handler associated with them. When the
-signal is generated and conditions are met, then the signal
-handler is invoked in the proper process or thread context
-asynchronous relative to the logical thread of execution.
-
-If a signal has been blocked when it is generated, then it
-is queued and kept pending until the thread or process unblocks
-the signal or explicitly checks for it.
-Traditional, non-real-time POSIX signals do not queue. Thus
-if a process or thread has blocked a particular signal, then
-multiple occurrences of that signal are recorded as a
-single occurrence of that signal.
+POSIX signals are an asynchronous event mechanism. Each process and thread has
+a set of signals associated with it. Individual signals may be enabled
+(e.g. unmasked) or blocked (e.g. ignored) on both a per-thread and process
+level. Signals which are enabled have a signal handler associated with them.
+When the signal is generated and conditions are met, then the signal handler is
+invoked in the proper process or thread context asynchronous relative to the
+logical thread of execution.
+
+If a signal has been blocked when it is generated, then it is queued and kept
+pending until the thread or process unblocks the signal or explicitly checks
+for it. Traditional, non-real-time POSIX signals do not queue. Thus if a
+process or thread has blocked a particular signal, then multiple occurrences of
+that signal are recorded as a single occurrence of that signal.
.. COMMENT: TODO: SIGRTMIN and SIGRTMAX ?
-One can check for the set of outstanding signals that have been
-blocked. Services are provided to check for outstanding process
-or thread directed signals.
+One can check for the set of outstanding signals that have been blocked.
+Services are provided to check for outstanding process or thread directed
+signals.
Signal Delivery
---------------
Signals which are directed at a thread are delivered to the specified thread.
-Signals which are directed at a process are delivered to a thread which
-is selected based on the following algorithm:
+Signals which are directed at a process are delivered to a thread which is
+selected based on the following algorithm:
-# If the action for this signal is currently ``SIG_IGN``,
- then the signal is simply ignored.
+#. If the action for this signal is currently ``SIG_IGN``, then the signal is
+ simply ignored.
-# If the currently executing thread has the signal unblocked, then
- the signal is delivered to it.
+#. If the currently executing thread has the signal unblocked, then the signal
+ is delivered to it.
-# If any threads are currently blocked waiting for this signal
- (``sigwait()``), then the signal is delivered to the highest priority
- thread waiting for this signal.
+#. If any threads are currently blocked waiting for this signal
+ (``sigwait()``), then the signal is delivered to the highest priority thread
+ waiting for this signal.
-# If any other threads are willing to accept delivery of the signal, then
- the signal is delivered to the highest priority thread of this set. In the
- event, multiple threads of the same priority are willing to accept this
- signal, then priority is given first to ready threads, then to threads
- blocked on calls which may be interrupted, and finally to threads blocked
- on non-interruptible calls.
+#. If any other threads are willing to accept delivery of the signal, then the
+ signal is delivered to the highest priority thread of this set. In the
+ event, multiple threads of the same priority are willing to accept this
+ signal, then priority is given first to ready threads, then to threads
+ blocked on calls which may be interrupted, and finally to threads blocked on
+ non-interruptible calls.
-# In the event the signal still can not be delivered, then it is left
- pending. The first thread to unblock the signal (``sigprocmask()`` or``pthread_sigprocmask()``) or to wait for this signal
- (``sigwait()``) will be the recipient of the signal.
+#. In the event the signal still can not be delivered, then it is left
+ pending. The first thread to unblock the signal (``sigprocmask()`` or
+ ``pthread_sigprocmask()``) or to wait for this signal (``sigwait()``) will
+ be the recipient of the signal.
Operations
==========
@@ -112,36 +113,34 @@ Operations
Signal Set Management
---------------------
-Each process and each thread within that process has a set of
-individual signals and handlers associated with it. Services
-are provided to construct signal sets for the purposes of building
-signal sets - type ``sigset_t`` - that are used to
-provide arguments to the services that mask, unmask, and
-check on pending signals.
+Each process and each thread within that process has a set of individual
+signals and handlers associated with it. Services are provided to construct
+signal sets for the purposes of building signal sets - type ``sigset_t`` - that
+are used to provide arguments to the services that mask, unmask, and check on
+pending signals.
Blocking Until Signal Generation
--------------------------------
-A thread may block until receipt of a signal. The "sigwait"
-and "pause" families of functions block until the requested
-signal is received or if using ``sigtimedwait()`` until the specified
-timeout period has elapsed.
+A thread may block until receipt of a signal. The "sigwait" and "pause"
+families of functions block until the requested signal is received or if using
+``sigtimedwait()`` until the specified timeout period has elapsed.
Sending a Signal
----------------
-This is accomplished
-via one of a number of services that sends a signal to either a
-process or thread. Signals may be directed at a process by
-the service ``kill()`` or at a thread by the service``pthread_kill()``
+This is accomplished via one of a number of services that sends a signal to
+either a process or thread. Signals may be directed at a process by the
+service ``kill()`` or at a thread by the service ``pthread_kill()``
Directives
==========
-This section details the signal manager's directives.
-A subsection is dedicated to each of this manager's directives
-and describes the calling sequence, related constants, usage,
-and status codes.
+This section details the signal manager's directives. A subsection is
+dedicated to each of this manager's directives and describes the calling
+sequence, related constants, usage, and status codes.
+
+.. _sigaddset:
sigaddset - Add a Signal to a Signal Set
----------------------------------------
@@ -150,20 +149,24 @@ sigaddset - Add a Signal to a Signal Set
**CALLING SEQUENCE:**
-.. code:: c
+.. code-block:: c
#include <signal.h>
int sigaddset(
- sigset_t \*set,
- int signo
+ sigset_t *set,
+ int signo
);
**STATUS CODES:**
-The function returns 0 on success, otherwise it returns -1 and sets``errno`` to indicate the error. ``errno`` may be set to:
+The function returns 0 on success, otherwise it returns -1 and sets ``errno``
+to indicate the error. ``errno`` may be set to:
-*EINVAL*
- Invalid argument passed.
+.. list-table::
+ :class: rtems-table
+
+ * - ``EINVAL``
+ - Invalid argument passed.
**DESCRIPTION:**
@@ -174,6 +177,8 @@ This function adds the signal ``signo`` to the specified signal ``set``.
The set must be initialized using either ``sigemptyset`` or ``sigfillset``
before using this function.
+.. _sigdelset:
+
sigdelset - Delete a Signal from a Signal Set
---------------------------------------------
.. index:: sigdelset
@@ -181,20 +186,24 @@ sigdelset - Delete a Signal from a Signal Set
**CALLING SEQUENCE:**
-.. code:: c
+.. code-block:: c
#include <signal.h>
int sigdelset(
- sigset_t \*set,
- int signo
+ sigset_t *set,
+ int signo
);
**STATUS CODES:**
-The function returns 0 on success, otherwise it returns -1 and sets``errno`` to indicate the error. ``errno`` may be set to:
+The function returns 0 on success, otherwise it returns -1 and sets ``errno``
+to indicate the error. ``errno`` may be set to:
-*EINVAL*
- Invalid argument passed.
+.. list-table::
+ :class: rtems-table
+
+ * - ``EINVAL``
+ - Invalid argument passed.
**DESCRIPTION:**
@@ -206,6 +215,8 @@ signal ``set``.
The set must be initialized using either ``sigemptyset`` or ``sigfillset``
before using this function.
+.. _sigfillset:
+
sigfillset - Fill a Signal Set
------------------------------
.. index:: sigfillset
@@ -213,24 +224,29 @@ sigfillset - Fill a Signal Set
**CALLING SEQUENCE:**
-.. code:: c
+.. code-block:: c
#include <signal.h>
int sigfillset(
- sigset_t \*set
+ sigset_t *set
);
**STATUS CODES:**
-The function returns 0 on success, otherwise it returns -1 and sets``errno`` to indicate the error. ``errno`` may be set to:
+The function returns 0 on success, otherwise it returns -1 and sets ``errno``
+to indicate the error. ``errno`` may be set to:
-*EINVAL*
- Invalid argument passed.
+.. list-table::
+ :class: rtems-table
+
+ * - ``EINVAL``
+ - Invalid argument passed.
**DESCRIPTION:**
-This function fills the specified signal ``set`` such that all
-signals are set.
+This function fills the specified signal ``set`` such that all signals are set.
+
+.. _sigismember:
sigismember - Is Signal a Member of a Signal Set
------------------------------------------------
@@ -239,33 +255,37 @@ sigismember - Is Signal a Member of a Signal Set
**CALLING SEQUENCE:**
-.. code:: c
+.. code-block:: c
#include <signal.h>
int sigismember(
- const sigset_t \*set,
- int signo
+ const sigset_t *set,
+ int signo
);
**STATUS CODES:**
The function returns either 1 or 0 if completed successfully, otherwise it
-returns -1 and sets ``errno`` to indicate the error. ``errno`` may be set
-to:
+returns -1 and sets ``errno`` to indicate the error. ``errno`` may be set to:
-*EINVAL*
- Invalid argument passed.
+.. list-table::
+ :class: rtems-table
+
+ * - ``EINVAL``
+ - Invalid argument passed.
**DESCRIPTION:**
-This function returns returns 1 if ``signo`` is a member of ``set``
-and 0 otherwise.
+This function returns returns 1 if ``signo`` is a member of ``set`` and 0
+otherwise.
**NOTES:**
The set must be initialized using either ``sigemptyset`` or ``sigfillset``
before using this function.
+.. _sigemptyset:
+
sigemptyset - Empty a Signal Set
--------------------------------
.. index:: sigemptyset
@@ -273,24 +293,30 @@ sigemptyset - Empty a Signal Set
**CALLING SEQUENCE:**
-.. code:: c
+.. code-block:: c
#include <signal.h>
int sigemptyset(
- sigset_t \*set
+ sigset_t *set
);
**STATUS CODES:**
-The function returns 0 on success, otherwise it returns -1 and sets``errno`` to indicate the error. ``errno`` may be set to:
+The function returns 0 on success, otherwise it returns -1 and sets ``errno``
+to indicate the error. ``errno`` may be set to:
-*EINVAL*
- Invalid argument passed.
+.. list-table::
+ :class: rtems-table
+
+ * - ``EINVAL``
+ - Invalid argument passed.
**DESCRIPTION:**
This function initializes an empty signal set pointed to by ``set``.
+.. _sigaction:
+
sigaction - Examine and Change Signal Action
--------------------------------------------
.. index:: sigaction
@@ -298,24 +324,27 @@ sigaction - Examine and Change Signal Action
**CALLING SEQUENCE:**
-.. code:: c
+.. code-block:: c
#include <signal.h>
int sigaction(
- int sig,
- const struct sigaction \*act,
- struct sigaction \*oact
+ int sig,
+ const struct sigaction *act,
+ struct sigaction *oact
);
**STATUS CODES:**
-The function returns 0 on success, otherwise it returns -1 and sets``errno`` to indicate the error. ``errno`` may be set to:
+The function returns 0 on success, otherwise it returns -1 and sets ``errno``
+to indicate the error. ``errno`` may be set to:
-*EINVAL*
- Invalid argument passed.
+.. list-table::
+ :class: rtems-table
-*ENOTSUP*
- Realtime Signals Extension option not supported.
+ * - ``EINVAL``
+ - Invalid argument passed.
+ * - ``ENOTSUP``
+ - Realtime Signals Extension option not supported.
**DESCRIPTION:**
@@ -328,52 +357,66 @@ about the current handling of a given signal.
The structure ``sigaction`` has the following members:
-``void(\*)(int) sa_handler``
- Pointer to a signal-catching function or one of the macros SIG_IGN or SIG_DFL.
-
-``sigset_t sa_mask``
- Additional set of signals to be blocked during execution of signal-catching function.
-
-``int sa_flags``
- Special flags to affect behavior of signal.
-
-``void(\*)(int, siginfo_t*, void*) sa_sigaction``
- Alternative pointer to a signal-catching function.
-
-``sa_handler`` and ``sa_sigaction`` should never be used at the same time as their storage may overlap.
-
-If the ``SA_SIGINFO`` flag (see below) is set in ``sa_flags``, the``sa_sigaction`` field specifies a signal-catching function, otherwise``sa_handler`` specifies the action to be associated with the signal, which
-may be a signal-catching function or one of the macros ``SIG_IGN`` or``SIG_DFN``.
+.. list-table::
+ :class: rtems-table
+
+ * - ``void(*)(int) sa_handler``
+ - Pointer to a signal-catching function or one of the macros SIG_IGN or
+ SIG_DFL.
+ * - ``sigset_t sa_mask``
+ - Additional set of signals to be blocked during execution of
+ signal-catching function.
+ * - ``int sa_flags``
+ - Special flags to affect behavior of signal.
+ * - ``void(*)(int, siginfo_t*, void*) sa_sigaction``
+ - Alternative pointer to a signal-catching function.
+
+``sa_handler`` and ``sa_sigaction`` should never be used at the same time as
+their storage may overlap.
+
+If the ``SA_SIGINFO`` flag (see below) is set in ``sa_flags``, the
+``sa_sigaction`` field specifies a signal-catching function,
+otherwise``sa_handler`` specifies the action to be associated with the signal,
+which may be a signal-catching function or one of the macros ``SIG_IGN`` or
+``SIG_DFN``.
The following flags can be set in the ``sa_flags`` field:
-``SA_SIGINFO``
- If not set, the signal-catching function should be declared as ``void
- func(int signo)`` and the address of the function should be set in``sa_handler``. If set, the signal-catching function should be declared as``void func(int signo, siginfo_t* info, void* context)`` and the address of
- the function should be set in ``sa_sigaction``.
+.. list-table::
+ :class: rtems-table
+
+ * - ``SA_SIGINFO``
+ - If not set, the signal-catching function should be declared as ``void
+ func(int signo)`` and the address of the function should be set
+ in``sa_handler``. If set, the signal-catching function should be declared
+ as ``void func(int signo, siginfo_t* info, void* context)`` and the
+ address of the function should be set in ``sa_sigaction``.
The prototype of the ``siginfo_t`` structure is the following:
-.. code:: c
+
+.. code-block:: c
typedef struct
{
- int si_signo; /* Signal number \*/
- int si_code; /* Cause of the signal \*/
- pid_t si_pid; /* Sending process ID \*/
- uid_t si_uid; /* Real user ID of sending process \*/
- void* si_addr; /* Address of faulting instruction \*/
- int si_status; /* Exit value or signal \*/
- union sigval
- {
- int sival_int; /* Integer signal value \*/
- void* sival_ptr; /* Pointer signal value \*/
- } si_value; /* Signal value \*/
+ int si_signo; /* Signal number */
+ int si_code; /* Cause of the signal */
+ pid_t si_pid; /* Sending process ID */
+ uid_t si_uid; /* Real user ID of sending process */
+ void* si_addr; /* Address of faulting instruction */
+ int si_status; /* Exit value or signal */
+ union sigval
+ {
+ int sival_int; /* Integer signal value */
+ void* sival_ptr; /* Pointer signal value */
+ } si_value; /* Signal value */
}
**NOTES:**
The signal number cannot be SIGKILL.
+.. _pthread_kill:
+
pthread_kill - Send a Signal to a Thread
----------------------------------------
.. index:: pthread_kill
@@ -381,31 +424,36 @@ pthread_kill - Send a Signal to a Thread
**CALLING SEQUENCE:**
-.. code:: c
+.. code-block:: c
#include <signal.h>
int pthread_kill(
- pthread_t thread,
- int sig
+ pthread_t thread,
+ int sig
);
**STATUS CODES:**
-The function returns 0 on success, otherwise it returns -1 and sets``errno`` to indicate the error. ``errno`` may be set to:
+The function returns 0 on success, otherwise it returns -1 and sets ``errno`` to
+indicate the error. ``errno`` may be set to:
-*ESRCH*
- The thread indicated by the parameter thread is invalid.
+.. list-table::
+ :class: rtems-table
-*EINVAL*
- Invalid argument passed.
+ * - ``ESRCH``
+ - The thread indicated by the parameter thread is invalid.
+ * - ``EINVAL``
+ - Invalid argument passed.
**DESCRIPTION:**
-This functions sends the specified signal ``sig`` to a thread referenced
-to by ``thread``.
+This functions sends the specified signal ``sig`` to a thread referenced to by
+``thread``.
If the signal code is ``0``, arguments are validated and no signal is sent.
+.. _sigprocmask:
+
sigprocmask - Examine and Change Process Blocked Signals
--------------------------------------------------------
.. index:: sigprocmask
@@ -413,49 +461,57 @@ sigprocmask - Examine and Change Process Blocked Signals
**CALLING SEQUENCE:**
-.. code:: c
+.. code-block:: c
#include <signal.h>
int sigprocmask(
- int how,
- const sigset_t \*set,
- sigset_t \*oset
+ int how,
+ const sigset_t *set,
+ sigset_t *oset
);
**STATUS CODES:**
-The function returns 0 on success, otherwise it returns -1 and sets``errno`` to indicate the error. ``errno`` may be set to:
+The function returns 0 on success, otherwise it returns -1 and sets ``errno``
+to indicate the error. ``errno`` may be set to:
-*EINVAL*
- Invalid argument passed.
+.. list-table::
+ :class: rtems-table
-**DESCRIPTION:**
+ * - ``EINVAL``
+ - Invalid argument passed.
-This function is used to alter the set of currently blocked signals
-on a process wide basis. A blocked signal will not be received by the
-process. The behavior of this function is dependent on the value of``how`` which may be one of the following:
+**DESCRIPTION:**
-``SIG_BLOCK``
- The set of blocked signals is set to the union of ``set`` and
- those signals currently blocked.
+This function is used to alter the set of currently blocked signals on a
+process wide basis. A blocked signal will not be received by the process. The
+behavior of this function is dependent on the value of ``how`` which may be one
+of the following:
-``SIG_UNBLOCK``
- The signals specific in ``set`` are removed from the currently
- blocked set.
+.. list-table::
+ :class: rtems-table
-``SIG_SETMASK``
- The set of currently blocked signals is set to ``set``.
+ * - ``SIG_BLOCK``
+ - The set of blocked signals is set to the union of ``set`` and those
+ signals currently blocked.
+ * - ``SIG_UNBLOCK``
+ - The signals specific in ``set`` are removed from the currently blocked
+ set.
+ * - ``SIG_SETMASK``
+ - The set of currently blocked signals is set to ``set``.
-If ``oset`` is not ``NULL``, then the set of blocked signals prior to
-this call is returned in ``oset``. If ``set`` is *NULL*, no change is
-done, allowing to examine the set of currently blocked signals.
+If ``oset`` is not ``NULL``, then the set of blocked signals prior to this call
+is returned in ``oset``. If ``set`` is ``NULL``, no change is done, allowing to
+examine the set of currently blocked signals.
**NOTES:**
It is not an error to unblock a signal which is not blocked.
-In the current implementation of RTEMS POSIX API sigprocmask() is technically
-mapped to pthread_sigmask().
+In the current implementation of RTEMS POSIX API ``sigprocmask()`` is
+technically mapped to ``pthread_sigmask()``.
+
+.. _pthread_sigmask:
pthread_sigmask - Examine and Change Thread Blocked Signals
-----------------------------------------------------------
@@ -464,7 +520,7 @@ pthread_sigmask - Examine and Change Thread Blocked Signals
**CALLING SEQUENCE:**
-.. code:: c
+.. code-block:: c
#include <signal.h>
int pthread_sigmask(
@@ -475,36 +531,41 @@ pthread_sigmask - Examine and Change Thread Blocked Signals
**STATUS CODES:**
-The function returns 0 on success, otherwise it returns -1 and sets``errno`` to indicate the error. ``errno`` may be set to:
+The function returns 0 on success, otherwise it returns -1 and sets ``errno``
+to indicate the error. ``errno`` may be set to:
*EINVAL*
Invalid argument passed.
**DESCRIPTION:**
-This function is used to alter the set of currently blocked signals
-for the calling thread. A blocked signal will not be received by the
-process. The behavior of this function is dependent on the value of``how`` which may be one of the following:
+This function is used to alter the set of currently blocked signals for the
+calling thread. A blocked signal will not be received by the process. The
+behavior of this function is dependent on the value of ``how`` which may be one
+of the following:
-``SIG_BLOCK``
- The set of blocked signals is set to the union of ``set`` and
- those signals currently blocked.
+.. list-table::
+ :class: rtems-table
-``SIG_UNBLOCK``
- The signals specific in ``set`` are removed from the currently
- blocked set.
+ * - ``SIG_BLOCK``
+ - The set of blocked signals is set to the union of ``set`` and those
+ signals currently blocked.
+ * - ``SIG_UNBLOCK``
+ - The signals specific in ``set`` are removed from the currently blocked
+ set.
+ * - ``SIG_SETMASK``
+ - The set of currently blocked signals is set to ``set``.
-``SIG_SETMASK``
- The set of currently blocked signals is set to ``set``.
-
-If ``oset`` is not ``NULL``, then the set of blocked signals prior to
-this call is returned in ``oset``. If ``set`` is *NULL*, no change is
-done, allowing to examine the set of currently blocked signals.
+If ``oset`` is not ``NULL``, then the set of blocked signals prior to this call
+is returned in ``oset``. If ``set`` is ``NULL``, no change is done, allowing to
+examine the set of currently blocked signals.
**NOTES:**
It is not an error to unblock a signal which is not blocked.
+.. _kill:
+
kill - Send a Signal to a Process
---------------------------------
.. index:: kill
@@ -512,27 +573,30 @@ kill - Send a Signal to a Process
**CALLING SEQUENCE:**
-.. code:: c
+.. code-block:: c
#include <sys/types.h>
#include <signal.h>
int kill(
- pid_t pid,
- int sig
+ pid_t pid,
+ int sig
);
**STATUS CODES:**
-The function returns 0 on success, otherwise it returns -1 and sets``errno`` to indicate the error. ``errno`` may be set to:
-
-*EINVAL*
- Invalid argument passed.
+The function returns 0 on success, otherwise it returns -1 and sets ``errno`` to
+indicate the error. ``errno`` may be set to:
-*EPERM*
- Process does not have permission to send the signal to any receiving process.
+.. list-table::
+ :class: rtems-table
-*ESRCH*
- The process indicated by the parameter pid is invalid.
+ * - ``EINVAL``
+ - Invalid argument passed.
+ * - ``EPERM``
+ - Process does not have permission to send the signal to any receiving
+ process.
+ * - ``ESRCH``
+ - The process indicated by the parameter pid is invalid.
**DESCRIPTION:**
@@ -540,8 +604,10 @@ This function sends the signal ``sig`` to the process ``pid``.
**NOTES:**
-Since RTEMS is a single-process system, a signal can only be sent to the calling
-process (i.e. the current node).
+Since RTEMS is a single-process system, a signal can only be sent to the
+calling process (i.e. the current node).
+
+.. _sigpending:
sigpending - Examine Pending Signals
------------------------------------
@@ -550,19 +616,23 @@ sigpending - Examine Pending Signals
**CALLING SEQUENCE:**
-.. code:: c
+.. code-block:: c
#include <signal.h>
- int sigpending(
- const sigset_t \*set
+ int sigpending(
+ const sigset_t *set
);
**STATUS CODES:**
-The function returns 0 on success, otherwise it returns -1 and sets``errno`` to indicate the error. ``errno`` may be set to:
+The function returns 0 on success, otherwise it returns -1 and sets ``errno``
+to indicate the error. ``errno`` may be set to:
+
+.. list-table::
+ :class: rtems-table
-*EFAULT*
- Invalid address for set.
+ * - ``EFAULT``
+ - Invalid address for set.
**DESCRIPTION:**
@@ -570,6 +640,8 @@ This function allows the caller to examine the set of currently pending
signals. A pending signal is one which has been raised but is currently
blocked. The set of pending signals is returned in ``set``.
+.. _sigsuspend:
+
sigsuspend - Wait for a Signal
------------------------------
.. index:: sigsuspend
@@ -577,25 +649,31 @@ sigsuspend - Wait for a Signal
**CALLING SEQUENCE:**
-.. code:: c
+.. code-block:: c
#include <signal.h>
- int sigsuspend(
- const sigset_t \*sigmask
+ int sigsuspend(
+ const sigset_t *sigmask
);
**STATUS CODES:**
-The function returns 0 on success, otherwise it returns -1 and sets``errno`` to indicate the error. ``errno`` may be set to:
+The function returns 0 on success, otherwise it returns -1 and sets ``errno``
+to indicate the error. ``errno`` may be set to:
-*EINTR*
- Signal interrupted this function.
+.. list-table::
+ :class: rtems-table
+
+ * - ``EINTR``
+ - Signal interrupted this function.
**DESCRIPTION:**
-This function temporarily replaces the signal mask for the process
-with that specified by ``sigmask`` and blocks the calling thread
-until a signal is raised.
+This function temporarily replaces the signal mask for the process with that
+specified by ``sigmask`` and blocks the calling thread until a signal is
+raised.
+
+.. _pause:
pause - Suspend Process Execution
---------------------------------
@@ -604,22 +682,28 @@ pause - Suspend Process Execution
**CALLING SEQUENCE:**
-.. code:: c
+.. code-block:: c
#include <signal.h>
int pause( void );
**STATUS CODES:**
-The function returns 0 on success, otherwise it returns -1 and sets``errno`` to indicate the error. ``errno`` may be set to:
+The function returns 0 on success, otherwise it returns -1 and sets ``errno``
+to indicate the error. ``errno`` may be set to:
-*EINTR*
- Signal interrupted this function.
+.. list-table::
+ :class: rtems-table
+
+ * - ``EINTR``
+ - Signal interrupted this function.
**DESCRIPTION:**
-This function causes the calling thread to be blocked until an
-unblocked signal is received.
+This function causes the calling thread to be blocked until an unblocked signal
+is received.
+
+.. _sigwait:
sigwait - Synchronously Accept a Signal
---------------------------------------
@@ -628,28 +712,34 @@ sigwait - Synchronously Accept a Signal
**CALLING SEQUENCE:**
-.. code:: c
+.. code-block:: c
#include <signal.h>
int sigwait(
- const sigset_t \*set,
- int \*sig
+ const sigset_t *set,
+ int *sig
);
**STATUS CODES:**
-The function returns 0 on success, otherwise it returns -1 and sets``errno`` to indicate the error. ``errno`` may be set to:
+The function returns 0 on success, otherwise it returns -1 and sets ``errno``
+to indicate the error. ``errno`` may be set to:
-*EINVAL*
- Invalid argument passed.
+.. list-table::
+ :class: rtems-table
-*EINTR*
- Signal interrupted this function.
+ * - ``EINVAL``
+ - Invalid argument passed.
+ * - ``EINTR``
+ - Signal interrupted this function.
**DESCRIPTION:**
-This function selects a pending signal based on the set specified in``set``, atomically clears it from the set of pending signals, and
-returns the signal number for that signal in ``sig``.
+This function selects a pending signal based on the set specified in ``set``,
+atomically clears it from the set of pending signals, and returns the signal
+number for that signal in ``sig``.
+
+.. _sigwaitinfo:
sigwaitinfo - Synchronously Accept a Signal
-------------------------------------------
@@ -658,44 +748,49 @@ sigwaitinfo - Synchronously Accept a Signal
**CALLING SEQUENCE:**
-.. code:: c
+.. code-block:: c
#include <signal.h>
int sigwaitinfo(
- const sigset_t \*set,
- siginfo_t \*info
+ const sigset_t *set,
+ siginfo_t *info
);
**STATUS CODES:**
-The function returns 0 on success, otherwise it returns -1 and sets``errno`` to indicate the error. ``errno`` may be set to:
+The function returns 0 on success, otherwise it returns -1 and sets ``errno``
+to indicate the error. ``errno`` may be set to:
*EINTR*
Signal interrupted this function.
**DESCRIPTION:**
-This function selects a pending signal based on the set specified in``set``, atomically clears it from the set of pending signals, and
-returns information about that signal in ``info``.
+This function selects a pending signal based on the set specified in ``set``,
+atomically clears it from the set of pending signals, and returns information
+about that signal in ``info``.
The prototype of the ``siginfo_t`` structure is the following:
-.. code:: c
+
+.. code-block:: c
typedef struct
{
- int si_signo; /* Signal number \*/
- int si_code; /* Cause of the signal \*/
- pid_t si_pid; /* Sending process ID \*/
- uid_t si_uid; /* Real user ID of sending process \*/
- void* si_addr; /* Address of faulting instruction \*/
- int si_status; /* Exit value or signal \*/
- union sigval
- {
- int sival_int; /* Integer signal value \*/
- void* sival_ptr; /* Pointer signal value \*/
- } si_value; /* Signal value \*/
+ int si_signo; /* Signal number */
+ int si_code; /* Cause of the signal */
+ pid_t si_pid; /* Sending process ID */
+ uid_t si_uid; /* Real user ID of sending process */
+ void* si_addr; /* Address of faulting instruction */
+ int si_status; /* Exit value or signal */
+ union sigval
+ {
+ int sival_int; /* Integer signal value */
+ void* sival_ptr; /* Pointer signal value */
+ } si_value; /* Signal value */
}
+.. _sigtimedwait:
+
sigtimedwait - Synchronously Accept a Signal with Timeout
---------------------------------------------------------
.. index:: sigtimedwait
@@ -703,47 +798,53 @@ sigtimedwait - Synchronously Accept a Signal with Timeout
**CALLING SEQUENCE:**
-.. code:: c
+.. code-block:: c
#include <signal.h>
int sigtimedwait(
- const sigset_t \*set,
- siginfo_t \*info,
- const struct timespec \*timeout
+ const sigset_t *set,
+ siginfo_t *info,
+ const struct timespec *timeout
);
**STATUS CODES:**
-The function returns 0 on success, otherwise it returns -1 and sets``errno`` to indicate the error. ``errno`` may be set to:
+The function returns 0 on success, otherwise it returns -1 and sets ``errno``
+to indicate the error. ``errno`` may be set to:
-*EAGAIN*
- Timed out while waiting for the specified signal set.
+.. list-table::
+ :class: rtems-table
-*EINVAL*
- Nanoseconds field of the timeout argument is invalid.
-
-*EINTR*
- Signal interrupted this function.
+ * - ``EAGAIN``
+ - Timed out while waiting for the specified signal set.
+ * - ``EINVAL``
+ - Nanoseconds field of the timeout argument is invalid.
+ * - ``EINTR``
+ - Signal interrupted this function.
**DESCRIPTION:**
-This function selects a pending signal based on the set specified in``set``, atomically clears it from the set of pending signals, and
-returns information about that signal in ``info``. The calling thread
-will block up to ``timeout`` waiting for the signal to arrive.
+This function selects a pending signal based on the set specified in ``set``,
+atomically clears it from the set of pending signals, and returns information
+about that signal in ``info``. The calling thread will block up to ``timeout``
+waiting for the signal to arrive.
The ``timespec`` structure is defined as follows:
-.. code:: c
+
+.. code-block:: c
struct timespec
{
- time_t tv_sec; /* Seconds \*/
- long tv_nsec; /* Nanoseconds \*/
+ time_t tv_sec; /* Seconds */
+ long tv_nsec; /* Nanoseconds */
}
**NOTES:**
-If ``timeout`` is NULL, then the calling thread will wait forever for
-the specified signal set.
+If ``timeout`` is NULL, then the calling thread will wait forever for the
+specified signal set.
+
+.. _sigqueue:
sigqueue - Queue a Signal to a Process
--------------------------------------
@@ -752,53 +853,56 @@ sigqueue - Queue a Signal to a Process
**CALLING SEQUENCE:**
-.. code:: c
+.. code-block:: c
#include <signal.h>
int sigqueue(
- pid_t pid,
- int signo,
- const union sigval value
+ pid_t pid,
+ int signo,
+ const union sigval value
);
**STATUS CODES:**
-The function returns 0 on success, otherwise it returns -1 and sets``errno`` to indicate the error. ``errno`` may be set to:
-
-*EAGAIN*
- No resources available to queue the signal. The process has already
- queued SIGQUEUE_MAX signals that are still pending at the receiver
- or the systemwide resource limit has been exceeded.
-
-*EINVAL*
- The value of the signo argument is an invalid or unsupported signal
- number.
-
-*EPERM*
- The process does not have the appropriate privilege to send the signal
- to the receiving process.
-
-*ESRCH*
- The process pid does not exist.
+The function returns 0 on success, otherwise it returns -1 and sets ``errno``
+to indicate the error. ``errno`` may be set to:
+
+.. list-table::
+ :class: rtems-table
+
+ * - ``EAGAIN``
+ - No resources available to queue the signal. The process has already queued
+ ``SIGQUEUE_MAX`` signals that are still pending at the receiver or the
+ systemwide resource limit has been exceeded.
+ * - ``EINVAL``
+ - The value of the signo argument is an invalid or unsupported signal
+ number.
+ * - ``EPERM``
+ - The process does not have the appropriate privilege to send the signal to
+ the receiving process.
+ * - ``ESRCH``
+ - The process pid does not exist.
**DESCRIPTION:**
-This function sends the signal specified by ``signo`` to the
-process ``pid``
+This function sends the signal specified by ``signo`` to the process ``pid``
The ``sigval`` union is specified as:
-.. code:: c
+
+.. code-block:: c
union sigval
{
- int sival_int; /* Integer signal value \*/
- void* sival_ptr; /* Pointer signal value \*/
+ int sival_int; /* Integer signal value */
+ void* sival_ptr; /* Pointer signal value */
}
**NOTES:**
-Since RTEMS is a single-process system, a signal can only be sent to the calling
-process (i.e. the current node).
+Since RTEMS is a single-process system, a signal can only be sent to the
+calling process (i.e. the current node).
+
+.. _alarm:
alarm - Schedule Alarm
----------------------
@@ -807,36 +911,37 @@ alarm - Schedule Alarm
**CALLING SEQUENCE:**
-.. code:: c
+.. code-block:: c
#include <unistd.h>
unsigned int alarm(
- unsigned int seconds
+ unsigned int seconds
);
**STATUS CODES:**
This call always succeeds.
-If there was a previous ``alarm()`` request with time remaining,
-then this routine returns the number of seconds until that outstanding
-alarm would have fired. If no previous ``alarm()`` request was
-outstanding, then zero is returned.
+If there was a previous ``alarm()`` request with time remaining, then this
+routine returns the number of seconds until that outstanding alarm would have
+fired. If no previous ``alarm()`` request was outstanding, then zero is
+returned.
**DESCRIPTION:**
-The ``alarm()`` service causes the ``SIGALRM`` signal to
-be generated after the number of seconds specified by``seconds`` has elapsed.
+The ``alarm()`` service causes the ``SIGALRM`` signal to be generated after the
+number of seconds specified by ``seconds`` has elapsed.
**NOTES:**
-Alarm requests do not queue. If ``alarm`` is called while
-a previous request is outstanding, the call will result in
-rescheduling the time at which the ``SIGALRM`` signal
-will be generated.
+Alarm requests do not queue. If ``alarm`` is called while a previous request
+is outstanding, the call will result in rescheduling the time at which the
+``SIGALRM`` signal will be generated.
+
+If the notification signal, ``SIGALRM``, is not caught or ignored, the calling
+process is terminated.
-If the notification signal, ``SIGALRM``, is not caught or ignored, the
-calling process is terminated.
+.. _ualarm:
ualarm - Schedule Alarm in Microseconds
---------------------------------------
@@ -847,44 +952,36 @@ ualarm - Schedule Alarm in Microseconds
**CALLING SEQUENCE:**
-.. code:: c
+.. code-block:: c
#include <unistd.h>
useconds_t ualarm(
- useconds_t useconds,
- useconds_t interval
+ useconds_t useconds,
+ useconds_t interval
);
**STATUS CODES:**
This call always succeeds.
-If there was a previous ``ualarm()`` request with time remaining,
-then this routine returns the number of seconds until that outstanding
-alarm would have fired. If no previous ``alarm()`` request was
-outstanding, then zero is returned.
+If there was a previous ``ualarm()`` request with time remaining, then this
+routine returns the number of seconds until that outstanding alarm would have
+fired. If no previous ``alarm()`` request was outstanding, then zero is
+returned.
**DESCRIPTION:**
-The ``ualarm()`` service causes the ``SIGALRM`` signal to
-be generated after the number of microseconds specified by``useconds`` has elapsed.
+The ``ualarm()`` service causes the ``SIGALRM`` signal to be generated after
+the number of microseconds specified by ``useconds`` has elapsed.
-When ``interval`` is non-zero, repeated timeout notification occurs
-with a period in microseconds specified by ``interval``.
+When ``interval`` is non-zero, repeated timeout notification occurs with a
+period in microseconds specified by ``interval``.
**NOTES:**
-Alarm requests do not queue. If ``alarm`` is called while
-a previous request is outstanding, the call will result in
-rescheduling the time at which the ``SIGALRM`` signal
-will be generated.
-
-If the notification signal, ``SIGALRM``, is not caught or ignored, the
-calling process is terminated.
-
-.. COMMENT: COPYRIGHT (c) 1988-2002.
-
-.. COMMENT: On-Line Applications Research Corporation (OAR).
-
-.. COMMENT: All rights reserved.
+Alarm requests do not queue. If ``alarm`` is called while a previous request
+is outstanding, the call will result in rescheduling the time at which the
+``SIGALRM`` signal will be generated.
+If the notification signal, ``SIGALRM``, is not caught or ignored, the calling
+process is terminated.
diff --git a/posix_users/status_of_implementation.rst b/posix_users/status_of_implementation.rst
index 7f535f0..e372f42 100644
--- a/posix_users/status_of_implementation.rst
+++ b/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.
-
diff --git a/posix_users/system_database.rst b/posix_users/system_database.rst
index 60d6e02..e629f9b 100644
--- a/posix_users/system_database.rst
+++ b/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
-system databases manager is ...
+The 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.
-A subsection is dedicated to each of this manager's directives
-and describes the calling sequence, related constants, usage,
-and status codes.
+This section details the system databases manager's directives. A subsection
+is dedicated to each of this manager's directives and describes the calling
+sequence, related constants, usage, and status codes.
+
+.. _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*
- The
+.. list-table::
+ :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*
- The
+.. list-table::
+ :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*
- The
+.. list-table::
+ :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*
- The
+.. list-table::
+ :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*
- The
+.. list-table::
+ :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*
- The
+.. list-table::
+ :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*
- The
+.. list-table::
+ :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*
- The
+.. list-table::
+ :class: rtems-table
+
+ * - ``E``
+ - The
**DESCRIPTION:**
**NOTES:**
-
-.. COMMENT: COPYRIGHT(c) 1988-2002.
-
-.. COMMENT: On-Line Applications Research Corporation(OAR).
-
-.. COMMENT: All rights reserved.
-
diff --git a/posix_users/thread.rst b/posix_users/thread.rst
index b6a6fca..c0ce38b 100644
--- a/posix_users/thread.rst
+++ b/posix_users/thread.rst
@@ -1,75 +1,79 @@
+.. COMMENT: COPYRIGHT (c) 1988-2002.
+.. COMMENT: On-Line Applications Research Corporation (OAR).
+.. COMMENT: All rights reserved.
+
Thread Manager
##############
Introduction
============
-The thread manager implements the functionality required of the thread
-manager as defined by POSIX 1003.1b. This standard requires that
-a compliant operating system provide the facilties to manage multiple
-threads of control and defines the API that must be provided.
+The thread manager implements the functionality required of the thread manager
+as defined by POSIX 1003.1b. This standard requires that a compliant operating
+system provide the facilties to manage multiple threads of control and defines
+the API that must be provided.
The services provided by the thread manager are:
-- ``pthread_attr_init`` - Initialize a Thread Attribute Set
+- pthread_attr_init_ - Initialize a Thread Attribute Set
-- ``pthread_attr_destroy`` - Destroy a Thread Attribute Set
+- pthread_attr_destroy_ - Destroy a Thread Attribute Set
-- ``pthread_attr_setdetachstate`` - Set Detach State
+- pthread_attr_setdetachstate_ - Set Detach State
-- ``pthread_attr_getdetachstate`` - Get Detach State
+- pthread_attr_getdetachstate_ - Get Detach State
-- ``pthread_attr_setstacksize`` - Set Thread Stack Size
+- pthread_attr_setstacksize_ - Set Thread Stack Size
-- ``pthread_attr_getstacksize`` - Get Thread Stack Size
+- pthread_attr_getstacksize_ - Get Thread Stack Size
-- ``pthread_attr_setstackaddr`` - Set Thread Stack Address
+- pthread_attr_setstackaddr_ - Set Thread Stack Address
-- ``pthread_attr_getstackaddr`` - Get Thread Stack Address
+- pthread_attr_getstackaddr_ - Get Thread Stack Address
-- ``pthread_attr_setscope`` - Set Thread Scheduling Scope
+- pthread_attr_setscope_ - Set Thread Scheduling Scope
-- ``pthread_attr_getscope`` - Get Thread Scheduling Scope
+- pthread_attr_getscope_ - Get Thread Scheduling Scope
-- ``pthread_attr_setinheritsched`` - Set Inherit Scheduler Flag
+- pthread_attr_setinheritsched_ - Set Inherit Scheduler Flag
-- ``pthread_attr_getinheritsched`` - Get Inherit Scheduler Flag
+- pthread_attr_getinheritsched_ - Get Inherit Scheduler Flag
-- ``pthread_attr_setschedpolicy`` - Set Scheduling Policy
+- pthread_attr_setschedpolicy_ - Set Scheduling Policy
-- ``pthread_attr_getschedpolicy`` - Get Scheduling Policy
+- pthread_attr_getschedpolicy_ - Get Scheduling Policy
-- ``pthread_attr_setschedparam`` - Set Scheduling Parameters
+- pthread_attr_setschedparam_ - Set Scheduling Parameters
-- ``pthread_attr_getschedparam`` - Get Scheduling Parameters
+- pthread_attr_getschedparam_ - Get Scheduling Parameters
-- ``pthread_attr_getaffinity_np`` - Get Thread Affinity Attribute
+- pthread_attr_getaffinity_np_ - Get Thread Affinity Attribute
-- ``pthread_attr_setaffinity_np`` - Set Thread Affinity Attribute
+- pthread_attr_setaffinity_np_ - Set Thread Affinity Attribute
-- ``pthread_create`` - Create a Thread
+- pthread_create_ - Create a Thread
-- ``pthread_exit`` - Terminate the Current Thread
+- pthread_exit_ - Terminate the Current Thread
-- ``pthread_detach`` - Detach a Thread
+- pthread_detach_ - Detach a Thread
-- ``pthread_getattr_np`` - Get Thread Attributes
+- pthread_getattr_np_ - Get Thread Attributes
-- ``pthread_join`` - Wait for Thread Termination
+- pthread_join_ - Wait for Thread Termination
-- ``pthread_self`` - Get Thread ID
+- pthread_self_ - Get Thread ID
-- ``pthread_equal`` - Compare Thread IDs
+- pthread_equal_ - Compare Thread IDs
-- ``pthread_once`` - Dynamic Package Initialization
+- pthread_once_ - Dynamic Package Initialization
-- ``pthread_setschedparam`` - Set Thread Scheduling Parameters
+- pthread_setschedparam_ - Set Thread Scheduling Parameters
-- ``pthread_getschedparam`` - Get Thread Scheduling Parameters
+- pthread_getschedparam_ - Get Thread Scheduling Parameters
-- ``pthread_getaffinity_np`` - Get Thread Affinity
+- pthread_getaffinity_np_ - Get Thread Affinity
-- ``pthread_setaffinity_np`` - Set Thread Affinity
+- pthread_setaffinity_np_ - Set Thread Affinity
Background
==========
@@ -77,9 +81,9 @@ Background
Thread Attributes
-----------------
-Thread attributes are utilized only at thread creation time. A thread
-attribute structure may be initialized and passed as an argument to
-the ``pthread_create`` routine.
+Thread attributes are utilized only at thread creation time. A thread attribute
+structure may be initialized and passed as an argument to the
+``pthread_create`` routine.
*stack address*
is the address of the optionally user specified stack area for this thread.
@@ -90,27 +94,26 @@ the ``pthread_create`` routine.
rules which should be followed.
*stack size*
- is the minimum desired size for this thread's stack area.
- If the size of this area as specified by the stack size attribute
- is smaller than the minimum for this processor family and the stack
- is not user specified, then RTEMS will automatically allocate a
- stack of the minimum size for this processor family.
+ is the minimum desired size for this thread's stack area. If the size of
+ this area as specified by the stack size attribute is smaller than the
+ minimum for this processor family and the stack is not user specified, then
+ RTEMS will automatically allocate a stack of the minimum size for this
+ processor family.
*contention scope*
specifies the scheduling contention scope. RTEMS only supports the
PTHREAD_SCOPE_PROCESS scheduling contention scope.
*scheduling inheritance*
- specifies whether a user specified or the scheduling policy and
- parameters of the currently executing thread are to be used. When
- this is PTHREAD_INHERIT_SCHED, then the scheduling policy and
- parameters of the currently executing thread are inherited by
- the newly created thread.
+ specifies whether a user specified or the scheduling policy and parameters
+ of the currently executing thread are to be used. When this is
+ PTHREAD_INHERIT_SCHED, then the scheduling policy and parameters of the
+ currently executing thread are inherited by the newly created thread.
*scheduling policy and parameters*
- specify the manner in which the thread will contend for the processor.
- The scheduling parameters are interpreted based on the specified policy.
- All policies utilize the thread priority parameter.
+ specify the manner in which the thread will contend for the processor. The
+ scheduling parameters are interpreted based on the specified policy. All
+ policies utilize the thread priority parameter.
Operations
==========
@@ -120,10 +123,11 @@ There is currently no text in this section.
Services
========
-This section details the thread manager's services.
-A subsection is dedicated to each of this manager's services
-and describes the calling sequence, related constants, usage,
-and status codes.
+This section details the thread manager's services. A subsection is dedicated
+to each of this manager's services and describes the calling sequence, related
+constants, usage, and status codes.
+
+.. _pthread_attr_init:
pthread_attr_init - Initialize a Thread Attribute Set
-----------------------------------------------------
@@ -132,44 +136,48 @@ pthread_attr_init - Initialize a Thread Attribute Set
**CALLING SEQUENCE:**
-.. code:: c
+.. code-block:: c
#include <pthread.h>
int pthread_attr_init(
- pthread_attr_t \*attr
+ pthread_attr_t *attr
);
**STATUS CODES:**
-*EINVAL*
- The attribute pointer argument is invalid.
+.. list-table::
+ :class: rtems-table
+
+ * - ``EINVAL``
+ - The attribute pointer argument is invalid.
**DESCRIPTION:**
-The ``pthread_attr_init`` routine initializes the thread attributes
-object specified by ``attr`` with the default value for all of the
-individual attributes.
+The ``pthread_attr_init`` routine initializes the thread attributes object
+specified by ``attr`` with the default value for all of the individual
+attributes.
**NOTES:**
-The settings in the default attributes are implementation defined. For
-RTEMS, the default attributes are as follows:
+The settings in the default attributes are implementation defined. For RTEMS,
+the default attributes are as follows:
-- stackadr
- is not set to indicate that RTEMS is to allocate the stack memory.
+.. list-table::
+ :class: rtems-table
-- stacksize
- is set to ``PTHREAD_MINIMUM_STACK_SIZE``.
+ * - *stackadr*
+ - is not set to indicate that RTEMS is to allocate the stack memory.
+ * - *stacksize*
+ - is set to ``PTHREAD_MINIMUM_STACK_SIZE``.
+ * - *contentionscope*
+ - is set to ``PTHREAD_SCOPE_PROCESS``.
+ * - *inheritsched*
+ - is set to ``PTHREAD_INHERIT_SCHED`` to indicate that the created thread
+ inherits its scheduling attributes from its parent.
+ * - detachstate
+ - is set to ``PTHREAD_CREATE_JOINABLE``.
-- contentionscope
- is set to ``PTHREAD_SCOPE_PROCESS``.
-
-- inheritsched
- is set to ``PTHREAD_INHERIT_SCHED`` to indicate that the created
- thread inherits its scheduling attributes from its parent.
-
-- detachstate
- is set to ``PTHREAD_CREATE_JOINABLE``.
+.. _pthread_attr_destroy:
pthread_attr_destroy - Destroy a Thread Attribute Set
-----------------------------------------------------
@@ -178,31 +186,35 @@ pthread_attr_destroy - Destroy a Thread Attribute Set
**CALLING SEQUENCE:**
-.. code:: c
+.. code-block:: c
#include <pthread.h>
int pthread_attr_destroy(
- pthread_attr_t \*attr
+ pthread_attr_t *attr
);
**STATUS CODES:**
-*EINVAL*
- The attribute pointer argument is invalid.
+.. list-table::
+ :class: rtems-table
-*EINVAL*
- The attribute set is not initialized.
+ * - ``EINVAL``
+ - The attribute pointer argument is invalid.
+ * - ``EINVAL``
+ - The attribute set is not initialized.
**DESCRIPTION:**
-The ``pthread_attr_destroy`` routine is used to destroy a thread
-attributes object. The behavior of using an attributes object after
-it is destroyed is implementation dependent.
+The ``pthread_attr_destroy`` routine is used to destroy a thread attributes
+object. The behavior of using an attributes object after it is destroyed is
+implementation dependent.
**NOTES:**
NONE
+.. _pthread_attr_setdetachstate:
+
pthread_attr_setdetachstate - Set Detach State
----------------------------------------------
.. index:: pthread_attr_setdetachstate
@@ -210,36 +222,42 @@ pthread_attr_setdetachstate - Set Detach State
**CALLING SEQUENCE:**
-.. code:: c
+.. code-block:: c
#include <pthread.h>
int pthread_attr_setdetachstate(
- pthread_attr_t \*attr,
- int detachstate
+ pthread_attr_t *attr,
+ int detachstate
);
**STATUS CODES:**
-*EINVAL*
- The attribute pointer argument is invalid.
+.. list-table::
+ :class: rtems-table
-*EINVAL*
- The attribute set is not initialized.
-
-*EINVAL*
- The detachstate argument is invalid.
+ * - ``EINVAL``
+ - The attribute pointer argument is invalid.
+ * - ``EINVAL``
+ - The attribute set is not initialized.
+ * - ``EINVAL``
+ - The detachstate argument is invalid.
**DESCRIPTION:**
-The ``pthread_attr_setdetachstate`` routine is used to value of the``detachstate`` attribute. This attribute controls whether the
-thread is created in a detached state.
+The ``pthread_attr_setdetachstate`` routine is used to value of the
+``detachstate`` attribute. This attribute controls whether the thread is
+created in a detached state.
-The ``detachstate`` can be either ``PTHREAD_CREATE_DETACHED`` or``PTHREAD_CREATE_JOINABLE``. The default value for all threads is``PTHREAD_CREATE_JOINABLE``.
+The ``detachstate`` can be either ``PTHREAD_CREATE_DETACHED`` or
+``PTHREAD_CREATE_JOINABLE``. The default value for all threads is
+``PTHREAD_CREATE_JOINABLE``.
**NOTES:**
-If a thread is in a detached state,
-then the use of the ID with the ``pthread_detach`` or``pthread_join`` routines is an error.
+If a thread is in a detached state, then the use of the ID with the
+``pthread_detach`` or ``pthread_join`` routines is an error.
+
+.. _pthread_attr_getdetachstate:
pthread_attr_getdetachstate - Get Detach State
----------------------------------------------
@@ -248,35 +266,38 @@ pthread_attr_getdetachstate - Get Detach State
**CALLING SEQUENCE:**
-.. code:: c
+.. code-block:: c
#include <pthread.h>
int pthread_attr_getdetachstate(
- const pthread_attr_t \*attr,
- int \*detachstate
+ const pthread_attr_t *attr,
+ int *detachstate
);
**STATUS CODES:**
-*EINVAL*
- The attribute pointer argument is invalid.
+.. list-table::
+ :class: rtems-table
-*EINVAL*
- The attribute set is not initialized.
-
-*EINVAL*
- The detatchstate pointer argument is invalid.
+ * - ``EINVAL``
+ - The attribute pointer argument is invalid.
+ * - ``EINVAL``
+ - The attribute set is not initialized.
+ * - ``EINVAL``
+ - The detatchstate pointer argument is invalid.
**DESCRIPTION:**
-The ``pthread_attr_getdetachstate`` routine is used to obtain the
-current value of the ``detachstate`` attribute as specified
-by the ``attr`` thread attribute object.
+The ``pthread_attr_getdetachstate`` routine is used to obtain the current value
+of the ``detachstate`` attribute as specified by the ``attr`` thread attribute
+object.
**NOTES:**
NONE
+.. _pthread_attr_setstacksize:
+
pthread_attr_setstacksize - Set Thread Stack Size
-------------------------------------------------
.. index:: pthread_attr_setstacksize
@@ -284,35 +305,39 @@ pthread_attr_setstacksize - Set Thread Stack Size
**CALLING SEQUENCE:**
-.. code:: c
+.. code-block:: c
#include <pthread.h>
int pthread_attr_setstacksize(
- pthread_attr_t \*attr,
- size_t stacksize
+ pthread_attr_t *attr,
+ size_t stacksize
);
**STATUS CODES:**
-*EINVAL*
- The attribute pointer argument is invalid.
+.. list-table::
+ :class: rtems-table
-*EINVAL*
- The attribute set is not initialized.
+ * - ``EINVAL``
+ - The attribute pointer argument is invalid.
+ * - ``EINVAL``
+ - The attribute set is not initialized.
**DESCRIPTION:**
-The ``pthread_attr_setstacksize`` routine is used to set the``stacksize`` attribute in the ``attr`` thread attribute
-object.
+The ``pthread_attr_setstacksize`` routine is used to set the ``stacksize``
+attribute in the ``attr`` thread attribute object.
**NOTES:**
-As required by POSIX, RTEMS defines the feature symbol``_POSIX_THREAD_ATTR_STACKSIZE`` to indicate that this
-routine is supported.
+As required by POSIX, RTEMS defines the feature symbol
+``_POSIX_THREAD_ATTR_STACKSIZE`` to indicate that this routine is supported.
If the specified stacksize is below the minimum required for this CPU
-(``PTHREAD_STACK_MIN``, then the stacksize will be set to the minimum
-for this CPU.
+(``PTHREAD_STACK_MIN``, then the stacksize will be set to the minimum for this
+CPU.
+
+.. _pthread_attr_getstacksize:
pthread_attr_getstacksize - Get Thread Stack Size
-------------------------------------------------
@@ -321,34 +346,37 @@ pthread_attr_getstacksize - Get Thread Stack Size
**CALLING SEQUENCE:**
-.. code:: c
+.. code-block:: c
#include <pthread.h>
int pthread_attr_getstacksize(
- const pthread_attr_t \*attr,
- size_t \*stacksize
+ const pthread_attr_t *attr,
+ size_t *stacksize
);
**STATUS CODES:**
-*EINVAL*
- The attribute pointer argument is invalid.
-
-*EINVAL*
- The attribute set is not initialized.
+.. list-table::
+ :class: rtems-table
-*EINVAL*
- The stacksize pointer argument is invalid.
+ * - ``EINVAL``
+ - The attribute pointer argument is invalid.
+ * - ``EINVAL``
+ - The attribute set is not initialized.
+ * - ``EINVAL``
+ - The stacksize pointer argument is invalid.
**DESCRIPTION:**
-The ``pthread_attr_getstacksize`` routine is used to obtain the``stacksize`` attribute in the ``attr`` thread attribute
-object.
+The ``pthread_attr_getstacksize`` routine is used to obtain the ``stacksize``
+attribute in the ``attr`` thread attribute object.
**NOTES:**
-As required by POSIX, RTEMS defines the feature symbol``_POSIX_THREAD_ATTR_STACKSIZE`` to indicate that this
-routine is supported.
+As required by POSIX, RTEMS defines the feature symbol
+``_POSIX_THREAD_ATTR_STACKSIZE`` to indicate that this routine is supported.
+
+.. _pthread_attr_setstackaddr:
pthread_attr_setstackaddr - Set Thread Stack Address
----------------------------------------------------
@@ -357,34 +385,38 @@ pthread_attr_setstackaddr - Set Thread Stack Address
**CALLING SEQUENCE:**
-.. code:: c
+.. code-block:: c
#include <pthread.h>
int pthread_attr_setstackaddr(
- pthread_attr_t \*attr,
- void \*stackaddr
+ pthread_attr_t *attr,
+ void *stackaddr
);
**STATUS CODES:**
-*EINVAL*
- The attribute pointer argument is invalid.
+.. list-table::
+ :class: rtems-table
-*EINVAL*
- The attribute set is not initialized.
+ * - ``EINVAL``
+ - The attribute pointer argument is invalid.
+ * - ``EINVAL``
+ - The attribute set is not initialized.
**DESCRIPTION:**
-The ``pthread_attr_setstackaddr`` routine is used to set the``stackaddr`` attribute in the ``attr`` thread attribute
-object.
+The ``pthread_attr_setstackaddr`` routine is used to set the ``stackaddr``
+attribute in the ``attr`` thread attribute object.
**NOTES:**
-As required by POSIX, RTEMS defines the feature symbol``_POSIX_THREAD_ATTR_STACKADDR`` to indicate that this
-routine is supported.
+As required by POSIX, RTEMS defines the feature symbol
+``_POSIX_THREAD_ATTR_STACKADDR`` to indicate that this routine is supported.
-It is imperative to the proper operation of the system that
-each thread have sufficient stack space.
+It is imperative to the proper operation of the system that each thread have
+sufficient stack space.
+
+.. _pthread_attr_getstackaddr:
pthread_attr_getstackaddr - Get Thread Stack Address
----------------------------------------------------
@@ -393,34 +425,37 @@ pthread_attr_getstackaddr - Get Thread Stack Address
**CALLING SEQUENCE:**
-.. code:: c
+.. code-block:: c
#include <pthread.h>
int pthread_attr_getstackaddr(
- const pthread_attr_t \*attr,
- void \**stackaddr
+ const pthread_attr_t *attr,
+ void **stackaddr
);
**STATUS CODES:**
-*EINVAL*
- The attribute pointer argument is invalid.
-
-*EINVAL*
- The attribute set is not initialized.
+.. list-table::
+ :class: rtems-table
-*EINVAL*
- The stackaddr pointer argument is invalid.
+ * - ``EINVAL``
+ - The attribute pointer argument is invalid.
+ * - ``EINVAL``
+ - The attribute set is not initialized.
+ * - ``EINVAL``
+ - The stackaddr pointer argument is invalid.
**DESCRIPTION:**
-The ``pthread_attr_getstackaddr`` routine is used to obtain the``stackaddr`` attribute in the ``attr`` thread attribute
-object.
+The ``pthread_attr_getstackaddr`` routine is used to obtain the ``stackaddr``
+attribute in the ``attr`` thread attribute object.
**NOTES:**
-As required by POSIX, RTEMS defines the feature symbol``_POSIX_THREAD_ATTR_STACKADDR`` to indicate that this
-routine is supported.
+As required by POSIX, RTEMS defines the feature symbol
+``_POSIX_THREAD_ATTR_STACKADDR`` to indicate that this routine is supported.
+
+.. _pthread_attr_setscope:
pthread_attr_setscope - Set Thread Scheduling Scope
---------------------------------------------------
@@ -429,43 +464,46 @@ pthread_attr_setscope - Set Thread Scheduling Scope
**CALLING SEQUENCE:**
-.. code:: c
+.. code-block:: c
#include <pthread.h>
int pthread_attr_setscope(
- pthread_attr_t \*attr,
- int contentionscope
+ pthread_attr_t *attr,
+ int contentionscope
);
**STATUS CODES:**
-*EINVAL*
- The attribute pointer argument is invalid.
-
-*EINVAL*
- The attribute set is not initialized.
+.. list-table::
+ :class: rtems-table
-*EINVAL*
- The contention scope specified is not valid.
-
-*ENOTSUP*
- The contention scope specified (PTHREAD_SCOPE_SYSTEM) is not supported.
+ * - ``EINVAL``
+ - The attribute pointer argument is invalid.
+ * - ``EINVAL``
+ - The attribute set is not initialized.
+ * - ``EINVAL``
+ - The contention scope specified is not valid.
+ * - ``ENOTSUP``
+ - The contention scope specified (``PTHREAD_SCOPE_SYSTEM``) is not supported.
**DESCRIPTION:**
-The ``pthread_attr_setscope`` routine is used to set the contention
-scope field in the thread attribute object ``attr`` to the value
-specified by ``contentionscope``.
+The ``pthread_attr_setscope`` routine is used to set the contention scope field
+in the thread attribute object ``attr`` to the value specified by
+``contentionscope``.
-The ``contentionscope`` must be either ``PTHREAD_SCOPE_SYSTEM``
-to indicate that the thread is to be within system scheduling contention
-or ``PTHREAD_SCOPE_PROCESS`` indicating that the thread is to be
-within the process scheduling contention scope.
+The ``contentionscope`` must be either ``PTHREAD_SCOPE_SYSTEM`` to indicate
+that the thread is to be within system scheduling contention or
+``PTHREAD_SCOPE_PROCESS`` indicating that the thread is to be within the
+process scheduling contention scope.
**NOTES:**
-As required by POSIX, RTEMS defines the feature symbol``_POSIX_THREAD_PRIORITY_SCHEDULING`` to indicate that the
-family of routines to which this routine belongs is supported.
+As required by POSIX, RTEMS defines the feature symbol
+``_POSIX_THREAD_PRIORITY_SCHEDULING`` to indicate that the family of routines
+to which this routine belongs is supported.
+
+.. _pthread_attr_getscope:
pthread_attr_getscope - Get Thread Scheduling Scope
---------------------------------------------------
@@ -474,35 +512,39 @@ pthread_attr_getscope - Get Thread Scheduling Scope
**CALLING SEQUENCE:**
-.. code:: c
+.. code-block:: c
#include <pthread.h>
int pthread_attr_getscope(
- const pthread_attr_t \*attr,
- int \*contentionscope
+ const pthread_attr_t *attr,
+ int *contentionscope
);
**STATUS CODES:**
-*EINVAL*
- The attribute pointer argument is invalid.
-
-*EINVAL*
- The attribute set is not initialized.
+.. list-table::
+ :class: rtems-table
-*EINVAL*
- The contentionscope pointer argument is invalid.
+ * - ``EINVAL``
+ - The attribute pointer argument is invalid.
+ * - ``EINVAL``
+ - The attribute set is not initialized.
+ * - ``EINVAL``
+ - The contentionscope pointer argument is invalid.
**DESCRIPTION:**
-The ``pthread_attr_getscope`` routine is used to obtain the
-value of the contention scope field in the thread attributes
-object ``attr``. The current value is returned in``contentionscope``.
+The ``pthread_attr_getscope`` routine is used to obtain the value of the
+contention scope field in the thread attributes object ``attr``. The current
+value is returned in ``contentionscope``.
**NOTES:**
-As required by POSIX, RTEMS defines the feature symbol``_POSIX_THREAD_PRIORITY_SCHEDULING`` to indicate that the
-family of routines to which this routine belongs is supported.
+As required by POSIX, RTEMS defines the feature symbol
+``_POSIX_THREAD_PRIORITY_SCHEDULING`` to indicate that the family of routines
+to which this routine belongs is supported.
+
+.. _pthread_attr_setinheritsched:
pthread_attr_setinheritsched - Set Inherit Scheduler Flag
---------------------------------------------------------
@@ -511,44 +553,47 @@ pthread_attr_setinheritsched - Set Inherit Scheduler Flag
**CALLING SEQUENCE:**
-.. code:: c
+.. code-block:: c
#include <pthread.h>
int pthread_attr_setinheritsched(
- pthread_attr_t \*attr,
- int inheritsched
+ pthread_attr_t *attr,
+ int inheritsched
);
**STATUS CODES:**
-*EINVAL*
- The attribute pointer argument is invalid.
-
-*EINVAL*
- The attribute set is not initialized.
+.. list-table::
+ :class: rtems-table
-*EINVAL*
- The specified scheduler inheritance argument is invalid.
+ * - ``EINVAL``
+ - The attribute pointer argument is invalid.
+ * - ``EINVAL``
+ - The attribute set is not initialized.
+ * - ``EINVAL``
+ - The specified scheduler inheritance argument is invalid.
**DESCRIPTION:**
-The ``pthread_attr_setinheritsched`` routine is used to set the
-inherit scheduler field in the thread attribute object ``attr`` to
-the value specified by ``inheritsched``.
+The ``pthread_attr_setinheritsched`` routine is used to set the inherit
+scheduler field in the thread attribute object ``attr`` to the value specified
+by ``inheritsched``.
-The ``contentionscope`` must be either ``PTHREAD_INHERIT_SCHED``
-to indicate that the thread is to inherit the scheduling policy
-and parameters fromthe creating thread, or ``PTHREAD_EXPLICIT_SCHED``
-to indicate that the scheduling policy and parameters for this thread
-are to be set from the corresponding values in the attributes object.
-If ``contentionscope`` is ``PTHREAD_INHERIT_SCHED``, then the
-scheduling attributes in the ``attr`` structure will be ignored
-at thread creation time.
+The ``contentionscope`` must be either ``PTHREAD_INHERIT_SCHED`` to indicate
+that the thread is to inherit the scheduling policy and parameters fromthe
+creating thread, or ``PTHREAD_EXPLICIT_SCHED`` to indicate that the scheduling
+policy and parameters for this thread are to be set from the corresponding
+values in the attributes object. If ``contentionscope`` is
+``PTHREAD_INHERIT_SCHED``, then the scheduling attributes in the ``attr``
+structure will be ignored at thread creation time.
**NOTES:**
-As required by POSIX, RTEMS defines the feature symbol``_POSIX_THREAD_PRIORITY_SCHEDULING`` to indicate that the
-family of routines to which this routine belongs is supported.
+As required by POSIX, RTEMS defines the feature symbol
+``_POSIX_THREAD_PRIORITY_SCHEDULING`` to indicate that the family of routines
+to which this routine belongs is supported.
+
+.. _pthread_attr_getinheritsched:
pthread_attr_getinheritsched - Get Inherit Scheduler Flag
---------------------------------------------------------
@@ -557,35 +602,38 @@ pthread_attr_getinheritsched - Get Inherit Scheduler Flag
**CALLING SEQUENCE:**
-.. code:: c
+.. code-block:: c
#include <pthread.h>
int pthread_attr_getinheritsched(
- const pthread_attr_t \*attr,
- int \*inheritsched
+ const pthread_attr_t *attr,
+ int *inheritsched
);
**STATUS CODES:**
-*EINVAL*
- The attribute pointer argument is invalid.
+.. list-table::
+ :class: rtems-table
-*EINVAL*
- The attribute set is not initialized.
-
-*EINVAL*
- The inheritsched pointer argument is invalid.
+ * - ``EINVAL``
+ - The attribute pointer argument is invalid.
+ * - ``EINVAL``
+ - The attribute set is not initialized.
+ * - ``EINVAL``
+ - The inheritsched pointer argument is invalid.
**DESCRIPTION:**
-The ``pthread_attr_getinheritsched`` routine is used to
-object the current value of the inherit scheduler field in
-the thread attribute object ``attr``.
+The ``pthread_attr_getinheritsched`` routine is used to object the current
+value of the inherit scheduler field in the thread attribute object ``attr``.
**NOTES:**
-As required by POSIX, RTEMS defines the feature symbol``_POSIX_THREAD_PRIORITY_SCHEDULING`` to indicate that the
-family of routines to which this routine belongs is supported.
+As required by POSIX, RTEMS defines the feature symbol
+``_POSIX_THREAD_PRIORITY_SCHEDULING`` to indicate that the family of routines
+to which this routine belongs is supported.
+
+.. _pthread_attr_setschedpolicy:
pthread_attr_setschedpolicy - Set Scheduling Policy
---------------------------------------------------
@@ -594,30 +642,31 @@ pthread_attr_setschedpolicy - Set Scheduling Policy
**CALLING SEQUENCE:**
-.. code:: c
+.. code-block:: c
#include <pthread.h>
int pthread_attr_setschedpolicy(
- pthread_attr_t \*attr,
- int policy
+ pthread_attr_t *attr,
+ int policy
);
**STATUS CODES:**
-*EINVAL*
- The attribute pointer argument is invalid.
+.. list-table::
+ :class: rtems-table
-*EINVAL*
- The attribute set is not initialized.
-
-*ENOTSUP*
- The specified scheduler policy argument is invalid.
+ * - ``EINVAL``
+ - The attribute pointer argument is invalid.
+ * - ``EINVAL``
+ - The attribute set is not initialized.
+ * - ``ENOTSUP``
+ - The specified scheduler policy argument is invalid.
**DESCRIPTION:**
-The ``pthread_attr_setschedpolicy`` routine is used to set the
-scheduler policy field in the thread attribute object ``attr`` to
-the value specified by ``policy``.
+The ``pthread_attr_setschedpolicy`` routine is used to set the scheduler policy
+field in the thread attribute object ``attr`` to the value specified by
+``policy``.
Scheduling policies may be one of the following:
@@ -631,13 +680,15 @@ Scheduling policies may be one of the following:
- ``SCHED_OTHER``
-The precise meaning of each of these is discussed elsewhere in this
-manual.
+The precise meaning of each of these is discussed elsewhere in this manual.
**NOTES:**
-As required by POSIX, RTEMS defines the feature symbol``_POSIX_THREAD_PRIORITY_SCHEDULING`` to indicate that the
-family of routines to which this routine belongs is supported.
+As required by POSIX, RTEMS defines the feature symbol
+``_POSIX_THREAD_PRIORITY_SCHEDULING`` to indicate that the family of routines
+to which this routine belongs is supported.
+
+.. _pthread_attr_getschedpolicy:
pthread_attr_getschedpolicy - Get Scheduling Policy
---------------------------------------------------
@@ -646,35 +697,39 @@ pthread_attr_getschedpolicy - Get Scheduling Policy
**CALLING SEQUENCE:**
-.. code:: c
+.. code-block:: c
#include <pthread.h>
int pthread_attr_getschedpolicy(
- const pthread_attr_t \*attr,
- int \*policy
+ const pthread_attr_t *attr,
+ int *policy
);
**STATUS CODES:**
-*EINVAL*
- The attribute pointer argument is invalid.
-
-*EINVAL*
- The attribute set is not initialized.
+.. list-table::
+ :class: rtems-table
-*EINVAL*
- The specified scheduler policy argument pointer is invalid.
+ * - ``EINVAL``
+ - The attribute pointer argument is invalid.
+ * - ``EINVAL``
+ - The attribute set is not initialized.
+ * - ``EINVAL``
+ - The specified scheduler policy argument pointer is invalid.
**DESCRIPTION:**
-The ``pthread_attr_getschedpolicy`` routine is used to obtain the
-scheduler policy field from the thread attribute object ``attr``.
-The value of this field is returned in ``policy``.
+The ``pthread_attr_getschedpolicy`` routine is used to obtain the scheduler
+policy field from the thread attribute object ``attr``. The value of this
+field is returned in ``policy``.
**NOTES:**
-As required by POSIX, RTEMS defines the feature symbol``_POSIX_THREAD_PRIORITY_SCHEDULING`` to indicate that the
-family of routines to which this routine belongs is supported.
+As required by POSIX, RTEMS defines the feature symbol
+``_POSIX_THREAD_PRIORITY_SCHEDULING`` to indicate that the family of routines
+to which this routine belongs is supported.
+
+.. _pthread_attr_setschedparam:
pthread_attr_setschedparam - Set Scheduling Parameters
------------------------------------------------------
@@ -683,35 +738,39 @@ pthread_attr_setschedparam - Set Scheduling Parameters
**CALLING SEQUENCE:**
-.. code:: c
+.. code-block:: c
#include <pthread.h>
int pthread_attr_setschedparam(
- pthread_attr_t \*attr,
- const struct sched_param param
+ pthread_attr_t *attr,
+ const struct sched_param param
);
**STATUS CODES:**
-*EINVAL*
- The attribute pointer argument is invalid.
-
-*EINVAL*
- The attribute set is not initialized.
+.. list-table::
+ :class: rtems-table
-*EINVAL*
- The specified scheduler parameter argument is invalid.
+ * - ``EINVAL``
+ - The attribute pointer argument is invalid.
+ * - ``EINVAL``
+ - The attribute set is not initialized.
+ * - ``EINVAL``
+ - The specified scheduler parameter argument is invalid.
**DESCRIPTION:**
-The ``pthread_attr_setschedparam`` routine is used to set the
-scheduler parameters field in the thread attribute object ``attr`` to
-the value specified by ``param``.
+The ``pthread_attr_setschedparam`` routine is used to set the scheduler
+parameters field in the thread attribute object ``attr`` to the value specified
+by ``param``.
**NOTES:**
-As required by POSIX, RTEMS defines the feature symbol``_POSIX_THREAD_PRIORITY_SCHEDULING`` to indicate that the
-family of routines to which this routine belongs is supported.
+As required by POSIX, RTEMS defines the feature symbol
+``_POSIX_THREAD_PRIORITY_SCHEDULING`` to indicate that the family of routines
+to which this routine belongs is supported.
+
+.. _pthread_attr_getschedparam:
pthread_attr_getschedparam - Get Scheduling Parameters
------------------------------------------------------
@@ -720,114 +779,124 @@ pthread_attr_getschedparam - Get Scheduling Parameters
**CALLING SEQUENCE:**
-.. code:: c
+.. code-block:: c
#include <pthread.h>
int pthread_attr_getschedparam(
- const pthread_attr_t \*attr,
- struct sched_param \*param
+ const pthread_attr_t *attr,
+ struct sched_param *param
);
**STATUS CODES:**
-*EINVAL*
- The attribute pointer argument is invalid.
-
-*EINVAL*
- The attribute set is not initialized.
+.. list-table::
+ :class: rtems-table
-*EINVAL*
- The specified scheduler parameter argument pointer is invalid.
+ * - ``EINVAL``
+ - The attribute pointer argument is invalid.
+ * - ``EINVAL``
+ - The attribute set is not initialized.
+ * - ``EINVAL``
+ - The specified scheduler parameter argument pointer is invalid.
**DESCRIPTION:**
-The ``pthread_attr_getschedparam`` routine is used to obtain the
-scheduler parameters field from the thread attribute object ``attr``.
-The value of this field is returned in ``param``.
+The ``pthread_attr_getschedparam`` routine is used to obtain the scheduler
+parameters field from the thread attribute object ``attr``. The value of this
+field is returned in ``param``.
**NOTES:**
-As required by POSIX, RTEMS defines the feature symbol``_POSIX_THREAD_PRIORITY_SCHEDULING`` to indicate that the
-family of routines to which this routine belongs is supported.
+As required by POSIX, RTEMS defines the feature symbol
+``_POSIX_THREAD_PRIORITY_SCHEDULING`` to indicate that the family of routines
+to which this routine belongs is supported.
+
+.. _pthread_attr_getaffinity_np:
pthread_attr_getaffinity_np - Get Thread Affinity Attribute
-----------------------------------------------------------
**CALLING SEQUENCE:**
-.. code:: c
+.. code-block:: c
#define _GNU_SOURCE
#include <pthread.h>
int pthread_attr_getaffinity_np(
- const pthread_attr_t \*attr,
- size_t cpusetsize,
- cpu_set_t \*cpuset
+ const pthread_attr_t *attr,
+ size_t cpusetsize,
+ cpu_set_t *cpuset
);
**STATUS CODES:**
-*EFAULT*
- The attribute pointer argument is invalid.
+.. list-table::
+ :class: rtems-table
-*EFAULT*
- The cpuset pointer argument is invalid.
-
-*EINVAL*
- The ``cpusetsize`` does not match the value of ``affinitysetsize``
- field in the thread attribute object.
+ * - ``EFAULT``
+ - The attribute pointer argument is invalid.
+ * - ``EFAULT``
+ - The cpuset pointer argument is invalid.
+ * - ``EINVAL``
+ - The ``cpusetsize`` does not match the value of ``affinitysetsize`` field
+ in the thread attribute object.
**DESCRIPTION:**
-The ``pthread_attr_getaffinity_np`` routine is used to obtain the``affinityset`` field from the thread attribute object ``attr``.
-The value of this field is returned in ``cpuset``.
+The ``pthread_attr_getaffinity_np`` routine is used to obtain the
+``affinityset`` field from the thread attribute object ``attr``. The value of
+this field is returned in ``cpuset``.
**NOTES:**
NONE
+.. _pthread_attr_setaffinity_np:
+
pthread_attr_setaffinity_np - Set Thread Affinity Attribute
-----------------------------------------------------------
**CALLING SEQUENCE:**
-.. code:: c
+.. code-block:: c
#define _GNU_SOURCE
#include <pthread.h>
int pthread_attr_setaffinity_np(
- pthread_attr_t \*attr,
- size_t cpusetsize,
- const cpu_set_t \*cpuset
+ pthread_attr_t *attr,
+ size_t cpusetsize,
+ const cpu_set_t *cpuset
);
**STATUS CODES:**
-*EFAULT*
- The attribute pointer argument is invalid.
-
-*EFAULT*
- The cpuset pointer argument is invalid.
-
-*EINVAL*
- The ``cpusetsize`` does not match the value of ``affinitysetsize``
- field in the thread attribute object.
-
-*EINVAL*
- The ``cpuset`` did not select a valid cpu.
-
-*EINVAL*
- The ``cpuset`` selected a cpu that was invalid.
+.. list-table::
+ :class: rtems-table
+
+ * - ``EFAULT``
+ - The attribute pointer argument is invalid.
+ * - ``EFAULT``
+ - The cpuset pointer argument is invalid.
+ * - ``EINVAL``
+ - The ``cpusetsize`` does not match the value of ``affinitysetsize`` field
+ in the thread attribute object.
+ * - ``EINVAL``
+ - The ``cpuset`` did not select a valid cpu.
+ * - ``EINVAL``
+ - The ``cpuset`` selected a cpu that was invalid.
**DESCRIPTION:**
-The ``pthread_attr_setaffinity_np`` routine is used to set the``affinityset`` field in the thread attribute object ``attr``.
-The value of this field is returned in ``cpuset``.
+The ``pthread_attr_setaffinity_np`` routine is used to set the ``affinityset``
+field in the thread attribute object ``attr``. The value of this field is
+returned in ``cpuset``.
**NOTES:**
NONE
+.. _pthread_create:
+
pthread_create - Create a Thread
--------------------------------
.. index:: pthread_create
@@ -835,76 +904,72 @@ pthread_create - Create a Thread
**CALLING SEQUENCE:**
-.. code:: c
+.. code-block:: c
#include <pthread.h>
int pthread_create(
- pthread_t \*thread,
- const pthread_attr_t \*attr,
- void (\*start_routine)( void \*),
- void \*arg
+ pthread_t *thread,
+ const pthread_attr_t *attr,
+ void (*start_routine)( void *),
+ void *arg
);
**STATUS CODES:**
-*EINVAL*
- The attribute set is not initialized.
-
-*EINVAL*
- The user specified a stack address and the size of the area was not
- large enough to meet this processor's minimum stack requirements.
-
-*EINVAL*
- The specified scheduler inheritance policy was invalid.
-
-*ENOTSUP*
- The specified contention scope was PTHREAD_SCOPE_PROCESS.
-
-*EINVAL*
- The specified thread priority was invalid.
-
-*EINVAL*
- The specified scheduling policy was invalid.
-
-*EINVAL*
- The scheduling policy was SCHED_SPORADIC and the specified replenishment
- period is less than the initial budget.
-
-*EINVAL*
- The scheduling policy was SCHED_SPORADIC and the specified low priority
- is invalid.
-
-*EAGAIN*
- The system lacked the necessary resources to create another thread, or the
- self imposed limit on the total number of threads in a process
- PTHREAD_THREAD_MAX would be exceeded.
-
-*EINVAL*
- Invalid argument passed.
+.. list-table::
+ :class: rtems-table
+
+ * - ``EINVAL``
+ - The attribute set is not initialized.
+ * - ``EINVAL``
+ - The user specified a stack address and the size of the area was not large
+ enough to meet this processor's minimum stack requirements.
+ * - ``EINVAL``
+ - The specified scheduler inheritance policy was invalid.
+ * - ``ENOTSUP``
+ - The specified contention scope was ``PTHREAD_SCOPE_PROCESS``.
+ * - ``EINVAL``
+ - The specified thread priority was invalid.
+ * - ``EINVAL``
+ - The specified scheduling policy was invalid.
+ * - ``EINVAL``
+ - The scheduling policy was ``SCHED_SPORADIC`` and the specified
+ replenishment period is less than the initial budget.
+ * - ``EINVAL``
+ - The scheduling policy was ``SCHED_SPORADIC`` and the specified low
+ priority is invalid.
+ * - ``EAGAIN``
+ - The system lacked the necessary resources to create another thread, or the
+ self imposed limit on the total number of threads in a process
+ ``PTHREAD_THREAD_MAX`` would be exceeded.
+ * - ``EINVAL``
+ - Invalid argument passed.
**DESCRIPTION:**
-The ``pthread_create`` routine is used to create a new thread with
-the attributes specified by ``attr``. If the ``attr`` argument
-is ``NULL``, then the default attribute set will be used. Modification
-of the contents of ``attr`` after this thread is created does not
-have an impact on this thread.
+The ``pthread_create`` routine is used to create a new thread with the
+attributes specified by ``attr``. If the ``attr`` argument is ``NULL``, then
+the default attribute set will be used. Modification of the contents of
+``attr`` after this thread is created does not have an impact on this thread.
-The thread begins execution at the address specified by ``start_routine``
-with ``arg`` as its only argument. If ``start_routine`` returns,
-then it is functionally equivalent to the thread executing the``pthread_exit`` service.
+The thread begins execution at the address specified by ``start_routine`` with
+``arg`` as its only argument. If ``start_routine`` returns, then it is
+functionally equivalent to the thread executing the ``pthread_exit`` service.
-Upon successful completion, the ID of the created thread is returned in the``thread`` argument.
+Upon successful completion, the ID of the created thread is returned in the
+``thread`` argument.
**NOTES:**
-There is no concept of a single main thread in RTEMS as there is in
-a tradition UNIX system. POSIX requires that the implicit return of
-the main thread results in the same effects as if there were a call
-to ``exit``. This does not occur in RTEMS.
+There is no concept of a single main thread in RTEMS as there is in a tradition
+UNIX system. POSIX requires that the implicit return of the main thread results
+in the same effects as if there were a call to ``exit``. This does not occur in
+RTEMS.
-The signal mask of the newly created thread is inherited from its
-creator and the set of pending signals for this thread is empty.
+The signal mask of the newly created thread is inherited from its creator and
+the set of pending signals for this thread is empty.
+
+.. _pthread_exit:
pthread_exit - Terminate the Current Thread
-------------------------------------------
@@ -913,11 +978,11 @@ pthread_exit - Terminate the Current Thread
**CALLING SEQUENCE:**
-.. code:: c
+.. code-block:: c
#include <pthread.h>
void pthread_exit(
- void \*status
+ void *status
);
**STATUS CODES:**
@@ -926,37 +991,37 @@ pthread_exit - Terminate the Current Thread
**DESCRIPTION:**
-The ``pthread_exit`` routine is used to terminate the calling thread.
-The ``status`` is made available to any successful join with the
-terminating thread.
+The ``pthread_exit`` routine is used to terminate the calling thread. The
+``status`` is made available to any successful join with the terminating
+thread.
-When a thread returns from its start routine, it results in an
-implicit call to the ``pthread_exit`` routine with the return
-value of the function serving as the argument to ``pthread_exit``.
+When a thread returns from its start routine, it results in an implicit call to
+the ``pthread_exit`` routine with the return value of the function serving as
+the argument to ``pthread_exit``.
**NOTES:**
Any cancellation cleanup handlers that hace been pushed and not yet popped
-shall be popped in reverse of the order that they were pushed. After
-all cancellation cleanup handlers have been executed, if the
-thread has any thread-specific data, destructors for that data will
-be invoked.
-
-Thread termination does not release or free any application visible
-resources including byt not limited to mutexes, file descriptors, allocated
-memory, etc.. Similarly, exitting a thread does not result in any
-process-oriented cleanup activity.
-
-There is no concept of a single main thread in RTEMS as there is in
-a tradition UNIX system. POSIX requires that the implicit return of
-the main thread results in the same effects as if there were a call
-to ``exit``. This does not occur in RTEMS.
-
-All access to any automatic variables allocated by the threads is lost
-when the thread exits. Thus references (i.e. pointers) to local variables
-of a thread should not be used in a global manner without care. As
-a specific example, a pointer to a local variable should NOT be used
-as the return value.
+shall be popped in reverse of the order that they were pushed. After all
+cancellation cleanup handlers have been executed, if the thread has any
+thread-specific data, destructors for that data will be invoked.
+
+Thread termination does not release or free any application visible resources
+including byt not limited to mutexes, file descriptors, allocated memory,
+etc.. Similarly, exitting a thread does not result in any process-oriented
+cleanup activity.
+
+There is no concept of a single main thread in RTEMS as there is in a tradition
+UNIX system. POSIX requires that the implicit return of the main thread results
+in the same effects as if there were a call to ``exit``. This does not occur in
+RTEMS.
+
+All access to any automatic variables allocated by the threads is lost when the
+thread exits. Thus references (i.e. pointers) to local variables of a thread
+should not be used in a global manner without care. As a specific example, a
+pointer to a local variable should NOT be used as the return value.
+
+.. _pthread_detach:
pthread_detach - Detach a Thread
--------------------------------
@@ -965,34 +1030,39 @@ pthread_detach - Detach a Thread
**CALLING SEQUENCE:**
-.. code:: c
+.. code-block:: c
#include <pthread.h>
int pthread_detach(
- pthread_t thread
+ pthread_t thread
);
**STATUS CODES:**
-*ESRCH*
- The thread specified is invalid.
+.. list-table::
+ :class: rtems-table
-*EINVAL*
- The thread specified is not a joinable thread.
+ * - ``ESRCH``
+ - The thread specified is invalid.
+ * - ``EINVAL``
+ - The thread specified is not a joinable thread.
**DESCRIPTION:**
-The ``pthread_detach`` routine is used to to indicate that storage
-for ``thread`` can be reclaimed when the thread terminates without
-another thread joinging with it.
+The ``pthread_detach`` routine is used to to indicate that storage for
+``thread`` can be reclaimed when the thread terminates without another thread
+joinging with it.
**NOTES:**
-If any threads have previously joined with the specified thread, then they
-will remain joined with that thread. Any subsequent calls to``pthread_join`` on the specified thread will fail.
+If any threads have previously joined with the specified thread, then they will
+remain joined with that thread. Any subsequent calls to ``pthread_join`` on the
+specified thread will fail.
.. COMMENT: pthread_getattr_np
+.. _pthread_getattr_np:
+
pthread_getattr_np - Get Thread Attributes
------------------------------------------
.. index:: pthread_getattr_np
@@ -1000,32 +1070,36 @@ pthread_getattr_np - Get Thread Attributes
**CALLING SEQUENCE:**
-.. code:: c
+.. code-block:: c
#define _GNU_SOURCE
#include <pthread.h>
int pthread_getattr_np(
- pthread_t thread,
- pthread_attr_t \*attr
+ pthread_t thread,
+ pthread_attr_t *attr
);
**STATUS CODES:**
-*ESRCH*
- The thread specified is invalid.
+.. list-table::
+ :class: rtems-table
-*EINVAL*
- The attribute pointer argument is invalid.
+ * - ``ESRCH``
+ - The thread specified is invalid.
+ * - ``EINVAL``
+ - The attribute pointer argument is invalid.
**DESCRIPTION:**
-The ``pthread_getattr_np`` routine is used to obtain the
-attributes associated with ``thread``.
+The ``pthread_getattr_np`` routine is used to obtain the attributes associated
+with ``thread``.
**NOTES:**
-Modification of the execution modes and priority through the Classic API
-may result in a combination that is not representable in the POSIX API.
+Modification of the execution modes and priority through the Classic API may
+result in a combination that is not representable in the POSIX API.
+
+.. _pthread_join:
pthread_join - Wait for Thread Termination
------------------------------------------
@@ -1034,31 +1108,32 @@ pthread_join - Wait for Thread Termination
**CALLING SEQUENCE:**
-.. code:: c
+.. code-block:: c
#include <pthread.h>
int pthread_join(
- pthread_t thread,
- void \**value_ptr
+ pthread_t thread,
+ void **value_ptr
);
**STATUS CODES:**
-*ESRCH*
- The thread specified is invalid.
-
-*EINVAL*
- The thread specified is not a joinable thread.
+.. list-table::
+ :class: rtems-table
-*EDEADLK*
- A deadlock was detected or thread is the calling thread.
+ * - ``ESRCH``
+ - The thread specified is invalid.
+ * - ``EINVAL``
+ - The thread specified is not a joinable thread.
+ * - ``EDEADLK``
+ - A deadlock was detected or thread is the calling thread.
**DESCRIPTION:**
-The ``pthread_join`` routine suspends execution of the calling thread
-until ``thread`` terminates. If ``thread`` has already terminated,
-then this routine returns immediately. The value returned by ``thread``
-(i.e. passed to ``pthread_exit`` is returned in ``value_ptr``.
+The ``pthread_join`` routine suspends execution of the calling thread until
+``thread`` terminates. If ``thread`` has already terminated, then this routine
+returns immediately. The value returned by ``thread`` (i.e. passed to
+``pthread_exit`` is returned in ``value_ptr``.
When this routine returns, then ``thread`` has been terminated.
@@ -1066,11 +1141,14 @@ When this routine returns, then ``thread`` has been terminated.
The results of multiple simultaneous joins on the same thread is undefined.
-If any threads have previously joined with the specified thread, then they
-will remain joined with that thread. Any subsequent calls to``pthread_join`` on the specified thread will fail.
+If any threads have previously joined with the specified thread, then they will
+remain joined with that thread. Any subsequent calls to ``pthread_join`` on the
+specified thread will fail.
If value_ptr is NULL, then no value is returned.
+.. _pthread_self:
+
pthread_self - Get Thread ID
----------------------------
.. index:: pthread_self
@@ -1078,7 +1156,7 @@ pthread_self - Get Thread ID
**CALLING SEQUENCE:**
-.. code:: c
+.. code-block:: c
#include <pthread.h>
pthread_t pthread_self( void );
@@ -1095,6 +1173,8 @@ This routine returns the ID of the calling thread.
NONE
+.. _pthread_equal:
+
pthread_equal - Compare Thread IDs
----------------------------------
.. index:: pthread_equal
@@ -1102,31 +1182,35 @@ pthread_equal - Compare Thread IDs
**CALLING SEQUENCE:**
-.. code:: c
+.. code-block:: c
#include <pthread.h>
int pthread_equal(
- pthread_t t1,
- pthread_t t2
+ pthread_t t1,
+ pthread_t t2
);
**STATUS CODES:**
-*zero*
- The thread ids are not equal.
+.. list-table::
+ :class: rtems-table
-*non-zero*
- The thread ids are equal.
+ * - ``zero``
+ - The thread ids are not equal.
+ * - ``non-zero``
+ - The thread ids are equal.
**DESCRIPTION:**
-The ``pthread_equal`` routine is used to compare two thread
-IDs and determine if they are equal.
+The ``pthread_equal`` routine is used to compare two thread IDs and determine
+if they are equal.
**NOTES:**
The behavior is undefined if the thread IDs are not valid.
+.. _pthread_once:
+
pthread_once - Dynamic Package Initialization
---------------------------------------------
.. index:: pthread_once
@@ -1134,13 +1218,13 @@ pthread_once - Dynamic Package Initialization
**CALLING SEQUENCE:**
-.. code:: c
+.. code-block:: c
#include <pthread.h>
pthread_once_t once_control = PTHREAD_ONCE_INIT;
int pthread_once(
- pthread_once_t \*once_control,
- void (\*init_routine)(void)
+ pthread_once_t *once_control,
+ void (*init_routine)(void)
);
**STATUS CODES:**
@@ -1149,19 +1233,22 @@ NONE
**DESCRIPTION:**
-The ``pthread_once`` routine is used to provide controlled initialization
-of variables. The first call to ``pthread_once`` by any thread with the
-same ``once_control`` will result in the ``init_routine`` being
-invoked with no arguments. Subsequent calls to ``pthread_once`` with
-the same ``once_control`` will have no effect.
+The ``pthread_once`` routine is used to provide controlled initialization of
+variables. The first call to ``pthread_once`` by any thread with the same
+``once_control`` will result in the ``init_routine`` being invoked with no
+arguments. Subsequent calls to ``pthread_once`` with the same ``once_control``
+will have no effect.
-The ``init_routine`` is guaranteed to have run to completion when
-this routine returns to the caller.
+The ``init_routine`` is guaranteed to have run to completion when this routine
+returns to the caller.
**NOTES:**
-The behavior of ``pthread_once`` is undefined if ``once_control``
-is automatic storage (i.e. on a task stack) or is not initialized using``PTHREAD_ONCE_INIT``.
+The behavior of ``pthread_once`` is undefined if ``once_control`` is automatic
+storage (i.e. on a task stack) or is not initialized using
+``PTHREAD_ONCE_INIT``.
+
+.. _pthread_setschedparam:
pthread_setschedparam - Set Thread Scheduling Parameters
--------------------------------------------------------
@@ -1170,46 +1257,47 @@ pthread_setschedparam - Set Thread Scheduling Parameters
**CALLING SEQUENCE:**
-.. code:: c
+.. code-block:: c
#include <pthread.h>
int pthread_setschedparam(
- pthread_t thread,
- int policy,
- struct sched_param \*param
+ pthread_t thread,
+ int policy,
+ struct sched_param *param
);
**STATUS CODES:**
-*EINVAL*
- The scheduling parameters indicated by the parameter param is invalid.
-
-*EINVAL*
- The value specified by policy is invalid.
-
-*EINVAL*
- The scheduling policy was SCHED_SPORADIC and the specified replenishment
- period is less than the initial budget.
-
-*EINVAL*
- The scheduling policy was SCHED_SPORADIC and the specified low priority
- is invalid.
-
-*ESRCH*
- The thread indicated was invalid.
+.. list-table::
+ :class: rtems-table
+
+ * - ``EINVAL``
+ - The scheduling parameters indicated by the parameter param is invalid.
+ * - ``EINVAL``
+ - The value specified by policy is invalid.
+ * - ``EINVAL``
+ - The scheduling policy was ``SCHED_SPORADIC`` and the specified
+ replenishment period is less than the initial budget.
+ * - ``EINVAL``
+ - The scheduling policy was ``SCHED_SPORADIC`` and the specified low
+ priority is invalid.
+ * - ``ESRCH``
+ - The thread indicated was invalid.
**DESCRIPTION:**
-The ``pthread_setschedparam`` routine is used to set the
-scheduler parameters currently associated with the thread specified
-by ``thread`` to the policy specified by ``policy``. The
-contents of ``param`` are interpreted based upon the ``policy``
-argument.
+The ``pthread_setschedparam`` routine is used to set the scheduler parameters
+currently associated with the thread specified by ``thread`` to the policy
+specified by ``policy``. The contents of ``param`` are interpreted based upon
+the ``policy`` argument.
**NOTES:**
-As required by POSIX, RTEMS defines the feature symbol``_POSIX_THREAD_PRIORITY_SCHEDULING`` to indicate that the
-family of routines to which this routine belongs is supported.
+As required by POSIX, RTEMS defines the feature symbol
+``_POSIX_THREAD_PRIORITY_SCHEDULING`` to indicate that the family of routines
+to which this routine belongs is supported.
+
+.. _pthread_getschedparam:
pthread_getschedparam - Get Thread Scheduling Parameters
--------------------------------------------------------
@@ -1218,67 +1306,74 @@ pthread_getschedparam - Get Thread Scheduling Parameters
**CALLING SEQUENCE:**
-.. code:: c
+.. code-block:: c
#include <pthread.h>
int pthread_getschedparam(
- pthread_t thread,
- int \*policy,
- struct sched_param \*param
+ pthread_t thread,
+ int *policy,
+ struct sched_param *param
);
**STATUS CODES:**
-*EINVAL*
- The policy pointer argument is invalid.
+.. list-table::
+ :class: rtems-table
-*EINVAL*
- The scheduling parameters pointer argument is invalid.
-
-*ESRCH*
- The thread indicated by the parameter thread is invalid.
+ * - ``EINVAL``
+ - The policy pointer argument is invalid.
+ * - ``EINVAL``
+ - The scheduling parameters pointer argument is invalid.
+ * - ``ESRCH``
+ - The thread indicated by the parameter thread is invalid.
**DESCRIPTION:**
-The ``pthread_getschedparam`` routine is used to obtain the
-scheduler policy and parameters associated with ``thread``.
-The current policy and associated parameters values returned in``policy`` and ``param``, respectively.
+The ``pthread_getschedparam`` routine is used to obtain the scheduler policy
+and parameters associated with ``thread``. The current policy and associated
+parameters values returned in``policy`` and ``param``, respectively.
**NOTES:**
-As required by POSIX, RTEMS defines the feature symbol``_POSIX_THREAD_PRIORITY_SCHEDULING`` to indicate that the
-family of routines to which this routine belongs is supported.
+As required by POSIX, RTEMS defines the feature symbol
+``_POSIX_THREAD_PRIORITY_SCHEDULING`` to indicate that the family of routines
+to which this routine belongs is supported.
.. COMMENT: pthread_getaffinity_np
+.. _pthread_getaffinity_np:
+
pthread_getaffinity_np - Get Thread Affinity
--------------------------------------------
**CALLING SEQUENCE:**
-.. code:: c
+.. code-block:: c
#define _GNU_SOURCE
#include <pthread.h>
int pthread_getaffinity_np(
- const pthread_t id,
- size_t cpusetsize,
- cpu_set_t \*cpuset
+ const pthread_t id,
+ size_t cpusetsize,
+ cpu_set_t *cpuset
);
**STATUS CODES:**
-*EFAULT*
- The cpuset pointer argument is invalid.
+.. list-table::
+ :class: rtems-table
-*EINVAL*
- The ``cpusetsize`` does not match the value of ``affinitysetsize``
- field in the thread attribute object.
+ * - ``EFAULT``
+ - The cpuset pointer argument is invalid.
+ * - ``EINVAL``
+ - The ``cpusetsize`` does not match the value of ``affinitysetsize`` field
+ in the thread attribute object.
**DESCRIPTION:**
-The ``pthread_getaffinity_np`` routine is used to obtain the``affinity.set`` field from the thread control object associated
-with the ``id``. The value of this field is returned in ``cpuset``.
+The ``pthread_getaffinity_np`` routine is used to obtain the ``affinity.set``
+field from the thread control object associated with the ``id``. The value of
+this field is returned in ``cpuset``.
**NOTES:**
@@ -1286,48 +1381,43 @@ NONE
.. COMMENT: pthread_setaffinity_np
+.. _pthread_setaffinity_np:
+
pthread_setaffinity_np - Set Thread Affinity
--------------------------------------------
**CALLING SEQUENCE:**
-.. code:: c
+.. code-block:: c
#define _GNU_SOURCE
#include <pthread.h>
int pthread_setaffinity_np(
- pthread_t id,
- size_t cpusetsize,
- const cpu_set_t \*cpuset
+ pthread_t id,
+ size_t cpusetsize,
+ const cpu_set_t *cpuset
);
**STATUS CODES:**
-*EFAULT*
- The cpuset pointer argument is invalid.
-
-*EINVAL*
- The ``cpusetsize`` does not match the value of ``affinitysetsize``
- field in the thread attribute object.
-
-*EINVAL*
- The ``cpuset`` did not select a valid cpu.
+.. list-table::
+ :class: rtems-table
-*EINVAL*
- The ``cpuset`` selected a cpu that was invalid.
+ * - ``EFAULT``
+ - The cpuset pointer argument is invalid.
+ * - ``EINVAL``
+ - The ``cpusetsize`` does not match the value of ``affinitysetsize`` field
+ in the thread attribute object.
+ * - ``EINVAL``
+ - The ``cpuset`` did not select a valid cpu.
+ * - ``EINVAL``
+ - The ``cpuset`` selected a cpu that was invalid.
**DESCRIPTION:**
-The ``pthread_setaffinity_np`` routine is used to set the``affinityset`` field of the thread object ``id``.
-The value of this field is returned in ``cpuset``
+The ``pthread_setaffinity_np`` routine is used to set the ``affinityset`` field
+of the thread object ``id``. The value of this field is returned in ``cpuset``
**NOTES:**
NONE
-
-.. COMMENT: COPYRIGHT (c) 1988-2002.
-
-.. COMMENT: On-Line Applications Research Corporation (OAR).
-
-.. COMMENT: All rights reserved.
-
diff --git a/posix_users/thread_cancellation.rst b/posix_users/thread_cancellation.rst
index 5a70c40..67c7a78 100644
--- a/posix_users/thread_cancellation.rst
+++ b/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.
-A subsection is dedicated to each of this manager's directives
-and describes the calling sequence, related constants, usage,
-and status codes.
+This section details the thread cancellation manager's directives. A
+subsection is dedicated to each of this manager's directives and describes the
+calling sequence, related constants, usage, and status codes.
+
+.. _pthread_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*
- The
+.. list-table::
+ :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*
- The
+.. list-table::
+ :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*
- The
+.. list-table::
+ :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*
- The
+.. list-table::
+ :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*
- The
+.. list-table::
+ :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*
- The
+.. list-table::
+ :class: rtems-table
+
+ * - ``E``
+ - The
**DESCRIPTION:**
**NOTES:**
-
-.. COMMENT: COPYRIGHT (c) 1988-2002.
-
-.. COMMENT: On-Line Applications Research Corporation (OAR).
-
-.. COMMENT: All rights reserved.
-
diff --git a/posix_users/timer.rst b/posix_users/timer.rst
index 36801d8..f08bc04 100644
--- a/posix_users/timer.rst
+++ b/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.
-A subsection is dedicated to each of this manager's services
-and describes the calling sequence, related constants, usage,
-and status codes.
+This section details the timer manager's services. A subsection is dedicated
+to each of this manager's services and describes the calling sequence, related
+constants, usage, and status codes.
.. 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,
- struct sigevent \*evp,
- timer_t \*timerid
+ clockid_t clock_id,
+ struct sigevent *evp,
+ 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,
- int flags,
- const struct itimerspec \*value,
- struct itimerspec \*ovalue
+ timer_t timerid,
+ int flags,
+ const struct itimerspec *value,
+ 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,
- struct itimerspec \*value
+ timer_t timerid,
+ 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.
-