diff options
| author | Chris Johns <chrisj@rtems.org> | 2016-02-26 18:22:07 +1100 |
|---|---|---|
| committer | Amar Takhar <verm@darkbeer.org> | 2016-05-02 20:51:26 -0400 |
| commit | fa70fd20878e402610c263f129266593d31a0376 (patch) | |
| tree | c609d33c7047b975cfe8e0ac0df020fb26dae255 /posix_users | |
| parent | Update the shell user's guide top level. (diff) | |
| download | rtems-docs-fa70fd20878e402610c263f129266593d31a0376.tar.bz2 | |
POSIX User clean up.
Diffstat (limited to 'posix_users')
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. - |