From 72a62ad88f82fe1ffee50024db4dd0f3fa5806f7 Mon Sep 17 00:00:00 2001 From: Chris Johns Date: Thu, 3 Nov 2016 16:58:08 +1100 Subject: Rename all manuals with an _ to have a -. It helps released naming of files. --- posix-users/clock.rst | 341 +++++ posix-users/command.rst | 7 + posix-users/condition_variable.rst | 361 +++++ posix-users/conf.py | 13 + posix-users/device_and_class_specific.rst | 460 ++++++ posix-users/files_and_directory.rst | 1943 ++++++++++++++++++++++++ posix-users/index.rst | 67 + posix-users/input_and_output.rst | 1040 +++++++++++++ posix-users/key.rst | 212 +++ posix-users/language_specific_services.rst | 621 ++++++++ posix-users/memory_managment.rst | 313 ++++ posix-users/message_passing.rst | 741 +++++++++ posix-users/mutex.rst | 673 ++++++++ posix-users/preface.rst | 52 + posix-users/process_creation_and_execution.rst | 421 +++++ posix-users/process_environment.rst | 807 ++++++++++ posix-users/scheduler.rst | 209 +++ posix-users/semaphore.rst | 543 +++++++ posix-users/services_provided_by_c.rst | 442 ++++++ posix-users/services_provided_by_math.rst | 98 ++ posix-users/signal.rst | 989 ++++++++++++ posix-users/status_of_implementation.rst | 46 + posix-users/system_database.rst | 256 ++++ posix-users/thread.rst | 1425 +++++++++++++++++ posix-users/thread_cancellation.rst | 201 +++ posix-users/timer.rst | 165 ++ posix-users/wscript | 6 + 27 files changed, 12452 insertions(+) create mode 100644 posix-users/clock.rst create mode 100644 posix-users/command.rst create mode 100644 posix-users/condition_variable.rst create mode 100644 posix-users/conf.py create mode 100644 posix-users/device_and_class_specific.rst create mode 100644 posix-users/files_and_directory.rst create mode 100644 posix-users/index.rst create mode 100644 posix-users/input_and_output.rst create mode 100644 posix-users/key.rst create mode 100644 posix-users/language_specific_services.rst create mode 100644 posix-users/memory_managment.rst create mode 100644 posix-users/message_passing.rst create mode 100644 posix-users/mutex.rst create mode 100644 posix-users/preface.rst create mode 100644 posix-users/process_creation_and_execution.rst create mode 100644 posix-users/process_environment.rst create mode 100644 posix-users/scheduler.rst create mode 100644 posix-users/semaphore.rst create mode 100644 posix-users/services_provided_by_c.rst create mode 100644 posix-users/services_provided_by_math.rst create mode 100644 posix-users/signal.rst create mode 100644 posix-users/status_of_implementation.rst create mode 100644 posix-users/system_database.rst create mode 100644 posix-users/thread.rst create mode 100644 posix-users/thread_cancellation.rst create mode 100644 posix-users/timer.rst create mode 100644 posix-users/wscript (limited to 'posix-users') diff --git a/posix-users/clock.rst b/posix-users/clock.rst new file mode 100644 index 0000000..e3387e7 --- /dev/null +++ b/posix-users/clock.rst @@ -0,0 +1,341 @@ +.. comment SPDX-License-Identifier: CC-BY-SA-4.0 + +.. 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 directives provided by the clock manager are: + +- clock_gettime_ - Obtain Time of Day + +- clock_settime_ - Set Time of Day + +- clock_getres_ - Get Clock Resolution + +- sleep_ - Delay Process Execution + +- usleep_ - Delay Process Execution in Microseconds + +- nanosleep_ - Delay with High Resolution + +- gettimeofday_ - Get the Time of Day + +- time_ - Get time in seconds + +Background +========== + +There is currently no text in this section. + +Operations +========== + +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. + +.. _clock_gettime: + +clock_gettime - Obtain Time of Day +---------------------------------- +.. index:: clock_gettime +.. index:: obtain time of day + +**CALLING SEQUENCE:** + +.. code-block:: c + + #include + int clock_gettime( + clockid_t clock_id, + struct timespec *tp + ); + +**STATUS CODES:** + +On error, this routine returns -1 and sets ``errno`` to one of the following: + +.. list-table:: + :class: rtems-table + + * - ``EINVAL`` + - The tp pointer parameter is invalid. + * - ``EINVAL`` + - The clock_id specified is invalid. + +**DESCRIPTION:** + +**NOTES:** + +NONE + +.. _clock_settime: + +clock_settime - Set Time of Day +------------------------------- +.. index:: clock_settime +.. index:: set time of day + +**CALLING SEQUENCE:** + +.. code-block:: c + + #include + int clock_settime( + clockid_t clock_id, + const struct timespec *tp + ); + +**STATUS CODES:** + +On error, this routine returns -1 and sets ``errno`` to one of the following: + +.. list-table:: + :class: rtems-table + + * - ``EINVAL`` + - The tp pointer parameter is invalid. + * - ``EINVAL`` + - The clock_id specified is invalid. + * - ``EINVAL`` + - The contents of the tp structure are invalid. + +**DESCRIPTION:** + +**NOTES:** + +NONE + +.. _clock_getres: + +clock_getres - Get Clock Resolution +----------------------------------- +.. index:: clock_getres +.. index:: get clock resolution + +**CALLING SEQUENCE:** + +.. code-block:: c + + #include + int clock_getres( + clockid_t clock_id, + struct timespec *res + ); + +**STATUS CODES:** + +On error, this routine returns -1 and sets ``errno`` to one of the following: + +.. list-table:: + :class: rtems-table + + * - ``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. + +.. _sleep: + +sleep - Delay Process Execution +------------------------------- +.. index:: sleep +.. index:: delay process execution + +**CALLING SEQUENCE:** + +.. code-block:: c + + #include + unsigned int sleep( + unsigned int seconds + ); + +**STATUS CODES:** + +This routine returns the number of unslept seconds. + +**DESCRIPTION:** + +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 +.. index:: delay process execution +.. index:: delay process execution +.. index:: usecs delay process execution +.. index:: microsecond delay process execution + +**CALLING SEQUENCE:** + +.. code-block:: c + + #include + useconds_t usleep( + useconds_t useconds + ); + +**STATUS CODES:** + +This routine returns the number of unslept seconds. + +**DESCRIPTION:** + +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. + +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. + +.. _nanosleep: + +nanosleep - Delay with High Resolution +-------------------------------------- +.. index:: nanosleep +.. index:: delay with high resolution + +**CALLING SEQUENCE:** + +.. code-block:: c + + #include + int nanosleep( + const struct timespec *rqtp, + struct timespec *rmtp + ); + +**STATUS CODES:** + +On error, this routine returns -1 and sets ``errno`` to one of the following: + +.. list-table:: + :class: rtems-table + + * - ``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:** + +**NOTES:** + +This call is interruptible by a signal. + +.. _gettimeofday: + +gettimeofday - Get the Time of Day +---------------------------------- +.. index:: gettimeofday +.. index:: get the time of day + +**CALLING SEQUENCE:** + +.. code-block:: c + + #include + #include + int gettimeofday( + struct timeval *tp, + struct timezone *tzp + ); + +**STATUS CODES:** + +On error, this routine returns -1 and sets ``errno`` as appropriate. + +.. list-table:: + :class: rtems-table + + * - ``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:** + +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. + +.. _time: + +time - Get time in seconds +-------------------------- +.. index:: time +.. index:: get time in seconds + +**CALLING SEQUENCE:** + +.. code-block:: c + + #include + int time( + time_t *tloc + ); + +**STATUS CODES:** + +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 + +If ``tloc`` in non null, the return value is also stored in the memory pointed +to by ``t``. + +**NOTES:** + +NONE diff --git a/posix-users/command.rst b/posix-users/command.rst new file mode 100644 index 0000000..5994765 --- /dev/null +++ b/posix-users/command.rst @@ -0,0 +1,7 @@ +.. comment SPDX-License-Identifier: CC-BY-SA-4.0 + +Command and Variable Index +########################## + +.. COMMENT: There are currently no Command and Variable Index entries. + diff --git a/posix-users/condition_variable.rst b/posix-users/condition_variable.rst new file mode 100644 index 0000000..ced9a8a --- /dev/null +++ b/posix-users/condition_variable.rst @@ -0,0 +1,361 @@ +.. comment SPDX-License-Identifier: CC-BY-SA-4.0 + +.. COMMENT: COPYRIGHT (c) 1988-2002. +.. COMMENT: On-Line Applications Research Corporation (OAR). +.. COMMENT: All rights reserved. + +Condition Variable Manager +########################## + +Introduction +============ + +The condition variable manager ... + +The directives provided by the condition variable manager are: + +- pthread_condattr_init_ - Initialize a Condition Variable Attribute Set + +- pthread_condattr_destroy_ - Destroy a Condition Variable Attribute Set + +- pthread_condattr_setpshared_ - Set Process Shared Attribute + +- pthread_condattr_getpshared_ - Get Process Shared Attribute + +- pthread_cond_init_ - Initialize a Condition Variable + +- pthread_cond_destroy_ - Destroy a Condition Variable + +- pthread_cond_signal_ - Signal a Condition Variable + +- pthread_cond_broadcast_ - Broadcast a Condition Variable + +- pthread_cond_wait_ - Wait on a Condition Variable + +- pthread_cond_timedwait_ - With with Timeout a Condition Variable + +Background +========== + +There is currently no text in this section. + +Operations +========== + +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. + +.. _pthread_condattr_init: + +pthread_condattr_init - Initialize a Condition Variable Attribute Set +--------------------------------------------------------------------- +.. index:: pthread_condattr_init +.. index:: initialize a condition variable attribute set + +**CALLING SEQUENCE:** + +.. code-block:: c + + #include + int pthread_condattr_init( + pthread_condattr_t *attr + ); + +**STATUS CODES:** + + * - ``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 +.. index:: destroy a condition variable attribute set + +**CALLING SEQUENCE:** + +.. code-block:: c + + #include + int pthread_condattr_destroy( + pthread_condattr_t *attr + ); + +**STATUS CODES:** + +.. 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 +.. index:: set process shared attribute + +**CALLING SEQUENCE:** + +.. code-block:: c + + #include + int pthread_condattr_setpshared( + pthread_condattr_t *attr, + int pshared + ); + +**STATUS CODES:** + +.. 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 +.. index:: get process shared attribute + +**CALLING SEQUENCE:** + +.. code-block:: c + + #include + int pthread_condattr_getpshared( + const pthread_condattr_t *attr, + int *pshared + ); + +**STATUS CODES:** + +.. 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 +.. index:: initialize a condition variable + +**CALLING SEQUENCE:** + +.. code-block:: c + + #include + int pthread_cond_init( + pthread_cond_t *cond, + const pthread_condattr_t *attr + ); + +**STATUS CODES:** + +.. list-table:: + :class: rtems-table + + * - ``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 +.. index:: destroy a condition variable + +**CALLING SEQUENCE:** + +.. code-block:: c + + #include + int pthread_cond_destroy( + pthread_cond_t *cond + ); + +**STATUS CODES:** + +.. list-table:: + :class: rtems-table + + * - ``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 +.. index:: signal a condition variable + +**CALLING SEQUENCE:** + +.. code-block:: c + + #include + int pthread_cond_signal( + pthread_cond_t *cond + ); + +**STATUS CODES:** + +.. list-table:: + :class: rtems-table + + * - ``EINVAL`` + - The specified condition variable is not valid. + +**DESCRIPTION:** + +**NOTES:** + +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 +.. index:: broadcast a condition variable + +**CALLING SEQUENCE:** + +.. code-block:: c + + #include + int pthread_cond_broadcast( + pthread_cond_t *cond + ); + +**STATUS CODES:** + +.. list-table:: + :class: rtems-table + + * - ``EINVAL`` + - The specified condition variable is not valid. + +**DESCRIPTION:** + +**NOTES:** + +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 +.. index:: wait on a condition variable + +**CALLING SEQUENCE:** + +.. code-block:: c + + #include + int pthread_cond_wait( + pthread_cond_t *cond, + pthread_mutex_t *mutex + ); + +**STATUS CODES:** + +.. 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 +.. index:: wait with timeout a condition variable + +**CALLING SEQUENCE:** + +.. code-block:: c + + #include + int pthread_cond_timedwait( + pthread_cond_t *cond, + pthread_mutex_t *mutex, + const struct timespec *abstime + ); + +**STATUS CODES:** + +.. 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. + * - ``ETIMEDOUT`` + - The specified time has elapsed without the condition variable being + satisfied. + +**DESCRIPTION:** + +**NOTES:** diff --git a/posix-users/conf.py b/posix-users/conf.py new file mode 100644 index 0000000..81b6443 --- /dev/null +++ b/posix-users/conf.py @@ -0,0 +1,13 @@ +import sys, os +sys.path.append(os.path.abspath('../common/')) + +from conf import * + +version = '4.11.0' +release = '4.11.0' + +project = "RTEMS POSIX User Manual" + +latex_documents = [ + ('index', 'posix-users.tex', u'RTEMS POSIX API User\'s Guide', u'RTEMS Documentation Project', 'manual'), +] diff --git a/posix-users/device_and_class_specific.rst b/posix-users/device_and_class_specific.rst new file mode 100644 index 0000000..24b2763 --- /dev/null +++ b/posix-users/device_and_class_specific.rst @@ -0,0 +1,460 @@ +.. comment SPDX-License-Identifier: CC-BY-SA-4.0 + +.. COMMENT: COPYRIGHT (c) 1988-2002. +.. COMMENT: On-Line Applications Research Corporation (OAR). +.. COMMENT: All rights reserved. + +Device- and Class- Specific Functions Manager +############################################# + +Introduction +============ + +The device- and class- specific functions manager is ... + +The directives provided by the device- and class- specific functions manager +are: + +- cfgetispeed_ - Reads terminal input baud rate + +- cfgetospeed_ - Reads terminal output baud rate + +- cfsetispeed_ - Sets terminal input baud rate + +- cfsetospeed_ - Set terminal output baud rate + +- tcgetattr_ - Gets terminal attributes + +- tcsetattr_ - Set terminal attributes + +- tcsendbreak_ - Sends a break to a terminal + +- tcdrain_ - Waits for all output to be transmitted to the terminal + +- tcflush_ - Discards terminal data + +- tcflow_ - Suspends/restarts terminal output + +- tcgetpgrp_ - Gets foreground process group ID + +- tcsetpgrp_ - Sets foreground process group ID + +Background +========== + +There is currently no text in this section. + +Operations +========== + +There is currently no text in this section. + +Directives +========== + +This section details the device- and class- specific functions 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. + +.. _cfgetispeed: + +cfgetispeed - Reads terminal input baud rate +-------------------------------------------- +.. index:: cfgetispeed +.. index:: reads terminal input baud rate + +**CALLING SEQUENCE:** + +.. code-block:: c + + #include + int cfgetispeed( + const struct termios *p + ); + +**STATUS CODES:** + +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 ```` 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()``. + +**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. + +.. _cfgetospeed: + +cfgetospeed - Reads terminal output baud rate +--------------------------------------------- +.. index:: cfgetospeed +.. index:: reads terminal output baud rate + +**CALLING SEQUENCE:** + +.. code-block:: c + + #include + int cfgetospeed( + const struct termios *p + ); + +**STATUS CODES:** + +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 ```` 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()``. + +**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. + +.. _cfsetispeed: + +cfsetispeed - Sets terminal input baud rate +------------------------------------------- +.. index:: cfsetispeed +.. index:: sets terminal input baud rate + +**CALLING SEQUENCE:** + +.. code-block:: c + + #include + int cfsetispeed( + struct termios *p, + speed_t speed + ); + +**STATUS CODES:** + +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 ```` 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. + +.. _cfsetospeed: + +cfsetospeed - Sets terminal output baud rate +-------------------------------------------- +.. index:: cfsetospeed +.. index:: sets terminal output baud rate + +**CALLING SEQUENCE:** + +.. code-block:: c + + #include + int cfsetospeed( + struct termios *p, + speed_t speed + ); + +**STATUS CODES:** + +The ``cfsetospeed()`` function returns a zero when successful and +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 ```` 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()``. + +**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. + +.. _tcgetattr: + +tcgetattr - Gets terminal attributes +------------------------------------ +.. index:: tcgetattr +.. index:: gets terminal attributes + +**CALLING SEQUENCE:** + +.. code-block:: c + + #include + #include + int tcgetattr( + int fildes, + struct termios *p + ); + +**STATUS CODES:** + +.. list-table:: + :class: rtems-table + + * - ``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``. + +**NOTES:** + +NONE + +.. _tcsetattr: + +tcsetattr - Set terminal attributes +----------------------------------- +.. index:: tcsetattr +.. index:: set terminal attributes + +**CALLING SEQUENCE:** + +.. code-block:: c + + #include + #include + int tcsetattr( + int fildes, + int options, + const struct termios *tp + ); + +**STATUS CODES:** + +.. list-table:: + :class: rtems-table + + * - ``E`` + - The + +**DESCRIPTION:** + +**NOTES:** + +.. _tcsendbreak: + +tcsendbreak - Sends a break to a terminal +----------------------------------------- +.. index:: tcsendbreak +.. index:: sends a break to a terminal + +**CALLING SEQUENCE:** + +.. code-block:: c + + int tcsendbreak( + int fd + ); + +**STATUS CODES:** + +.. list-table:: + :class: rtems-table + + * - ``E`` + - The + +**DESCRIPTION:** + +**NOTES:** + +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 +.. index:: waits for all output to be transmitted to the terminal. + +**CALLING SEQUENCE:** + +.. code-block:: c + + #include + #include + int tcdrain( + int fildes + ); + +**STATUS CODES:** + +.. list-table:: + :class: rtems-table + + * - ``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. + +**NOTES:** + +NONE + +.. _tcflush: + +tcflush - Discards terminal data +-------------------------------- +.. index:: tcflush +.. index:: discards terminal data + +**CALLING SEQUENCE:** + +.. code-block:: c + + int tcflush( + int fd + ); + +**STATUS CODES:** + +.. list-table:: + :class: rtems-table + + * - ``E`` + - The + +**DESCRIPTION:** + +**NOTES:** + +This routine is not currently supported by RTEMS but could be in a future +version. + +.. _tcflow: + +tcflow - Suspends/restarts terminal output. +------------------------------------------- +.. index:: tcflow +.. index:: suspends/restarts terminal output. + +**CALLING SEQUENCE:** + +.. code-block:: c + + int tcflow( + int fd + ); + +**STATUS CODES:** + +.. list-table:: + :class: rtems-table + + * - ``E`` + - The + +**DESCRIPTION:** + +**NOTES:** + +This routine is not currently supported by RTEMS but could be in a future +version. + +.. _tcgetpgrp: + +tcgetpgrp - Gets foreground process group ID +-------------------------------------------- +.. index:: tcgetpgrp +.. index:: gets foreground process group id + +**CALLING SEQUENCE:** + +.. code-block:: c + + int tcgetpgrp( + ); + +**STATUS CODES:** + +.. list-table:: + :class: rtems-table + + * - ``E`` + - The + +**DESCRIPTION:** + +**NOTES:** + +This routine is not currently supported by RTEMS but could be in a future +version. + +.. _tcsetpgrp: + +tcsetpgrp - Sets foreground process group ID +-------------------------------------------- +.. index:: tcsetpgrp +.. index:: sets foreground process group id + +**CALLING SEQUENCE:** + +.. code-block:: c + + int tcsetpgrp( + ); + +**STATUS CODES:** + +.. list-table:: + :class: rtems-table + + * - ``E`` + - The + +**DESCRIPTION:** + +**NOTES:** + +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 new file mode 100644 index 0000000..3a228b7 --- /dev/null +++ b/posix-users/files_and_directory.rst @@ -0,0 +1,1943 @@ +.. comment SPDX-License-Identifier: CC-BY-SA-4.0 + +.. COMMENT: COPYRIGHT (c) 1988-2002. +.. COMMENT: On-Line Applications Research Corporation (OAR). +.. COMMENT: All rights reserved. + +Files and Directories Manager +############################# + +Introduction +============ + +The files and directories manager is ... + +The directives provided by the files and directories manager are: + +- opendir_ - Open a Directory + +- readdir_ - Reads a directory + +- rewinddir_ - Resets the ``readdir()`` pointer + +- scandir_ - Scan a directory for matching entries + +- telldir_ - Return current location in directory stream + +- closedir_ - Ends directory read operation + +- getdents_ - Get directory entries + +- chdir_ - Changes the current working directory + +- fchdir_ - Changes the current working directory + +- getcwd_ - Gets current working directory + +- open_ - Opens a file + +- creat_ - Create a new file or rewrite an existing one + +- umask_ - Sets a file creation mask + +- link_ - Creates a link to a file + +- symlink_ - Creates a symbolic link to a file + +- readlink_ - Obtain the name of the link destination + +- mkdir_ - Makes a directory + +- mkfifo_ - Makes a FIFO special file + +- unlink_ - Removes a directory entry + +- rmdir_ - Delete a directory + +- rename_ - Renames a file + +- stat_ - Gets information about a file. + +- fstat_ - Gets file status + +- lstat_ - Gets file status + +- access_ - Check permissions for a file. + +- chmod_ - Changes file mode + +- fchmod_ - Changes permissions of a file + +- chown_ - Changes the owner and/ or group of a file + +- utime_ - Change access and/or modification times of an inode + +- ftruncate_ - Truncate a file to a specified length + +- truncate_ - Truncate a file to a specified length + +- pathconf_ - Gets configuration values for files + +- fpathconf_ - Get configuration values for files + +- mknod_ - Create a directory + +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. + +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. + +Operations +========== + +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. + +.. _opendir: + +opendir - Open a Directory +-------------------------- +.. index:: opendir +.. index:: open a directory + +**CALLING SEQUENCE:** + +.. code-block:: c + + #include + #include + int opendir( + const char *dirname + ); + +**STATUS CODES:** + +.. 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:** + +This routine opens a directory stream corresponding to the +directory specified by the ``dirname`` argument. The +directory stream is positioned at the first entry. + +**NOTES:** + +The routine is implemented in Cygnus newlib. + +.. _readdir: + +readdir - Reads a directory +--------------------------- +.. index:: readdir +.. index:: reads a directory + +**CALLING SEQUENCE:** + +.. code-block:: c + + #include + #include + int readdir( + DIR *dirp + ); + +**STATUS CODES:** + +.. 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. + +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. + +**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. + +The routine is implemented in Cygnus newlib. + +.. _rewinddir: + +rewinddir - Resets the readdir() pointer +---------------------------------------- +.. index:: rewinddir +.. index:: resets the readdir() pointer + +**CALLING SEQUENCE:** + +.. code-block:: c + + #include + #include + void rewinddir( + DIR *dirp + ); + +**STATUS CODES:** + +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. + +**NOTES:** + +NONE + +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 +.. index:: scan a directory for matching entries + +**CALLING SEQUENCE:** + +.. code-block:: c + + #include + int scandir( + const char *dir, + struct dirent ***namelist, + int (*select)(const struct dirent *), + int (*compar)(const struct dirent **, const struct dirent **) + ); + +**STATUS CODES:** + +.. 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. + +**NOTES:** + +The routine is implemented in Cygnus newlib. + +.. _telldir: + +telldir - Return current location in directory stream +----------------------------------------------------- +.. index:: telldir +.. index:: return current location in directory stream + +**CALLING SEQUENCE:** + +.. code-block:: c + + #include + off_t telldir( + DIR *dir + ); + +**STATUS CODES:** + +.. list-table:: + :class: rtems-table + + * - ``EBADF`` + - Invalid directory stream descriptor ``dir``. + +**DESCRIPTION:** + +The ``telldir()`` function returns the current location associated with the +directory stream ``dir``. + +**NOTES:** + +The routine is implemented in Cygnus newlib. + +.. _closedir: + +closedir - Ends directory read operation +---------------------------------------- +.. index:: closedir +.. index:: ends directory read operation + +**CALLING SEQUENCE:** + +.. code-block:: c + + #include + #include + int closedir( + DIR *dirp + ); + +**STATUS CODES:** + +.. 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()``. + +**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 routine is implemented in Cygnus newlib. + +.. _chdir: + +chdir - Changes the current working directory +--------------------------------------------- +.. index:: chdir +.. index:: changes the current working directory + +**CALLING SEQUENCE:** + +.. code-block:: c + + #include + int chdir( + const char *path + ); + +**STATUS CODES:** + +On error, this routine returns -1 and sets ``errno`` to one of the following: + +.. 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 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. + +If ``chdir()`` detects an error, the current working directory is not changed. + +**NOTES:** + +NONE + +.. _fchdir: + +fchdir - Changes the current working directory +---------------------------------------------- +.. index:: fchdir +.. index:: changes the current working directory + +**CALLING SEQUENCE:** + +.. code-block:: c + + #include + int fchdir( + int fd + ); + +**STATUS CODES:** + +On error, this routine returns -1 and sets ``errno`` to one of the following: + +.. 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 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. + +If ``fchdir()`` detects an error, the current working directory is not changed. + +**NOTES:** + +NONE + +.. _getcwd: + +getcwd - Gets current working directory +--------------------------------------- +.. index:: getcwd +.. index:: gets current working directory + +**CALLING SEQUENCE:** + +.. code-block:: c + + #include + int getcwd( void ); + +**STATUS CODES:** + +.. list-table:: + :class: rtems-table + + * - ``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`` + +**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. + +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. + +.. _open: + +open - Opens a file +------------------- +.. index:: open +.. index:: opens a file + +**CALLING SEQUENCE:** + +.. code-block:: c + + #include + #include + #include + int open( + const char *path, + int oflag, + mode_t mode + ); + +**STATUS CODES:** + +.. 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: + +.. list-table:: + :class: rtems-table + + * - ``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. + +.. 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 +.. index:: create a new file or rewrite an existing one + +**CALLING SEQUENCE:** + +.. code-block:: c + + #include + #include + #include + int creat( + const char *path, + mode_t mode + ); + +**STATUS CODES:** + +.. 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. + +**NOTES:** + +NONE + +The routine is implemented in Cygnus newlib. + +.. _umask: + +umask - Sets a file creation mask. +---------------------------------- +.. index:: umask +.. index:: sets a file creation mask. + +**CALLING SEQUENCE:** + +.. code-block:: c + + #include + #include + mode_t umask( + 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. + +**NOTES:** + +NONE + +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. + +.. _link: + +link - Creates a link to a file +------------------------------- +.. index:: link +.. index:: creates a link to a file + +**CALLING SEQUENCE:** + +.. code-block:: c + + #include + int link( + const char *existing, + const char *new + ); + +**STATUS CODES:** + +.. 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. + +If the ``link()`` function fails, no directories are modified. + +The ``existing`` argument should not be a directory. + +The caller may (or may not) need permission to access the existing file. + +**NOTES:** + +NONE + +.. _symlink: + +symlink - Creates a symbolic link to a file +------------------------------------------- +.. index:: symlink +.. index:: creates a symbolic link to a file + +**CALLING SEQUENCE:** + +.. code-block:: c + + #include + int symlink( + const char *topath, + const char *frompath + ); + +**STATUS CODES:** + +.. 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:** + +The ``symlink()`` function creates a symbolic link from the frombath to the +topath. The symbolic link will be interpreted at run-time. + +If the ``symlink()`` function fails, no directories are modified. + +The caller may (or may not) need permission to access the existing file. + +**NOTES:** + +NONE + +.. _readlink: + +readlink - Obtain the name of a symbolic link destination +--------------------------------------------------------- +.. index:: readlink +.. index:: obtain the name of a symbolic link destination + +**CALLING SEQUENCE:** + +.. code-block:: c + + #include + int readlink( + const char *path, + char *buf, + size_t bufsize + ); + +**STATUS CODES:** + +.. 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. + +If the symbolic link destination is longer than bufsize characters the name +will be truncated. + +**NOTES:** + +NONE + +.. _mkdir: + +mkdir - Makes a directory +------------------------- +.. index:: mkdir +.. index:: makes a directory + +**CALLING SEQUENCE:** + +.. code-block:: c + + #include + #include + int mkdir( + const char *path, + mode_t mode + ); + +**STATUS CODES:** + +.. 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 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 +.. index:: makes a fifo special file + +**CALLING SEQUENCE:** + +.. code-block:: c + + #include + #include + int mkfifo( + const char *path, + mode_t mode + ); + +**STATUS CODES:** + +.. 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. + +**NOTES:** + +NONE + +.. _unlink: + +unlink - Removes a directory entry +---------------------------------- +.. index:: unlink +.. index:: removes a directory entry + +**CALLING SEQUENCE:** + +.. code-block:: c + + #include + int unlink( + const char path + ); + +**STATUS CODES:** + +.. 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. + +**NOTES:** + +NONE + +.. _rmdir: + +rmdir - Delete a directory +-------------------------- +.. index:: rmdir +.. index:: delete a directory + +**CALLING SEQUENCE:** + +.. code-block:: c + + #include + int rmdir( + const char *pathname + ); + +**STATUS CODES:** + +.. 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:** + +``rmdir`` deletes a directory, which must be empty + +**NOTES:** + +NONE + +.. _rename: + +rename - Renames a file +----------------------- +.. index:: rename +.. index:: renames a file + +**CALLING SEQUENCE:** + +.. code-block:: c + + #include + int rename( + const char *old, + const char *new + ); + +**STATUS CODES:** + +.. 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``. + +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``. + +You may not rename dot or dot-dot. + +The routine is implemented in Cygnus newlib using ``link()`` and ``unlink()``. + +.. _stat: + +stat - Gets information about a file +------------------------------------ +.. index:: stat +.. index:: gets information about a file + +**CALLING SEQUENCE:** + +.. code-block:: c + + #include + #include + int stat( + const char *path, + struct stat *buf + ); + +**STATUS CODES:** + +.. 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``. + +**NOTES:** + +NONE + +.. _fstat: + +fstat - Gets file status +------------------------ +.. index:: fstat +.. index:: gets file status + +**CALLING SEQUENCE:** + +.. code-block:: c + + #include + #include + int fstat( + int fildes, + struct stat *buf + ); + +**STATUS CODES:** + +.. 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. + +**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. + +.. _lstat: + +lstat - Gets file status +------------------------ +.. index:: lstat +.. index:: gets file status + +**CALLING SEQUENCE:** + +.. code-block:: c + + #include + #include + int lstat( + int fildes, + struct stat *buf + ); + +**STATUS CODES:** + +.. 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. + +**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. + +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 +------------------------------------- +.. index:: access +.. index:: check permissions for a file + +**CALLING SEQUENCE:** + +.. code-block:: c + + #include + int access( + const char *pathname, + int mode + ); + +**STATUS CODES:** + +.. 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. + +``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 +.. index:: changes file mode. + +**CALLING SEQUENCE:** + +.. code-block:: c + + #include + #include + int chmod( + const char *path, + mode_t mode + ); + +**STATUS CODES:** + +.. 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``. + +**NOTES:** + +NONE + +.. _fchmod: + +fchmod - Changes permissions of a file +-------------------------------------- +.. index:: fchmod +.. index:: changes permissions of a file + +**CALLING SEQUENCE:** + +.. code-block:: c + + #include + #include + int fchmod( + int fildes, + mode_t mode + ); + +**STATUS CODES:** + +.. 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. + +**NOTES:** + +NONE + +.. _getdents: + +getdents - Get directory entries +-------------------------------- +.. index:: getdents +.. index:: get directory entries + +**CALLING SEQUENCE:** + +.. code-block:: c + + #include + #include + #include + long getdents( + 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. + +.. list-table:: + :class: rtems-table + + * - ``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. + +**NOTES:** + +NONE + +.. _chown: + +chown - Changes the owner and/or group of a file. +------------------------------------------------- +.. index:: chown +.. index:: changes the owner and/or group of a file. + +**CALLING SEQUENCE:** + +.. code-block:: c + + #include + #include + int chown( + const char *path, + uid_t owner, + gid_t group + ); + +**STATUS CODES:** + +.. 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. + +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. + +**NOTES:** + +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 +----------------------------------------------------------- +.. index:: utime +.. index:: change access and/or modification times of an inode + +**CALLING SEQUENCE:** + +.. code-block:: c + + #include + int utime( + const char *filename, + struct utimbuf *buf + ); + +**STATUS CODES:** + +.. list-table:: + :class: rtems-table + + * - ``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. + +**NOTES:** + +NONE + +.. _ftruncate: + +ftruncate - truncate a file to a specified length +------------------------------------------------- +.. index:: ftruncate +.. index:: truncate a file to a specified length + +**CALLING SEQUENCE:** + +.. code-block:: c + + #include + int ftrunctate( + int fd, + size_t length + ); + +**STATUS CODES:** + +.. 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. + +**NOTES:** + +NONE + +.. _truncate: + +truncate - truncate a file to a specified length +------------------------------------------------ +.. index:: truncate +.. index:: truncate a file to a specified length + +**CALLING SEQUENCE:** + +.. code-block:: c + + #include + int trunctate( + const char *path, + size_t length + ); + +**STATUS CODES:** + +.. 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. + +**NOTES:** + +NONE + +.. _pathconf: + +pathconf - Gets configuration values for files +---------------------------------------------- +.. index:: pathconf +.. index:: gets configuration values for files + +**CALLING SEQUENCE:** + +.. code-block:: c + + #include + int pathconf( + const char *path, + int name + ); + +**STATUS CODES:** + +.. 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``. + +The possible values for ``name`` are: + +.. 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. + +.. _fpathconf: + +fpathconf - Gets configuration values for files +----------------------------------------------- +.. index:: fpathconf +.. index:: gets configuration values for files + +**CALLING SEQUENCE:** + +.. code-block:: c + + #include + int fpathconf( + int filedes, + int name + ); + +**STATUS CODES:** + +.. 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``. + +The possible values for name are: + +.. 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 +.. index:: create a directory + +**CALLING SEQUENCE:** + +.. code-block:: c + + #include + #include + #include + #include + long mknod( + const char *pathname, + mode_t mode, + dev_t dev + ); + +**STATUS CODES:** + +``mknod`` returns zero on success, or -1 if an error occurred (in which case, +errno is set appropriately). + +.. 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:** + +``mknod`` attempts to create a filesystem node (file, device special file or +named pipe) named ``pathname``, specified by ``mode`` and ``dev``. + +``mode`` specifies both the permissions to use and the type of node to be created. + +It should be a combination (using bitwise OR) of one of the file types listed +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. + +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. + +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 diff --git a/posix-users/index.rst b/posix-users/index.rst new file mode 100644 index 0000000..072579c --- /dev/null +++ b/posix-users/index.rst @@ -0,0 +1,67 @@ +.. comment SPDX-License-Identifier: CC-BY-SA-4.0 + +============================ +RTEMS POSIX API User's Guide +============================ + +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 + files_and_directory + input_and_output + device_and_class_specific + language_specific_services + system_database + semaphore + mutex + condition_variable + memory_managment + scheduler + clock + timer + message_passing + thread + key + thread_cancellation + services_provided_by_c + services_provided_by_math + status_of_implementation + command + +* :ref:`genindex` +* :ref:`search` diff --git a/posix-users/input_and_output.rst b/posix-users/input_and_output.rst new file mode 100644 index 0000000..5a3b9d8 --- /dev/null +++ b/posix-users/input_and_output.rst @@ -0,0 +1,1040 @@ +.. comment SPDX-License-Identifier: CC-BY-SA-4.0 + +.. COMMENT: COPYRIGHT (c) 1988-2002. +.. COMMENT: On-Line Applications Research Corporation (OAR). +.. COMMENT: All rights reserved. + +Input and Output Primitives Manager +################################### + +Introduction +============ + +The input and output primitives manager is ... + +The directives provided by the input and output primitives manager are: + +- pipe_ - Create an Inter-Process Channel + +- dup_ - Duplicates an open file descriptor + +- dup2_ - Duplicates an open file descriptor + +- close_ - Closes a file + +- read_ - Reads from a file + +- write_ - Writes to a file + +- fcntl_ - Manipulates an open file descriptor + +- lseek_ - Reposition read/write file offset + +- fsync_ - Synchronize file complete in-core state with that on disk + +- fdatasync_ - Synchronize file in-core data with that on disk + +- sync_ - Schedule file system updates + +- mount_ - Mount a file system + +- unmount_ - Unmount file systems + +- readv_ - Vectored read from a file + +- writev_ - Vectored write to a file + +- aio_read_ - Asynchronous Read + +- aio_write_ - Asynchronous Write + +- lio_listio_ - List Directed I/O + +- aio_error_ - Retrieve Error Status of Asynchronous I/O Operation + +- aio_return_ - Retrieve Return Status Asynchronous I/O Operation + +- aio_cancel_ - Cancel Asynchronous I/O Request + +- aio_suspend_ - Wait for Asynchronous I/O Request + +- aio_fsync_ - Asynchronous File Synchronization + +Background +========== + +There is currently no text in this section. + +Operations +========== + +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. + +.. _pipe: + +pipe - Create an Inter-Process Channel +-------------------------------------- +.. index:: pipe +.. index:: create an inter + +**CALLING SEQUENCE:** + +.. code-block:: c + + int pipe( + ); + +**STATUS CODES:** + +.. list-table:: + :class: rtems-table + + * - ``E`` + - The + +**DESCRIPTION:** + +**NOTES:** + +This routine is not currently supported by RTEMS but could be +in a future version. + +.. _dup: + +dup - Duplicates an open file descriptor +---------------------------------------- +.. index:: dup +.. index:: duplicates an open file descriptor + +**CALLING SEQUENCE:** + +.. code-block:: c + + #include + int dup( + int fildes + ); + +**STATUS CODES:** + +.. list-table:: + :class: rtems-table + + * - ``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. + +**NOTES:** + +NONE + +.. _dup2: + +dup2 - Duplicates an open file descriptor +----------------------------------------- +.. index:: dup2 +.. index:: duplicates an open file descriptor + +**CALLING SEQUENCE:** + +.. code-block:: c + + #include + int dup2( + int fildes, + int fildes2 + ); + +**STATUS CODES:** + +.. list-table:: + :class: rtems-table + + * - ``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. + +**NOTES:** + +NONE + +.. _close: + +close - Closes a file +--------------------- +.. index:: close +.. index:: closes a file. + +**CALLING SEQUENCE:** + +.. code-block:: c + + #include + int close( + int fildes + ); + +**STATUS CODES:** + +.. list-table:: + :class: rtems-table + + * - ``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. + +**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. + +.. _read: + +read - Reads from a file +------------------------ +.. index:: read +.. index:: reads from a file + +**CALLING SEQUENCE:** + +.. code-block:: c + + #include + int read( + int fildes, + void *buf, + unsigned int nbyte + ); + +**STATUS CODES:** + +On error, this routine returns -1 and sets ``errno`` to one of the following: + +.. 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 + * - ``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 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``. + +- The ``read()`` request was interrupted by a signal. + +- The file is a pipe or FIFO or special file with less than ``nbytes`` + immediately available for reading. + +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 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. + +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. + +- The O_NONBLOCK flag is ignored if data is available. + +**NOTES:** + +NONE + +.. _write: + +write - Writes to a file +------------------------ +.. index:: write +.. index:: writes to a file + +**CALLING SEQUENCE:** + +.. code-block:: c + + #include + int write( + int fildes, + const void *buf, + unsigned int nbytes + ); + +**STATUS CODES:** + +.. 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``. + +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``. + +**NOTES:** + +NONE + +.. _fcntl: + +fcntl - Manipulates an open file descriptor +------------------------------------------- +.. index:: fcntl +.. index:: manipulates an open file descriptor + +**CALLING SEQUENCE:** + +.. code-block:: c + + #include + #include + #include + int fcntl( + int fildes, + int cmd + ); + +**STATUS CODES:** + +.. 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``: + +.. 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``. + +.. _lseek: + +lseek - Reposition read/write file offset +----------------------------------------- +.. index:: lseek +.. index:: reposition read/write file offset + +**CALLING SEQUENCE:** + +.. code-block:: c + + #include + #include + int lseek( + int fildes, + off_t offset, + int whence + ); + +**STATUS CODES:** + +.. list-table:: + :class: rtems-table + + * - ``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: + +- If ``whence`` is SEEK_SET, the offset is set to ``offset`` bytes. + +- If ``whence`` is SEEK_CUR, the offset is set to its current location + plus offset bytes. + +- 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). + +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 +.. index:: synchronize file complete in + +**CALLING SEQUENCE:** + +.. code-block:: c + + int fsync( + int fd + ); + +**STATUS CODES:** + +On success, zero is returned. On error, -1 is returned, and ``errno`` is set +appropriately. + +.. list-table:: + :class: rtems-table + + * - ``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:** + +``fsync`` copies all in-core parts of a file to disk. + +**NOTES:** + +NONE + +.. _fdatasync: + +fdatasync - Synchronize file in-core data with that on disk +----------------------------------------------------------- +.. index:: fdatasync +.. index:: synchronize file in + +**CALLING SEQUENCE:** + +.. code-block:: c + + int fdatasync( + int fd + ); + +**STATUS CODES:** + +On success, zero is returned. On error, -1 is returned, and ``errno`` is set +appropriately. + +.. list-table:: + :class: rtems-table + + * - ``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. + +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 +.. index:: synchronize file systems + +**CALLING SEQUENCE:** + +.. code-block:: c + + void sync(void); + +**STATUS CODES:** + +NONE + +**DESCRIPTION:** + +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``. + +.. _mount: + +mount - Mount a file system +--------------------------- +.. index:: mount +.. index:: mount a file system + +**CALLING SEQUENCE:** + +.. code-block:: c + + #include + 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 + ); + +**STATUS CODES:** + +*EXXX* + +**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``. + +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 +.. index:: unmount file systems + +**CALLING SEQUENCE:** + +.. code-block:: c + + #include + int unmount( + const char *mount_path + ); + +**STATUS CODES:** + +*EXXX* + +**DESCRIPTION:** + +The ``unmount`` routine removes the attachment of the filesystem specified by +``mount_path``. + +**NOTES:** + +NONE + +.. _readv: + +readv - Vectored read from a file +--------------------------------- +.. index:: readv +.. index:: vectored read from a file + +**CALLING SEQUENCE:** + +.. code-block:: c + + #include + ssize_t readv( + 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: + +.. list-table:: + :class: rtems-table + + * - ``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]``. + +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 +.. index:: vectored write to a file + +**CALLING SEQUENCE:** + +.. code-block:: c + + #include + ssize_t writev( + 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: + +.. list-table:: + :class: rtems-table + + * - ``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 +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. + +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 +.. index:: asynchronous read + +**CALLING SEQUENCE:** + +.. code-block:: c + + int aio_read( + ); + +**STATUS CODES:** + +.. list-table:: + :class: rtems-table + + * - ``E`` + - The + +**DESCRIPTION:** + +**NOTES:** + +This routine is not currently supported by RTEMS but could be in a future +version. + +.. _aio_write: + +aio_write - Asynchronous Write +------------------------------ +.. index:: aio_write +.. index:: asynchronous write + +**CALLING SEQUENCE:** + +.. code-block:: c + + int aio_write( + ); + +**STATUS CODES:** + +.. list-table:: + :class: rtems-table + + * - ``E`` + - The + +**DESCRIPTION:** + +**NOTES:** + +This routine is not currently supported by RTEMS but could be in a future +version. + +.. _lio_listio: + +lio_listio - List Directed I/O +------------------------------ +.. index:: lio_listio +.. index:: list directed i/o + +**CALLING SEQUENCE:** + +.. code-block:: c + + int lio_listio( + ); + +**STATUS CODES:** + +.. list-table:: + :class: rtems-table + + * - ``E`` + - The + +**DESCRIPTION:** + +**NOTES:** + +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 +--------------------------------------------------------------- +.. index:: aio_error +.. index:: retrieve error status of asynchronous i/o operation + +**CALLING SEQUENCE:** + +.. code-block:: c + + int aio_error( + ); + +**STATUS CODES:** + +.. list-table:: + :class: rtems-table + + * - ``E`` + - The + +**DESCRIPTION:** + +**NOTES:** + +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 +-------------------------------------------------------------- +.. index:: aio_return +.. index:: retrieve return status asynchronous i/o operation + +**CALLING SEQUENCE:** + +.. code-block:: c + + int aio_return( + ); + +**STATUS CODES:** + +.. list-table:: + :class: rtems-table + + * - ``E`` + - The + +**DESCRIPTION:** + +**NOTES:** + +This routine is not currently supported by RTEMS but could be in a future +version. + +.. _aio_cancel: + +aio_cancel - Cancel Asynchronous I/O Request +-------------------------------------------- +.. index:: aio_cancel +.. index:: cancel asynchronous i/o request + +**CALLING SEQUENCE:** + +.. code-block:: c + + int aio_cancel( + ); + +**STATUS CODES:** + +.. list-table:: + :class: rtems-table + + * - ``E`` + - The + +**DESCRIPTION:** + +**NOTES:** + +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 +----------------------------------------------- +.. index:: aio_suspend +.. index:: wait for asynchronous i/o request + +**CALLING SEQUENCE:** + +.. code-block:: c + + int aio_suspend( + ); + +**STATUS CODES:** + +.. list-table:: + :class: rtems-table + + * - ``E`` + - The + +**DESCRIPTION:** + +**NOTES:** + +This routine is not currently supported by RTEMS but could be in a future +version. + +.. _aio_fsync: + +aio_fsync - Asynchronous File Synchronization +--------------------------------------------- +.. index:: aio_fsync +.. index:: asynchronous file synchronization + +**CALLING SEQUENCE:** + +.. code-block:: c + + int aio_fsync( + ); + +**STATUS CODES:** + +.. list-table:: + :class: rtems-table + + * - ``E`` + - The + +**DESCRIPTION:** + +**NOTES:** + +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 new file mode 100644 index 0000000..5b16ddb --- /dev/null +++ b/posix-users/key.rst @@ -0,0 +1,212 @@ +.. comment SPDX-License-Identifier: CC-BY-SA-4.0 + +.. COMMENT: COPYRIGHT (c) 1988-2002. +.. COMMENT: On-Line Applications Research Corporation (OAR). +.. COMMENT: All rights reserved. + +Key Manager +########### + +Introduction +============ + +The key manager allows for the creation and deletion of Data keys +specific to threads. + +The directives provided by the key manager are: + +- pthread_key_create_ - Create Thread Specific Data Key + +- pthread_key_delete_ - Delete Thread Specific Data Key + +- pthread_setspecific_ - Set Thread Specific Key Value + +- pthread_getspecific_ - Get Thread Specific Key Value + +Background +========== + +There is currently no text in this section. + +Operations +========== + +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. + +.. _pthread_key_create: + +pthread_key_create - Create Thread Specific Data Key +---------------------------------------------------- + +**CALLING SEQUENCE:** + +.. code-block:: c + + #include + int pthread_key_create( + pthread_key_t *key, + void (*destructor)( void ) + ); + +**STATUS CODES:** + +.. list-table:: + :class: rtems-table + + * - ``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. + +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. + +.. _pthread_key_delete: + +pthread_key_delete - Delete Thread Specific Data Key +---------------------------------------------------- + +**CALLING SEQUENCE:** + +.. code-block:: c + + #include + int pthread_key_delete( + pthread_key_t key + ); + +**STATUS CODES:** + +.. 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 +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. + +**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. + +.. _pthread_setspecific: + +pthread_setspecific - Set Thread Specific Key Value +--------------------------------------------------- + +**CALLING SEQUENCE:** + +.. code-block:: c + + #include + int pthread_setspecific( + pthread_key_t key, + const void *value + ); + +**STATUS CODES:** + +.. 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. + +**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. + +``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-block:: c + + #include + void *pthread_getspecific( + pthread_key_t key + ); + +**STATUS CODES:** + +.. list-table:: + :class: rtems-table + + * - ``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. + +**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()``. diff --git a/posix-users/language_specific_services.rst b/posix-users/language_specific_services.rst new file mode 100644 index 0000000..d871e8a --- /dev/null +++ b/posix-users/language_specific_services.rst @@ -0,0 +1,621 @@ +.. comment SPDX-License-Identifier: CC-BY-SA-4.0 + +.. COMMENT: COPYRIGHT (c) 1988-2002. +.. COMMENT: On-Line Applications Research Corporation (OAR). +.. COMMENT: All rights reserved. + +Language-Specific Services for the C Programming Language Manager +################################################################# + +Introduction +============ + +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 + +- fileno_ - Obtain File Descriptor Number for this File + +- fdopen_ - Associate Stream with File Descriptor + +- flockfile_ - Acquire Ownership of File Stream + +- ftrylockfile_ - Poll to Acquire Ownership of File Stream + +- funlockfile_ - Release Ownership of File Stream + +- getc_unlocked_ - Get Character without Locking + +- getchar_unlocked_ - Get Character from stdin without Locking + +- putc_unlocked_ - Put Character without Locking + +- putchar_unlocked_ - Put Character to stdin without Locking + +- setjmp_ - Save Context for Non-Local Goto + +- longjmp_ - Non-Local Jump to a Saved Context + +- sigsetjmp_ - Save Context with Signal Status for Non-Local Goto + +- siglongjmp_ - Non-Local Jump with Signal Status to a Saved Context + +- tzset_ - Initialize Time Conversion Information + +- strtok_r_ - Reentrant Extract Token from String + +- asctime_r_ - Reentrant struct tm to ASCII Time Conversion + +- ctime_r_ - Reentrant time_t to ASCII Time Conversion + +- gmtime_r_ - Reentrant UTC Time Conversion + +- localtime_r_ - Reentrant Local Time Conversion + +- rand_r_ - Reentrant Random Number Generation + +Background +========== + +There is currently no text in this section. + +Operations +========== + +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. + +.. _setlocale: + +setlocale - Set the Current Locale +---------------------------------- +.. index:: setlocale +.. index:: set the current locale + +**CALLING SEQUENCE:** + +.. code-block:: c + + int setlocale( + ); + +**STATUS CODES:** + +.. list-table:: + :class: rtems-table + + * - ``E`` + - The + +**DESCRIPTION:** + +**NOTES:** + +.. _fileno: + +fileno - Obtain File Descriptor Number for this File +---------------------------------------------------- +.. index:: fileno +.. index:: obtain file descriptor number for this file + +**CALLING SEQUENCE:** + +.. code-block:: c + + int fileno( + ); + +**STATUS CODES:** + +.. list-table:: + :class: rtems-table + + * - ``E`` + - The + +**DESCRIPTION:** + +**NOTES:** + +.. _fdopen: + +fdopen - Associate Stream with File Descriptor +---------------------------------------------- +.. index:: fdopen +.. index:: associate stream with file descriptor + +**CALLING SEQUENCE:** + +.. code-block:: c + + int fdopen( + ); + +**STATUS CODES:** + +.. list-table:: + :class: rtems-table + + * - ``E`` + - The + +**DESCRIPTION:** + +**NOTES:** + +.. _flockfile: + +flockfile - Acquire Ownership of File Stream +-------------------------------------------- +.. index:: flockfile +.. index:: acquire ownership of file stream + +**CALLING SEQUENCE:** + +.. code-block:: c + + int flockfile( + ); + +**STATUS CODES:** + +.. list-table:: + :class: rtems-table + + * - ``E`` + - The + +**DESCRIPTION:** + +**NOTES:** + +.. _ftrylockfile: + +ftrylockfile - Poll to Acquire Ownership of File Stream +------------------------------------------------------- +.. index:: ftrylockfile +.. index:: poll to acquire ownership of file stream + +**CALLING SEQUENCE:** + +.. code-block:: c + + int ftrylockfile( + ); + +**STATUS CODES:** + +.. list-table:: + :class: rtems-table + + * - ``E`` + - The + +**DESCRIPTION:** + +**NOTES:** + +.. _funlockfile: + +funlockfile - Release Ownership of File Stream +---------------------------------------------- +.. index:: funlockfile +.. index:: release ownership of file stream + +**CALLING SEQUENCE:** + +.. code-block:: c + + int funlockfile( + ); + +**STATUS CODES:** + +.. list-table:: + :class: rtems-table + + * - ``E`` + - The + +**DESCRIPTION:** + +**NOTES:** + +.. _getc_unlocked: + +getc_unlocked - Get Character without Locking +--------------------------------------------- +.. index:: getc_unlocked +.. index:: get character without locking + +**CALLING SEQUENCE:** + +.. code-block:: c + + int getc_unlocked( + ); + +**STATUS CODES:** + +.. list-table:: + :class: rtems-table + + * - ``E`` + - The + +**DESCRIPTION:** + +**NOTES:** + +.. _getchar_unlocked: + +getchar_unlocked - Get Character from stdin without Locking +----------------------------------------------------------- +.. index:: getchar_unlocked +.. index:: get character from stdin without locking + +**CALLING SEQUENCE:** + +.. code-block:: c + + int getchar_unlocked( + ); + +**STATUS CODES:** + +.. list-table:: + :class: rtems-table + + * - ``E`` + - The + +**DESCRIPTION:** + +**NOTES:** + +.. _putc_unlocked: + +putc_unlocked - Put Character without Locking +--------------------------------------------- +.. index:: putc_unlocked +.. index:: put character without locking + +**CALLING SEQUENCE:** + +.. code-block:: c + + int putc_unlocked( + ); + +**STATUS CODES:** + +.. list-table:: + :class: rtems-table + + * - ``E`` + - The + +**DESCRIPTION:** + +**NOTES:** + +.. _putchar_unlocked: + +putchar_unlocked - Put Character to stdin without Locking +--------------------------------------------------------- +.. index:: putchar_unlocked +.. index:: put character to stdin without locking + +**CALLING SEQUENCE:** + +.. code-block:: c + + int putchar_unlocked( + ); + +**STATUS CODES:** + +.. list-table:: + :class: rtems-table + + * - ``E`` + - The + +**DESCRIPTION:** + +**NOTES:** + +.. _setjmp: + +setjmp - Save Context for Non-Local Goto +---------------------------------------- +.. index:: setjmp +.. index:: save context for non + +**CALLING SEQUENCE:** + +.. code-block:: c + + int setjmp( + ); + +**STATUS CODES:** + +.. list-table:: + :class: rtems-table + + * - ``E`` + - The + +**DESCRIPTION:** + +**NOTES:** + +.. _longjmp: + +longjmp - Non-Local Jump to a Saved Context +------------------------------------------- +.. index:: longjmp +.. index:: non + +**CALLING SEQUENCE:** + +.. code-block:: c + + int longjmp( + ); + +**STATUS CODES:** + +.. list-table:: + :class: rtems-table + + * - ``E`` + - The + +**DESCRIPTION:** + +**NOTES:** + +.. _sigsetjmp: + +sigsetjmp - Save Context with Signal Status for Non-Local Goto +-------------------------------------------------------------- +.. index:: sigsetjmp +.. index:: save context with signal status for non + +**CALLING SEQUENCE:** + +.. code-block:: c + + int sigsetjmp( + ); + +**STATUS CODES:** + +.. list-table:: + :class: rtems-table + + * - ``E`` + - The + +**DESCRIPTION:** + +**NOTES:** + +.. _siglongjmp: + +siglongjmp - Non-Local Jump with Signal Status to a Saved Context +----------------------------------------------------------------- +.. index:: siglongjmp +.. index:: non + +**CALLING SEQUENCE:** + +.. code-block:: c + + int siglongjmp( + ); + +**STATUS CODES:** + +.. list-table:: + :class: rtems-table + + * - ``E`` + - The + +**DESCRIPTION:** + +**NOTES:** + +.. _tzset: + +tzset - Initialize Time Conversion Information +---------------------------------------------- +.. index:: tzset +.. index:: initialize time conversion information + +**CALLING SEQUENCE:** + +.. code-block:: c + + int tzset( + ); + +**STATUS CODES:** + +.. list-table:: + :class: rtems-table + + * - ``E`` + - The + +**DESCRIPTION:** + +**NOTES:** + +.. _strtok_r: + +strtok_r - Reentrant Extract Token from String +---------------------------------------------- +.. index:: strtok_r +.. index:: reentrant extract token from string + +**CALLING SEQUENCE:** + +.. code-block:: c + + int strtok_r( + ); + +**STATUS CODES:** + +.. list-table:: + :class: rtems-table + + * - ``E`` + - The + +**DESCRIPTION:** + +**NOTES:** + +.. _asctime_r: + +asctime_r - Reentrant struct tm to ASCII Time Conversion +-------------------------------------------------------- +.. index:: asctime_r +.. index:: reentrant struct tm to ascii time conversion + +**CALLING SEQUENCE:** + +.. code-block:: c + + int asctime_r( + ); + +**STATUS CODES:** + +.. list-table:: + :class: rtems-table + + * - ``E`` + - The + +**DESCRIPTION:** + +**NOTES:** + +.. _ctime_r: + +ctime_r - Reentrant time_t to ASCII Time Conversion +--------------------------------------------------- +.. index:: ctime_r +.. index:: reentrant time_t to ascii time conversion + +**CALLING SEQUENCE:** + +.. code-block:: c + + int ctime_r( + ); + +**STATUS CODES:** + +.. list-table:: + :class: rtems-table + + * - ``E`` + - The + +**DESCRIPTION:** + +**NOTES:** + +.. _gmtime_r: + +gmtime_r - Reentrant UTC Time Conversion +---------------------------------------- +.. index:: gmtime_r +.. index:: reentrant utc time conversion + +**CALLING SEQUENCE:** + +.. code-block:: c + + int gmtime_r( + ); + +**STATUS CODES:** + +.. list-table:: + :class: rtems-table + + * - ``E`` + - The + +**DESCRIPTION:** + +**NOTES:** + +.. _localtime_r: + +localtime_r - Reentrant Local Time Conversion +--------------------------------------------- +.. index:: localtime_r +.. index:: reentrant local time conversion + +**CALLING SEQUENCE:** + +.. code-block:: c + + int localtime_r( + ); + +**STATUS CODES:** + +.. list-table:: + :class: rtems-table + + * - ``E`` + - The + +**DESCRIPTION:** + +**NOTES:** + +.. _rand_r: + +rand_r - Reentrant Random Number Generation +------------------------------------------- +.. index:: rand_r +.. index:: reentrant random number generation + +**CALLING SEQUENCE:** + +.. code-block:: c + + int rand_r( + ); + +**STATUS CODES:** + +.. list-table:: + :class: rtems-table + + * - ``E`` + - The + +**DESCRIPTION:** + +**NOTES:** diff --git a/posix-users/memory_managment.rst b/posix-users/memory_managment.rst new file mode 100644 index 0000000..631ba45 --- /dev/null +++ b/posix-users/memory_managment.rst @@ -0,0 +1,313 @@ +.. comment SPDX-License-Identifier: CC-BY-SA-4.0 + +.. COMMENT: COPYRIGHT (c) 1988-2002. +.. COMMENT: On-Line Applications Research Corporation (OAR). +.. COMMENT: All rights reserved. + +Memory Management Manager +######################### + +Introduction +============ + +The +memory management manager is ... + +The directives provided by the memory management manager are: + +- mlockall_ - Lock the Address Space of a Process + +- munlockall_ - Unlock the Address Space of a Process + +- mlock_ - Lock a Range of the Process Address Space + +- munlock_ - Unlock a Range of the Process Address Space + +- mmap_ - Map Process Addresses to a Memory Object + +- munmap_ - Unmap Previously Mapped Addresses + +- mprotect_ - Change Memory Protection + +- msync_ - Memory Object Synchronization + +- shm_open_ - Open a Shared Memory Object + +- shm_unlink_ - Remove a Shared Memory Object + +Background +========== + +There is currently no text in this section. + +Operations +========== + +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. + +.. _mlockall: + +mlockall - Lock the Address Space of a Process +---------------------------------------------- +.. index:: mlockall +.. index:: lock the address space of a process + +**CALLING SEQUENCE:** + +.. code-block:: c + + int mlockall( + ); + +**STATUS CODES:** + +.. list-table:: + :class: rtems-table + + * - ``E`` + - The + +**DESCRIPTION:** + +**NOTES:** + +.. _munlockall: + +munlockall - Unlock the Address Space of a Process +-------------------------------------------------- +.. index:: munlockall +.. index:: unlock the address space of a process + +**CALLING SEQUENCE:** + +.. code-block:: c + + int munlockall( + ); + +**STATUS CODES:** + +.. list-table:: + :class: rtems-table + + * - ``E`` + - The + +**DESCRIPTION:** + +**NOTES:** + +.. _mlock: + +mlock - Lock a Range of the Process Address Space +------------------------------------------------- +.. index:: mlock +.. index:: lock a range of the process address space + +**CALLING SEQUENCE:** + +.. code-block:: c + + int mlock( + ); + +**STATUS CODES:** + +.. list-table:: + :class: rtems-table + + * - ``E`` + - The + +**DESCRIPTION:** + +**NOTES:** + +.. _munlock: + +munlock - Unlock a Range of the Process Address Space +----------------------------------------------------- +.. index:: munlock +.. index:: unlock a range of the process address space + +**CALLING SEQUENCE:** + +.. code-block:: c + + int munlock( + ); + +**STATUS CODES:** + +.. list-table:: + :class: rtems-table + + * - ``E`` + - The + +**DESCRIPTION:** + +**NOTES:** + +.. _mmap: + +mmap - Map Process Addresses to a Memory Object +----------------------------------------------- +.. index:: mmap +.. index:: map process addresses to a memory object + +**CALLING SEQUENCE:** + +.. code-block:: c + + int mmap( + ); + +**STATUS CODES:** + +.. list-table:: + :class: rtems-table + + * - ``E`` + - The + +**DESCRIPTION:** + +**NOTES:** + +.. _munmap: + +munmap - Unmap Previously Mapped Addresses +------------------------------------------ +.. index:: munmap +.. index:: unmap previously mapped addresses + +**CALLING SEQUENCE:** + +.. code-block:: c + + int munmap( + ); + +**STATUS CODES:** + +.. list-table:: + :class: rtems-table + + * - ``E`` + - The + +**DESCRIPTION:** + +**NOTES:** + +.. _mprotect: + +mprotect - Change Memory Protection +----------------------------------- +.. index:: mprotect +.. index:: change memory protection + +**CALLING SEQUENCE:** + +.. code-block:: c + + int mprotect( + ); + +**STATUS CODES:** + +.. list-table:: + :class: rtems-table + + * - ``E`` + - The + +**DESCRIPTION:** + +**NOTES:** + +.. _msync: + +msync - Memory Object Synchronization +------------------------------------- +.. index:: msync +.. index:: memory object synchronization + +**CALLING SEQUENCE:** + +.. code-block:: c + + int msync( + ); + +**STATUS CODES:** + +.. list-table:: + :class: rtems-table + + * - ``E`` + - The + +**DESCRIPTION:** + +**NOTES:** + +.. _shm_open: + +shm_open - Open a Shared Memory Object +-------------------------------------- +.. index:: shm_open +.. index:: open a shared memory object + +**CALLING SEQUENCE:** + +.. code-block:: c + + int shm_open( + ); + +**STATUS CODES:** + +.. list-table:: + :class: rtems-table + + * - ``E`` + - The + +**DESCRIPTION:** + +**NOTES:** + +.. _shm_unlink: + +shm_unlink - Remove a Shared Memory Object +------------------------------------------ +.. index:: shm_unlink +.. index:: remove a shared memory object + +**CALLING SEQUENCE:** + +.. code-block:: c + + int shm_unlink( + ); + +**STATUS CODES:** + +.. list-table:: + :class: rtems-table + + * - ``E`` + - The + +**DESCRIPTION:** + +**NOTES:** diff --git a/posix-users/message_passing.rst b/posix-users/message_passing.rst new file mode 100644 index 0000000..64c64a3 --- /dev/null +++ b/posix-users/message_passing.rst @@ -0,0 +1,741 @@ +.. comment SPDX-License-Identifier: CC-BY-SA-4.0 + +.. COMMENT: COPYRIGHT (c) 1988-2014. +.. COMMENT: On-Line Applications Research Corporation (OAR). +.. COMMENT: All rights reserved. + +Message Passing Manager +####################### + +Introduction +============ + +The message passing manager is the means to provide communication and +synchronization capabilities using POSIX message queues. + +The directives provided by the message passing manager are: + +- mq_open_ - Open a Message Queue + +- mq_close_ - Close a Message Queue + +- mq_unlink_ - Remove a Message Queue + +- mq_send_ - Send a Message to a Message Queue + +- mq_receive_ - Receive a Message from a Message Queue + +- mq_notify_ - Notify Process that a Message is Available + +- mq_setattr_ - Set Message Queue Attributes + +- mq_getattr_ - Get Message Queue Attributes + +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. + +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. + +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 + +The message queue descriptor ``mqd_t`` represents the message queue. It is +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 + +.. code-block:: c + + typedef struct mq_attr{ + 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``. + +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 +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 +current state of the message queue. This specifies the number of messages +currently on the queue. + +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. + +POSIX Interpretation Issues +--------------------------- + +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? + +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 +========== + +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 +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. + +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. + +Removing a Message Queue +------------------------ + +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. + +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 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. + +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. + +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 +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. + +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. + +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. + +.. _mq_open: + +mq_open - Open a Message Queue +------------------------------ +.. index:: mq_open +.. index:: open a message queue + +**CALLING SEQUENCE:** + +.. code-block:: c + + #include + mqd_t mq_open( + const char *name, + int oflag, + mode_t mode, + struct mq_attr *attr + ); + +**STATUS CODES:** + +.. 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 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. + +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. + +.. 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 +attribute structure is not used. + +.. _mq_close: + +mq_close - Close a Message Queue +-------------------------------- +.. index:: mq_close +.. index:: close a message queue + +**CALLING SEQUENCE:** + +.. code-block:: c + + #include + int mq_close( + mqd_t mqdes + ); + +**STATUS CODES:** + +.. 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 +completed, the function returns a value of zero; otherwise, the function +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. + +.. _mq_unlink: + +mq_unlink - Remove a Message Queue +---------------------------------- +.. index:: mq_unlink +.. index:: remove a message queue + +**CALLING SEQUENCE:** + +.. code-block:: c + + #include + int mq_unlink( + const char *name + ); + +**STATUS CODES:** + +.. 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. + +**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 +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 +.. index:: send a message to a message queue + +**CALLING SEQUENCE:** + +.. code-block:: c + + #include + int mq_send( + mqd_t mqdes, + const char *msg_ptr, + size_t msg_len, + unsigned int msg_prio + ); + +**STATUS CODES:** + +.. 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 +```` 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. + +.. _mq_receive: + +mq_receive - Receive a Message from a Message Queue +--------------------------------------------------- +.. index:: mq_receive +.. index:: receive a message from a message queue + +**CALLING SEQUENCE:** + +.. code-block:: c + + #include + size_t mq_receive( + mqd_t mqdes, + char *msg_ptr, + size_t msg_len, + unsigned int *msg_prio + ); + +**STATUS CODES:** + +.. 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 +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. + +**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 + +.. _mq_notify: + +mq_notify - Notify Process that a Message is Available +------------------------------------------------------ +.. index:: mq_notify +.. index:: notify process that a message is available + +**CALLING SEQUENCE:** + +.. code-block:: c + + #include + int mq_notify( + mqd_t mqdes, + const struct sigevent *notification + ); + +**STATUS CODES:** + +.. 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``. + +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 be 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. + +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. + +.. _mq_setattr: + +mq_setattr - Set Message Queue Attributes +----------------------------------------- +.. index:: mq_setattr +.. index:: set message queue attributes + +**CALLING SEQUENCE:** + +.. code-block:: c + + #include + int mq_setattr( + mqd_t mqdes, + const struct mq_attr *mqstat, + struct mq_attr *omqstat + ); + +**STATUS CODES:** + +.. 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. + +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. + +**NOTES:** + +All other fields in the ``mq_attr`` are ignored by this call. + +.. _mq_getattr: + +mq_getattr - Get Message Queue Attributes +----------------------------------------- +.. index:: mq_getattr +.. index:: get message queue attributes + +**CALLING SEQUENCE:** + +.. code-block:: c + + #include + int mq_getattr( + mqd_t mqdes, + struct mq_attr *mqstat + ); + +**STATUS CODES:** + +.. 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. + +Upon successful completion, the ``mq_getattr`` function returns zero. +Otherwise, the function returns -1 and sets ``errno`` to indicate the error. + +**NOTES:** diff --git a/posix-users/mutex.rst b/posix-users/mutex.rst new file mode 100644 index 0000000..6fad624 --- /dev/null +++ b/posix-users/mutex.rst @@ -0,0 +1,673 @@ +.. comment SPDX-License-Identifier: CC-BY-SA-4.0 + +.. COMMENT: COPYRIGHT (c) 1988-2002. +.. COMMENT: On-Line Applications Research Corporation (OAR). +.. COMMENT: All rights reserved. + +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 services provided by the mutex manager are: + +- pthread_mutexattr_init_ - Initialize a Mutex Attribute Set + +- pthread_mutexattr_destroy_ - Destroy a Mutex Attribute Set + +- pthread_mutexattr_setprotocol_ - Set the Blocking Protocol + +- pthread_mutexattr_getprotocol_ - Get the Blocking Protocol + +- pthread_mutexattr_setprioceiling_ - Set the Priority Ceiling + +- pthread_mutexattr_getprioceiling_ - Get the Priority Ceiling + +- pthread_mutexattr_setpshared_ - Set the Visibility + +- pthread_mutexattr_getpshared_ - Get the Visibility + +- pthread_mutex_init_ - Initialize a Mutex + +- pthread_mutex_destroy_ - Destroy a Mutex + +- pthread_mutex_lock_ - Lock a Mutex + +- pthread_mutex_trylock_ - Poll to Lock a Mutex + +- pthread_mutex_timedlock_ - Lock a Mutex with Timeout + +- pthread_mutex_unlock_ - Unlock a Mutex + +- pthread_mutex_setprioceiling_ - Dynamically Set the Priority Ceiling + +- pthread_mutex_getprioceiling_ - Dynamically Get the Priority Ceiling + +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. + +.. list-table:: + :class: rtems-table + + * - *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-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. + +Note that the mutex will be initialized with default attributes. + +Operations +========== + +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. + +.. _pthread_mutexattr_init: + +pthread_mutexattr_init - Initialize a Mutex Attribute Set +--------------------------------------------------------- +.. index:: pthread_mutexattr_init +.. index:: initialize a mutex attribute set + +**CALLING SEQUENCE:** + +.. code-block:: c + + #include + int pthread_mutexattr_init( + pthread_mutexattr_t *attr + ); + +**STATUS CODES:** + +*EINVAL* + The attribute pointer argument is invalid. + +**DESCRIPTION:** + +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 +.. index:: destroy a mutex attribute set + +**CALLING SEQUENCE:** + +.. code-block:: c + + #include + int pthread_mutexattr_destroy( + pthread_mutexattr_t *attr + ); + +**STATUS CODES:** + +.. list-table:: + :class: rtems-table + + * - ``EINVAL`` + - The attribute pointer argument is invalid. + * - ``EINVAL`` + - The attribute set is not initialized. + +**DESCRIPTION:** + +The ``pthread_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. + +**NOTES:** + +NONE + +.. _pthread_mutexattr_setprotocol: + +pthread_mutexattr_setprotocol - Set the Blocking Protocol +--------------------------------------------------------- +.. index:: pthread_mutexattr_setprotocol +.. index:: set the blocking protocol + +**CALLING SEQUENCE:** + +.. code-block:: c + + #include + int pthread_mutexattr_setprotocol( + pthread_mutexattr_t *attr, + int protocol + ); + +**STATUS CODES:** + +.. list-table:: + :class: rtems-table + + * - ``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 ``protocol`` can be one of the following: + +.. list-table:: + :class: rtems-table + + * - ``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. + +.. _pthread_mutexattr_getprotocol: + +pthread_mutexattr_getprotocol - Get the Blocking Protocol +--------------------------------------------------------- +.. index:: pthread_mutexattr_getprotocol +.. index:: get the blocking protocol + +**CALLING SEQUENCE:** + +.. code-block:: c + + #include + int pthread_mutexattr_getprotocol( + pthread_mutexattr_t *attr, + int *protocol + ); + +**STATUS CODES:** + +.. list-table:: + :class: rtems-table + + * - ``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. + +**NOTES:** + +NONE + +.. _pthread_mutexattr_setprioceiling: + +pthread_mutexattr_setprioceiling - Set the Priority Ceiling +----------------------------------------------------------- +.. index:: pthread_mutexattr_setprioceiling +.. index:: set the priority ceiling + +**CALLING SEQUENCE:** + +.. code-block:: c + + #include + int pthread_mutexattr_setprioceiling( + pthread_mutexattr_t *attr, + int prioceiling + ); + +**STATUS CODES:** + +.. list-table:: + :class: rtems-table + + * - ``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``. + +**NOTES:** + +NONE + +.. _pthread_mutexattr_getprioceiling: + +pthread_mutexattr_getprioceiling - Get the Priority Ceiling +----------------------------------------------------------- +.. index:: pthread_mutexattr_getprioceiling +.. index:: get the priority ceiling + +**CALLING SEQUENCE:** + +.. code-block:: c + + #include + int pthread_mutexattr_getprioceiling( + const pthread_mutexattr_t *attr, + int *prioceiling + ); + +**STATUS CODES:** + +.. list-table:: + :class: rtems-table + + * - ``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. + +**NOTES:** + +NONE + +.. _pthread_mutexattr_setpshared: + +pthread_mutexattr_setpshared - Set the Visibility +------------------------------------------------- +.. index:: pthread_mutexattr_setpshared +.. index:: set the visibility + +**CALLING SEQUENCE:** + +.. code-block:: c + + #include + int pthread_mutexattr_setpshared( + pthread_mutexattr_t *attr, + int pshared + ); + +**STATUS CODES:** + +.. list-table:: + :class: rtems-table + + * - ``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 +.. index:: get the visibility + +**CALLING SEQUENCE:** + +.. code-block:: c + + #include + int pthread_mutexattr_getpshared( + const pthread_mutexattr_t *attr, + int *pshared + ); + +**STATUS CODES:** + +.. list-table:: + :class: rtems-table + + * - ``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 +.. index:: initialize a mutex + +**CALLING SEQUENCE:** + +.. code-block:: c + + #include + int pthread_mutex_init( + pthread_mutex_t *mutex, + const pthread_mutexattr_t *attr + ); + +**STATUS CODES:** + +.. 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 +.. index:: destroy a mutex + +**CALLING SEQUENCE:** + +.. code-block:: c + + #include + int pthread_mutex_destroy( + pthread_mutex_t *mutex + ); + +**STATUS CODES:** + +.. list-table:: + :class: rtems-table + + * - ``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 +.. index:: lock a mutex + +**CALLING SEQUENCE:** + +.. code-block:: c + + #include + int pthread_mutex_lock( + pthread_mutex_t *mutex + ); + +**STATUS CODES:** + +.. list-table:: + :class: rtems-table + + * - ``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 +.. index:: poll to lock a mutex + +**CALLING SEQUENCE:** + +.. code-block:: c + + #include + int pthread_mutex_trylock( + pthread_mutex_t *mutex + ); + +**STATUS CODES:** + +.. list-table:: + :class: rtems-table + + * - ``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 +.. index:: lock a mutex with timeout + +**CALLING SEQUENCE:** + +.. code-block:: c + + #include + #include + int pthread_mutex_timedlock( + pthread_mutex_t *mutex, + const struct timespec *timeout + ); + +**STATUS CODES:** + +.. 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 +.. index:: unlock a mutex + +**CALLING SEQUENCE:** + +.. code-block:: c + + #include + int pthread_mutex_unlock( + pthread_mutex_t *mutex + ); + +**STATUS CODES:** + +.. 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 +.. index:: dynamically set the priority ceiling + +**CALLING SEQUENCE:** + +.. code-block:: c + + #include + int pthread_mutex_setprioceiling( + pthread_mutex_t *mutex, + int prioceiling, + int *oldceiling + ); + +**STATUS CODES:** + +.. list-table:: + :class: rtems-table + + * - ``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 +.. index:: get the current priority ceiling + +**CALLING SEQUENCE:** + +.. code-block:: c + + #include + int pthread_mutex_getprioceiling( + pthread_mutex_t *mutex, + int *prioceiling + ); + +**STATUS CODES:** + +.. list-table:: + :class: rtems-table + + * - ``EINVAL`` + - The prioceiling pointer parameter is invalid. + * - ``EINVAL`` + - The specified mutex is invalid. + +**DESCRIPTION:** + +**NOTES:** diff --git a/posix-users/preface.rst b/posix-users/preface.rst new file mode 100644 index 0000000..0028d51 --- /dev/null +++ b/posix-users/preface.rst @@ -0,0 +1,52 @@ +.. comment SPDX-License-Identifier: CC-BY-SA-4.0 + +.. COMMENT: COPYRIGHT (c) 1988-2002. +.. COMMENT: On-Line Applications Research Corporation (OAR). +.. COMMENT: All rights reserved. + +Preface +####### + +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: + +- POSIX 1003.1b-1993. + +- POSIX 1003.1h/D3. + +- 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. + +This manual is still under construction and improvements are welcomed from +users. + +Acknowledgements +================ + +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. diff --git a/posix-users/process_creation_and_execution.rst b/posix-users/process_creation_and_execution.rst new file mode 100644 index 0000000..1668695 --- /dev/null +++ b/posix-users/process_creation_and_execution.rst @@ -0,0 +1,421 @@ +.. comment SPDX-License-Identifier: CC-BY-SA-4.0 + +.. COMMENT: COPYRIGHT (c) 1988-2002. +.. COMMENT: On-Line Applications Research Corporation (OAR). +.. COMMENT: All rights reserved. + +Process Creation and Execution Manager +###################################### + +Introduction +============ + +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 + +- execl_ - Execute a File + +- execv_ - Execute a File + +- execle_ - Execute a File + +- execve_ - Execute a File + +- execlp_ - Execute a File + +- execvp_ - Execute a File + +- pthread_atfork_ - Register Fork Handlers + +- wait_ - Wait for Process Termination + +- waitpid_ - Wait for Process Termination + +- `_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. + +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``. + +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. + +.. _fork: + +fork - Create a Process +----------------------- +.. index:: fork +.. index:: create a process + +**CALLING SEQUENCE:** + +.. code-block:: c + + #include + int fork( void ); + +**STATUS CODES:** + +.. list-table:: + :class: rtems-table + + * - ``ENOSYS`` + - This routine is not supported by RTEMS. + +**DESCRIPTION:** + +This routine is not supported by RTEMS. + +**NOTES:** + +NONE + +.. _execl: + +execl - Execute a File +---------------------- +.. index:: execl +.. index:: execute a file + +**CALLING SEQUENCE:** + +.. code-block:: c + + int execl( + const char *path, + const char *arg, + ... + ); + +**STATUS CODES:** + +.. list-table:: + :class: rtems-table + + * - ``ENOSYS`` + - This routine is not supported by RTEMS. + +**DESCRIPTION:** + +This routine is not supported by RTEMS. + +**NOTES:** + +NONE + +.. _execv: + +execv - Execute a File +---------------------- +.. index:: execv +.. index:: execute a file + +**CALLING SEQUENCE:** + +.. code-block:: c + + int execv( + const char *path, + char const *argv[], + ... + ); + +**STATUS CODES:** + +.. list-table:: + :class: rtems-table + + * - ``ENOSYS`` + - This routine is not supported by RTEMS. + +**DESCRIPTION:** + +This routine is not supported by RTEMS. + +**NOTES:** + +NONE + +.. _execle: + +execle - Execute a File +----------------------- +.. index:: execle +.. index:: execute a file + +**CALLING SEQUENCE:** + +.. code-block:: c + + int execle( + const char *path, + const char *arg, + ... + ); + +**STATUS CODES:** + +.. list-table:: + :class: rtems-table + + * - ``ENOSYS`` + - This routine is not supported by RTEMS. + +**DESCRIPTION:** + +This routine is not supported by RTEMS. + +**NOTES:** + +NONE + +.. _execve: + +execve - Execute a File +----------------------- +.. index:: execve +.. index:: execute a file + +**CALLING SEQUENCE:** + +.. code-block:: c + + int execve( + const char *path, + char *const argv[], + char *const envp[] + ); + +**STATUS CODES:** + +.. list-table:: + :class: rtems-table + + * - ``ENOSYS`` + - This routine is not supported by RTEMS. + +**DESCRIPTION:** + +This routine is not supported by RTEMS. + +**NOTES:** + +NONE + +.. _execlp: + +execlp - Execute a File +----------------------- +.. index:: execlp +.. index:: execute a file + +**CALLING SEQUENCE:** + +.. code-block:: c + + int execlp( + const char *file, + const char *arg, + ... + ); + +**STATUS CODES:** + +.. list-table:: + :class: rtems-table + + * - ``ENOSYS`` + - This routine is not supported by RTEMS. + +**DESCRIPTION:** + +This routine is not supported by RTEMS. + +**NOTES:** + +NONE + +.. _execvp: + +execvp - Execute a File +----------------------- +.. index:: execvp +.. index:: execute a file + +**CALLING SEQUENCE:** + +.. code-block:: c + + int execvp( + const char *file, + char *const argv[], + ... + ); + +**STATUS CODES:** + +.. list-table:: + :class: rtems-table + + * - ``ENOSYS`` + - This routine is not supported by RTEMS. + +**DESCRIPTION:** + +This routine is not supported by RTEMS. + +**NOTES:** + +NONE + +.. _pthread_atfork: + +pthread_atfork - Register Fork Handlers +--------------------------------------- +.. index:: pthread_atfork +.. index:: register fork handlers + +**CALLING SEQUENCE:** + +.. code-block:: c + + #include + int pthread_atfork( + void (*prepare)(void), + void (*parent)(void), + void (*child)(void) + ); + +**STATUS CODES:** + +.. list-table:: + :class: rtems-table + + * - ``ENOSYS`` + - This routine is not supported by RTEMS. + +**DESCRIPTION:** + +This routine is not supported by RTEMS. + +**NOTES:** + +NONE + +.. _wait: + +wait - Wait for Process Termination +----------------------------------- +.. index:: wait +.. index:: wait for process termination + +**CALLING SEQUENCE:** + +.. code-block:: c + + #include + #include + int wait( + int *stat_loc + ); + +**STATUS CODES:** + +.. list-table:: + :class: rtems-table + + * - ``ENOSYS`` + - This routine is not supported by RTEMS. + +**DESCRIPTION:** + +This routine is not supported by RTEMS. + +**NOTES:** + +NONE + +.. _waitpid: + +waitpid - Wait for Process Termination +-------------------------------------- +.. index:: waitpid +.. index:: wait for process termination + +**CALLING SEQUENCE:** + +.. code-block:: c + + int wait( + pid_t pid, + int *stat_loc, + int options + ); + +**STATUS CODES:** + +.. list-table:: + :class: rtems-table + + * - ``ENOSYS`` + - This routine is not supported by RTEMS. + +**DESCRIPTION:** + +This routine is not supported by RTEMS. + +**NOTES:** + +NONE + +.. _\_exit: + +_exit - Terminate a Process +--------------------------- +.. index:: _exit +.. index:: terminate a process + +**CALLING SEQUENCE:** + +.. code-block:: c + + void _exit( + int status + ); + +**STATUS CODES:** + +NONE + +**DESCRIPTION:** + +The ``_exit()`` function terminates the calling process. + +**NOTES:** + +In RTEMS, a process is equivalent to the entire application on a single +processor. Invoking this service terminates the application. diff --git a/posix-users/process_environment.rst b/posix-users/process_environment.rst new file mode 100644 index 0000000..0556d12 --- /dev/null +++ b/posix-users/process_environment.rst @@ -0,0 +1,807 @@ +.. comment SPDX-License-Identifier: CC-BY-SA-4.0 + +.. COMMENT: COPYRIGHT (c) 1988-2002. +.. COMMENT: On-Line Applications Research Corporation (OAR). +.. COMMENT: All rights reserved. + +Process Environment Manager +########################### + +Introduction +============ + +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 + +- getppid_ - Get Parent Process ID + +- getuid_ - Get User ID + +- geteuid_ - Get Effective User ID + +- getgid_ - Get Real Group ID + +- getegid_ - Get Effective Group ID + +- setuid_ - Set User ID + +- setgid_ - Set Group ID + +- getgroups_ - Get Supplementary Group IDs + +- getlogin_ - Get User Name + +- getlogin_r_ - Reentrant Get User Name + +- getpgrp_ - Get Process Group ID + +- setsid_ - Create Session and Set Process Group ID + +- setpgid_ - Set Process Group ID for Job Control + +- uname_ - Get System Name + +- times_ - Get Process Times + +- getenv_ - Get Environment Variables + +- setenv_ - Set Environment Variables + +- ctermid_ - Generate Terminal Pathname + +- ttyname_ - Determine Terminal Device Name + +- ttyname_r_ - Reentrant Determine Terminal Device Name + +- isatty_ - Determine if File Descriptor is Terminal + +- sysconf_ - Get Configurable System Variables + +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. + +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 +: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. + +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. + +Accessing Environment Variables +------------------------------- + +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. + +.. _getpid: + +getpid - Get Process ID +----------------------- +.. index:: getpid +.. index:: get process id + +**CALLING SEQUENCE:** + +.. code-block:: c + + int getpid( void ); + +**STATUS CODES:** + +The process Id is returned. + +**DESCRIPTION:** + +This service returns the process Id. + +**NOTES:** + +NONE + +.. _getppid: + +getppid - Get Parent Process ID +------------------------------- +.. index:: getppid +.. index:: get parent process id + +**CALLING SEQUENCE:** + +.. code-block:: c + + int getppid( void ); + +**STATUS CODES:** + +The parent process Id is returned. + +**DESCRIPTION:** + +This service returns the parent process Id. + +**NOTES:** + +NONE + +.. _getuid: + +getuid - Get User ID +-------------------- +.. index:: getuid +.. index:: get user id + +**CALLING SEQUENCE:** + +.. code-block:: c + + int getuid( void ); + +**STATUS CODES:** + +The effective user Id is returned. + +**DESCRIPTION:** + +This service returns the effective user Id. + +**NOTES:** + +NONE + +.. _geteuid: + +geteuid - Get Effective User ID +------------------------------- +.. index:: geteuid +.. index:: get effective user id + +**CALLING SEQUENCE:** + +.. code-block:: c + + int geteuid( void ); + +**STATUS CODES:** + +The effective group Id is returned. + +**DESCRIPTION:** + +This service returns the effective group Id. + +**NOTES:** + +NONE + +.. _getgid: + +getgid - Get Real Group ID +-------------------------- +.. index:: getgid +.. index:: get real group id + +**CALLING SEQUENCE:** + +.. code-block:: c + + int getgid( void ); + +**STATUS CODES:** + +The group Id is returned. + +**DESCRIPTION:** + +This service returns the group Id. + +**NOTES:** + +NONE + +.. _getegid: + +getegid - Get Effective Group ID +-------------------------------- +.. index:: getegid +.. index:: get effective group id + +**CALLING SEQUENCE:** + +.. code-block:: c + + int getegid( void ); + +**STATUS CODES:** + +The effective group Id is returned. + +**DESCRIPTION:** + +This service returns the effective group Id. + +**NOTES:** + +NONE + +.. _setuid: + +setuid - Set User ID +-------------------- +.. index:: setuid +.. index:: set user id + +**CALLING SEQUENCE:** + +.. code-block:: c + + int setuid( + uid_t uid + ); + +**STATUS CODES:** + +This service returns 0. + +**DESCRIPTION:** + +This service sets the user Id to ``uid``. + +**NOTES:** + +NONE + +.. _setgid: + +setgid - Set Group ID +--------------------- +.. index:: setgid +.. index:: set group id + +**CALLING SEQUENCE:** + +.. code-block:: c + + int setgid( + gid_t gid + ); + +**STATUS CODES:** + +This service returns 0. + +**DESCRIPTION:** + +This service sets the group Id to ``gid``. + +**NOTES:** + +NONE + +.. _getgroups: + +getgroups - Get Supplementary Group IDs +--------------------------------------- +.. index:: getgroups +.. index:: get supplementary group ids + +**CALLING SEQUENCE:** + +.. code-block:: c + + int getgroups( + int gidsetsize, + gid_t grouplist[] + ); + +**STATUS CODES:** + +NA + +**DESCRIPTION:** + +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. + +.. _getlogin: + +getlogin - Get User Name +------------------------ +.. index:: getlogin +.. index:: get user name + +**CALLING SEQUENCE:** + +.. code-block:: c + + char *getlogin( void ); + +**STATUS CODES:** + +Returns a pointer to a string containing the name of the current user. + +**DESCRIPTION:** + +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. + +.. _getlogin_r: + +getlogin_r - Reentrant Get User Name +------------------------------------ +.. index:: getlogin_r +.. index:: reentrant get user name +.. index:: get user name, reentrant + +**CALLING SEQUENCE:** + +.. code-block:: c + + int getlogin_r( + char *name, + size_t namesize + ); + +**STATUS CODES:** + +.. 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``. + +**NOTES:** + +NONE + +.. _getpgrp: + +getpgrp - Get Process Group ID +------------------------------ +.. index:: getpgrp +.. index:: get process group id + +**CALLING SEQUENCE:** + +.. code-block:: c + + pid_t getpgrp( void ); + +**STATUS CODES:** + +The procress group Id is returned. + +**DESCRIPTION:** + +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. + +.. _setsid: + +setsid - Create Session and Set Process Group ID +------------------------------------------------ +.. index:: setsid +.. index:: create session and set process group id + +**CALLING SEQUENCE:** + +.. code-block:: c + + pid_t setsid( void ); + +**STATUS CODES:** + +.. 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. + +**NOTES:** + +NONE + +.. _setpgid: + +setpgid - Set Process Group ID for Job Control +---------------------------------------------- +.. index:: setpgid +.. index:: set process group id for job control + +**CALLING SEQUENCE:** + +.. code-block:: c + + int setpgid( + pid_t pid, + pid_t pgid + ); + +**STATUS CODES:** + +.. 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. + +**NOTES:** + +NONE + +.. _uname: + +uname - Get System Name +----------------------- +.. index:: uname +.. index:: get system name + +**CALLING SEQUENCE:** + +.. code-block:: c + + int uname( + struct utsname *name + ); + +**STATUS CODES:** + +.. 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. + +**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. + +.. _times: + +times - Get process times +------------------------- +.. index:: times +.. index:: get process times + +**CALLING SEQUENCE:** + +.. code-block:: c + + #include + clock_t times( + 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). + +**DESCRIPTION:** + +``times`` stores the current process times in ``ptms``. The format of ``struct +tms`` is as defined in ````. 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. + +.. _getenv: + +getenv - Get Environment Variables +---------------------------------- +.. index:: getenv +.. index:: get environment variables + +**CALLING SEQUENCE:** + +.. code-block:: c + + char *getenv( + const char *name + ); + +**STATUS CODES:** + +.. list-table:: + :class: rtems-table + + * - ``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. + +**NOTES:** + +The environment list consists of name value pairs that are of the form ``name = +value``. + +.. _setenv: + +setenv - Set Environment Variables +---------------------------------- +.. index:: setenv +.. index:: set environment variables + +**CALLING SEQUENCE:** + +.. code-block:: c + + int setenv( + const char *name, + const char *value, + int overwrite + ); + +**STATUS CODES:** + +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. + +**NOTES:** + +NONE + +.. _ctermid: + +ctermid - Generate Terminal Pathname +------------------------------------ +.. index:: ctermid +.. index:: generate terminal pathname + +**CALLING SEQUENCE:** + +.. code-block:: c + + char *ctermid( + char *s + ); + +**STATUS CODES:** + +Returns a pointer to a string indicating the pathname for the controlling +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. + +**NOTES:** + +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 +---------------------------------------- +.. index:: ttyname +.. index:: determine terminal device name + +**CALLING SEQUENCE:** + +.. code-block:: c + + char *ttyname( + int fd + ); + +**STATUS CODES:** + +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. + +**NOTES:** + +This routine uses a static buffer. + +.. _ttyname_r: + +ttyname_r - Reentrant Determine Terminal Device Name +---------------------------------------------------- +.. index:: ttyname_r +.. index:: reentrant determine terminal device name + +**CALLING SEQUENCE:** + +.. code-block:: c + + int ttyname_r( + int fd, + char *name, + int namesize + ); + +**STATUS CODES:** + +This routine returns -1 and sets ``errno`` as follows: + +.. list-table:: + :class: rtems-table + + * - ``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``. + +**NOTES:** + +NONE + +.. _isatty: + +isatty - Determine if File Descriptor is Terminal +------------------------------------------------- +.. index:: isatty +.. index:: determine if file descriptor is terminal + +**CALLING SEQUENCE:** + +.. code-block:: c + + int isatty( + int fd + ); + +**STATUS CODES:** + +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. + +**NOTES:** + +.. _sysconf: + +sysconf - Get Configurable System Variables +------------------------------------------- +.. index:: sysconf +.. index:: get configurable system variables + +**CALLING SEQUENCE:** + +.. code-block:: c + + long sysconf( + 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. + +**DESCRIPTION:** + +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. diff --git a/posix-users/scheduler.rst b/posix-users/scheduler.rst new file mode 100644 index 0000000..9209391 --- /dev/null +++ b/posix-users/scheduler.rst @@ -0,0 +1,209 @@ +.. comment SPDX-License-Identifier: CC-BY-SA-4.0 + +.. COMMENT: COPYRIGHT (c) 1988-2002. +.. COMMENT: On-Line Applications Research Corporation (OAR). +.. COMMENT: All rights reserved. + +Scheduler Manager +################# + +Introduction +============ + +The scheduler manager ... + +The directives provided by the scheduler manager are: + +- sched_get_priority_min_ - Get Minimum Priority Value + +- sched_get_priority_max_ - Get Maximum Priority Value + +- sched_rr_get_interval_ - Get Timeslicing Quantum + +- sched_yield_ - Yield the Processor + +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 +priorities. + +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. + +*SCHED_RR* + Priority-based, preemptive scheduling with timeslicing. Time quantums are + maintained on a per-thread basis and are not reset at each context switch. + Thus, a thread which is preempted and subsequently resumes execution will + attempt to complete the unused portion of its time quantum. + +*SCHED_OTHER* + Priority-based, preemptive scheduling with timeslicing. Time quantums are + 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. + +Operations +========== + +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. + +.. _sched_get_priority_min: + +sched_get_priority_min - Get Minimum Priority Value +--------------------------------------------------- +.. index:: sched_get_priority_min +.. index:: get minimum priority value + +**CALLING SEQUENCE:** + +.. code-block:: c + + #include + int sched_get_priority_min( + int policy + ); + +**STATUS CODES:** + +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. + +**DESCRIPTION:** + +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 +.. index:: get maximum priority value + +**CALLING SEQUENCE:** + +.. code-block:: c + + #include + int sched_get_priority_max( + int policy + ); + +**STATUS CODES:** + +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. + +**DESCRIPTION:** + +This routine return the maximum (numerically and logically highest) priority +for the specified ``policy``. + +**NOTES:** + +NONE + +.. _sched_rr_get_interval: + +sched_rr_get_interval - Get Timeslicing Quantum +----------------------------------------------- +.. index:: sched_rr_get_interval +.. index:: get timeslicing quantum + +**CALLING SEQUENCE:** + +.. code-block:: c + + #include + int sched_rr_get_interval( + pid_t pid, + struct timespec *interval + ); + +**STATUS CODES:** + +On error, this routine returns -1 and sets ``errno`` to one of the following: + +.. list-table:: + :class: rtems-table + + * - ``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``. + +**NOTES:** + +The ``pid`` argument should be 0 to indicate the calling process. + +.. _sched_yield: + +sched_yield - Yield the Processor +--------------------------------- +.. index:: sched_yield +.. index:: yield the processor + +**CALLING SEQUENCE:** + +.. code-block:: c + + #include + int sched_yield( void ); + +**STATUS CODES:** + +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. + +**NOTES:** + +NONE diff --git a/posix-users/semaphore.rst b/posix-users/semaphore.rst new file mode 100644 index 0000000..27fdf51 --- /dev/null +++ b/posix-users/semaphore.rst @@ -0,0 +1,543 @@ +.. comment SPDX-License-Identifier: CC-BY-SA-4.0 + +.. COMMENT: COPYRIGHT (c) 1989-2008. +.. COMMENT: On-Line Applications Research Corporation (OAR). +.. COMMENT: All rights reserved. + +Semaphore Manager +################# + +Introduction +============ + +The semaphore manager provides functions to allocate, delete, and control +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_destroy_ - Destroy an unnamed semaphore + +- sem_open_ - Open a named semaphore + +- sem_close_ - Close a named semaphore + +- sem_unlink_ - Remove a named semaphore + +- sem_wait_ - Lock a semaphore + +- sem_trywait_ - Lock a semaphore + +- sem_timedwait_ - Wait on a Semaphore for a Specified Time + +- sem_post_ - Unlock a semaphore + +- sem_getvalue_ - Get the value of a semeaphore + +Background +========== + +Theory +------ + +Semaphores are used for synchronization and mutual exclusion by indicating the +availability and number of resources. The task (the task which is returning +resources) notifying other tasks of an event increases the number of resources +held by the semaphore by one. The task (the task which will obtain resources) +waiting for the event decreases the number of resources held by the semaphore +by one. If the number of resources held by a semaphore is insufficient (namely +0), the task requiring resources will wait until the next time resources are +returned to the semaphore. If there is more than one task waiting for a +semaphore, the tasks will be placed in the queue. + +"sem_t" Structure +----------------- +.. index:: sem_t + +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-block:: c + + typedef int sem_t; + +Building a Semaphore Attribute Set +---------------------------------- + +Operations +========== + +Using as a Binary Semaphore +--------------------------- + +Although POSIX supports mutexes, they are only visible between threads. To work +between processes, a binary semaphore must be used. + +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. + +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. + +.. _sem_init: + +sem_init - Initialize an unnamed semaphore +------------------------------------------ +.. index:: sem_init +.. index:: initialize an unnamed semaphore + +**CALLING SEQUENCE:** + +.. code-block:: c + + int sem_init( + sem_t *sem, + int pshared, + unsigned int value + ); + +**STATUS CODES:** + +.. list-table:: + :class: rtems-table + + * - ``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. + +.. 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 +that occurred. + +Multiprocessing is currently not supported in this implementation. + +.. _sem_destroy: + +sem_destroy - Destroy an unnamed semaphore +------------------------------------------ +.. index:: sem_destroy +.. index:: destroy an unnamed semaphore + +**CALLING SEQUENCE:** + +.. code-block:: c + + int sem_destroy( + sem_t *sem + ); + +**STATUS CODES:** + +.. list-table:: + :class: rtems-table + + * - ``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. + +**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 +that occurred. + +Multiprocessing is currently not supported in this implementation. + +.. _sem_open: + +sem_open - Open a named semaphore +--------------------------------- +.. index:: sem_open +.. index:: open a named semaphore + +**CALLING SEQUENCE:** + +.. code-block:: c + + int sem_open( + const char *name, + int oflag + ); + +**ARGUMENTS:** + +The following flag bit may be set in oflag: + +.. list-table:: + :class: rtems-table + + * - ``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:** + +.. 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()``. + +**NOTES:** + +.. _sem_close: + +sem_close - Close a named semaphore +----------------------------------- +.. index:: sem_close +.. index:: close a named semaphore + +**CALLING SEQUENCE:** + +.. code-block:: c + + int sem_close( + sem_t *sem_close + ); + +**STATUS CODES:** + +.. list-table:: + :class: rtems-table + + * - ``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. + +**NOTES:** + +.. _sem_unlink: + +sem_unlink - Unlink a semaphore +------------------------------- +.. index:: sem_unlink +.. index:: unlink a semaphore + +**CALLING SEQUENCE:** + +.. code-block:: c + + int sem_unlink( + const char *name + ); + +**STATUS CODES:** + +.. 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. + +If the termination is successful, the function shall return 0. Otherwise, a -1 +is returned and the ``errno`` is set. + +**NOTES:** + +.. _sem_wait: + +sem_wait - Wait on a Semaphore +------------------------------ +.. index:: sem_wait +.. index:: wait on a semaphore + +**CALLING SEQUENCE:** + +.. code-block:: c + + int sem_wait( + sem_t *sem + ); + +**STATUS CODES:** + +.. list-table:: + :class: rtems-table + + * - ``EINVAL`` + - The ``sem`` argument does not refer 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). If the semaphore is unavailable (i.e., the semaphore +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. + +**NOTES:** + +Multiprocessing is not supported in this implementation. + +.. _sem_trywait: + +sem_trywait - Non-blocking Wait on a Semaphore +---------------------------------------------- +.. index:: sem_trywait +.. index:: non + +**CALLING SEQUENCE:** + +.. code-block:: c + + int sem_trywait( + sem_t *sem + ); + +**STATUS CODES:** + +.. list-table:: + :class: rtems-table + + * - ``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``. + +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 +.. index:: wait on a semaphore for a specified time + +**CALLING SEQUENCE:** + +.. code-block:: c + + int sem_timedwait( + sem_t *sem, + const struct timespec *abstime + ); + +**STATUS CODES:** + +.. list-table:: + :class: rtems-table + + * - ``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. + +**NOTES:** + +Multiprocessing is not supported in this implementation. + +.. _sem_post: + +sem_post - Unlock a Semaphore +----------------------------- +.. index:: sem_post +.. index:: unlock a semaphore + +**CALLING SEQUENCE:** + +.. code-block:: c + + int sem_post( + sem_t *sem + ); + +**STATUS CODES:** + +.. 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. + +If an error occurs, the function returns -1 and sets ``errno`` to the +appropriate error code. + +**NOTES:** + +Multiprocessing is not supported in this implementation. + +.. _sem_getvalue: + +sem_getvalue - Get the value of a semaphore +------------------------------------------- +.. index:: sem_getvalue +.. index:: get the value of a semaphore + +**CALLING SEQUENCE:** + +.. code-block:: c + + int sem_getvalue( + sem_t *sem, + int *sval + ); + +**STATUS CODES:** + +.. list-table:: + :class: rtems-table + + * - ``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. + +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 +that occurred. diff --git a/posix-users/services_provided_by_c.rst b/posix-users/services_provided_by_c.rst new file mode 100644 index 0000000..e6b8f58 --- /dev/null +++ b/posix-users/services_provided_by_c.rst @@ -0,0 +1,442 @@ +.. comment SPDX-License-Identifier: CC-BY-SA-4.0 + +.. COMMENT: COPYRIGHT (c) 1988-2002. +.. COMMENT: On-Line Applications Research Corporation (OAR). +.. COMMENT: All rights reserved. + +Services Provided by C Library (libc) +##################################### + +Introduction +============ + +This section lists the routines that provided by the Newlib C Library. + +Standard Utility Functions (stdlib.h) +===================================== + +- ``abort`` - Abnormal termination of a program + +- ``abs`` - Integer absolute value (magnitude) + +- ``assert`` - Macro for Debugging Diagnostics + +- ``atexit`` - Request execution of functions at program exit + +- ``atof`` - String to double or float + +- ``atoi`` - String to integer + +- ``bsearch`` - Binary search + +- ``calloc`` - Allocate space for arrays + +- ``div`` - Divide two integers + +- ``ecvtbuf`` - Double or float to string of digits + +- ``ecvt`` - Double or float to string of digits (malloc result) + +- ``__env_lock`` - Lock environment list for getenv and setenv + +- ``gvcvt`` - Format double or float as string + +- ``exit`` - End program execution + +- ``getenv`` - Look up environment variable + +- ``labs`` - Long integer absolute value (magnitude) + +- ``ldiv`` - Divide two long integers + +- ``malloc`` - Allocate memory + +- ``realloc`` - Reallocate memory + +- ``free`` - Free previously allocated memory + +- ``mallinfo`` - Get information about allocated memory + +- ``__malloc_lock`` - Lock memory pool for malloc and free + +- ``mbstowcs`` - Minimal multibyte string to wide string converter + +- ``mblen`` - Minimal multibyte length + +- ``mbtowc`` - Minimal multibyte to wide character converter + +- ``qsort`` - Sort an array + +- ``rand`` - Pseudo-random numbers + +- ``strtod`` - String to double or float + +- ``strtol`` - String to long + +- ``strtoul`` - String to unsigned long + +- ``system`` - Execute command string + +- ``wcstombs`` - Minimal wide string to multibyte string converter + +- ``wctomb`` - Minimal wide character to multibyte converter + +Character Type Macros and Functions (ctype.h) +============================================= + +- ``isalnum`` - Alphanumeric character predicate + +- ``isalpha`` - Alphabetic character predicate + +- ``isascii`` - ASCII character predicate + +- ``iscntrl`` - Control character predicate + +- ``isdigit`` - Decimal digit predicate + +- ``islower`` - Lower-case character predicate + +- ``isprint`` - Printable character predicates (isprint, isgraph) + +- ``ispunct`` - Punctuation character predicate + +- ``isspace`` - Whitespace character predicate + +- ``isupper`` - Uppercase character predicate + +- ``isxdigit`` - Hexadecimal digit predicate + +- ``toascii`` - Force integers to ASCII range + +- ``tolower`` - Translate characters to lower case + +- ``toupper`` - Translate characters to upper case + +Input and Output (stdio.h) +========================== + +- ``clearerr`` - Clear file or stream error indicator + +- ``fclose`` - Close a file + +- ``feof`` - Test for end of file + +- ``ferror`` - Test whether read/write error has occurred + +- ``fflush`` - Flush buffered file output + +- ``fgetc`` - Get a character from a file or stream + +- ``fgetpos`` - Record position in a stream or file + +- ``fgets`` - Get character string from a file or stream + +- ``fiprintf`` - Write formatted output to file (integer only) + +- ``fopen`` - Open a file + +- ``fdopen`` - Turn an open file into a stream + +- ``fputc`` - Write a character on a stream or file + +- ``fputs`` - Write a character string in a file or stream + +- ``fread`` - Read array elements from a file + +- ``freopen`` - Open a file using an existing file descriptor + +- ``fseek`` - Set file position + +- ``fsetpos`` - Restore position of a stream or file + +- ``ftell`` - Return position in a stream or file + +- ``fwrite`` - Write array elements from memory to a file or stream + +- ``getc`` - Get a character from a file or stream (macro) + +- ``getchar`` - Get a character from standard input (macro) + +- ``gets`` - Get character string from standard input (obsolete) + +- ``iprintf`` - Write formatted output (integer only) + +- ``mktemp`` - Generate unused file name + +- ``perror`` - Print an error message on standard error + +- ``putc`` - Write a character on a stream or file (macro) + +- ``putchar`` - Write a character on standard output (macro) + +- ``puts`` - Write a character string on standard output + +- ``remove`` - Delete a file's name + +- ``rename`` - Rename a file + +- ``rewind`` - Reinitialize a file or stream + +- ``setbuf`` - Specify full buffering for a file or stream + +- ``setvbuf`` - Specify buffering for a file or stream + +- ``siprintf`` - Write formatted output (integer only) + +- ``printf`` - Write formatted output + +- ``scanf`` - Scan and format input + +- ``tmpfile`` - Create a temporary file + +- ``tmpnam`` - Generate name for a temporary file + +- ``vprintf`` - Format variable argument list + +Strings and Memory (string.h) +============================= + +- ``bcmp`` - Compare two memory areas + +- ``bcopy`` - Copy memory regions + +- ``bzero`` - Initialize memory to zero + +- ``index`` - Search for character in string + +- ``memchr`` - Find character in memory + +- ``memcmp`` - Compare two memory areas + +- ``memcpy`` - Copy memory regions + +- ``memmove`` - Move possibly overlapping memory + +- ``memset`` - Set an area of memory + +- ``rindex`` - Reverse search for character in string + +- ``strcasecmp`` - Compare strings ignoring case + +- ``strcat`` - Concatenate strings + +- ``strchr`` - Search for character in string + +- ``strcmp`` - Character string compare + +- ``strcoll`` - Locale specific character string compare + +- ``strcpy`` - Copy string + +- ``strcspn`` - Count chars not in string + +- ``strerror`` - Convert error number to string + +- ``strlen`` - Character string length + +- ``strlwr`` - Convert string to lower case + +- ``strncasecmp`` - Compare strings ignoring case + +- ``strncat`` - Concatenate strings + +- ``strncmp`` - Character string compare + +- ``strncpy`` - Counted copy string + +- ``strpbrk`` - Find chars in string + +- ``strrchr`` - Reverse search for character in string + +- ``strspn`` - Find initial match + +- ``strstr`` - Find string segment + +- ``strtok`` - Get next token from a string + +- ``strupr`` - Convert string to upper case + +- ``strxfrm`` - Transform string + +Signal Handling (signal.h) +========================== + +- ``raise`` - Send a signal + +- ``signal`` - Specify handler subroutine for a signal + +Time Functions (time.h) +======================= + +- ``asctime`` - Format time as string + +- ``clock`` - Cumulative processor time + +- ``ctime`` - Convert time to local and format as string + +- ``difftime`` - Subtract two times + +- ``gmtime`` - Convert time to UTC (GMT) traditional representation + +- ``localtime`` - Convert time to local representation + +- ``mktime`` - Convert time to arithmetic representation + +- ``strftime`` - Flexible calendar time formatter + +- ``time`` - Get current calendar time (as single number) + +Locale (locale.h) +================= + +- ``setlocale`` - Select or query locale + +Reentrant Versions of Functions +=============================== + +- Equivalent for errno variable: + - ``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 + - ``fopen_r`` - XXX + - ``putchar_r`` - XXX + - ``tmpnam_r`` - XXX + - ``getchar_r`` - XXX + - ``puts_r`` - XXX + - ``tmpfile_r`` - XXX + - ``gets_r`` - XXX + - ``remove_r`` - XXX + - ``vfprintf_r`` - XXX + - ``iprintf_r`` - XXX + - ``rename_r`` - XXX + - ``vsnprintf_r`` - XXX + - ``mkstemp_r`` - XXX + - ``snprintf_r`` - XXX + - ``vsprintf_r`` - XXX + - ``mktemp_t`` - XXX + - ``sprintf_r`` - XXX + +- Signal functions: + + - ``init_signal_r`` - XXX + - ``signal_r`` - XXX + - ``kill_r`` - XXX + - ``_sigtramp_r`` - XXX + - ``raise_r`` - XXX + +- Stdlib functions: + + - ``calloc_r`` - XXX + - ``mblen_r`` - XXX + - ``srand_r`` - XXX + - ``dtoa_r`` - XXX + - ``mbstowcs_r`` - XXX + - ``strtod_r`` - XXX + - ``free_r`` - XXX + - ``mbtowc_r`` - XXX + - ``strtol_r`` - XXX + - ``getenv_r`` - XXX + - ``memalign_r`` - XXX + - ``strtoul_r`` - XXX + - ``mallinfo_r`` - XXX + - ``mstats_r`` - XXX + - ``system_r`` - XXX + - ``malloc_r`` - XXX + - ``rand_r`` - XXX + - ``wcstombs_r`` - XXX + - ``malloc_r`` - XXX + - ``realloc_r`` - XXX + - ``wctomb_r`` - XXX + - ``malloc_stats_r`` - XXX + - ``setenv_r`` - XXX + +- String functions: + + - ``strtok_r`` - XXX + +- System functions: + + - ``close_r`` - XXX + - ``link_r`` - XXX + - ``unlink_r`` - XXX + - ``execve_r`` - XXX + - ``lseek_r`` - XXX + - ``wait_r`` - XXX + - ``fcntl_r`` - XXX + - ``open_r`` - XXX + - ``write_r`` - XXX + - ``fork_r`` - XXX + - ``read_r`` - XXX + - ``fstat_r`` - XXX + - ``sbrk_r`` - XXX + - ``gettimeofday_r`` - XXX + - ``stat_r`` - XXX + - ``getpid_r`` - XXX + - ``times_r`` - XXX + +- Time function: + + - ``asctime_r`` - XXX + +Miscellaneous Macros and Functions +================================== + +- ``unctrl`` - Return printable representation of a character + +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 + - ``va_end-trad`` - XXX + +Reentrant System Calls +====================== + +- ``open_r`` - XXX + +- ``close_r`` - XXX + +- ``lseek_r`` - XXX + +- ``read_r`` - XXX + +- ``write_r`` - XXX + +- ``fork_r`` - XXX + +- ``wait_r`` - XXX + +- ``stat_r`` - XXX + +- ``fstat_r`` - XXX + +- ``link_r`` - XXX + +- ``unlink_r`` - XXX + +- ``sbrk_r`` - XXX diff --git a/posix-users/services_provided_by_math.rst b/posix-users/services_provided_by_math.rst new file mode 100644 index 0000000..43a6aa5 --- /dev/null +++ b/posix-users/services_provided_by_math.rst @@ -0,0 +1,98 @@ +.. comment SPDX-License-Identifier: CC-BY-SA-4.0 + +Services Provided by the Math Library (libm) +############################################ + +Introduction +============ + +This section lists the routines that provided by the Newlib Math Library +(libm). + +Standard Math Functions (math.h) +================================ + +- ``acos`` - Arccosine + +- ``acosh`` - Inverse hyperbolic cosine + +- ``asin`` - Arcsine + +- ``asinh`` - Inverse hyperbolic sine + +- ``atan`` - Arctangent + +- ``atan2`` - Arctangent of y/x + +- ``atanh`` - Inverse hyperbolic tangent + +- ``jN`` - Bessel functions (jN and yN) + +- ``cbrt`` - Cube root + +- ``copysign`` - Sign of Y and magnitude of X + +- ``cosh`` - Hyperbolic cosine + +- ``erf`` - Error function (erf and erfc) + +- ``exp`` - Exponential + +- ``expm1`` - Exponential of x and - 1 + +- ``fabs`` - Absolute value (magnitude) + +- ``floor`` - Floor and ceiling (floor and ceil) + +- ``fmod`` - Floating-point remainder (modulo) + +- ``frexp`` - Split floating-point number + +- ``gamma`` - Logarithmic gamma function + +- ``hypot`` - Distance from origin + +- ``ilogb`` - Get exponent + +- ``infinity`` - Floating infinity + +- ``isnan`` - Check type of number + +- ``ldexp`` - Load exponent + +- ``log`` - Natural logarithms + +- ``log10`` - Base 10 logarithms + +- ``log1p`` - Log of 1 + X + +- ``matherr`` - Modifiable math error handler + +- ``modf`` - Split fractional and integer parts + +- ``nan`` - Floating Not a Number + +- ``nextafter`` - Get next representable number + +- ``pow`` - X to the power Y + +- ``remainder`` - remainder of X divided by Y + +- ``scalbn`` - scalbn + +- ``sin`` - Sine or cosine (sin and cos) + +- ``sinh`` - Hyperbolic sine + +- ``sqrt`` - Positive square root + +- ``tan`` - Tangent + +- ``tanh`` - Hyperbolic tangent + +.. 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 new file mode 100644 index 0000000..490c132 --- /dev/null +++ b/posix-users/signal.rst @@ -0,0 +1,989 @@ +.. comment SPDX-License-Identifier: CC-BY-SA-4.0 + +.. COMMENT: COPYRIGHT (c) 1988-2002. +.. COMMENT: On-Line Applications Research Corporation (OAR). +.. COMMENT: All rights reserved. + +Signal Manager +############## + +Introduction +============ + +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 + +- sigdelset_ - Delete a Signal from a Signal Set + +- sigfillset_ - Fill a Signal Set + +- sigismember_ - Is Signal a Member of a Signal Set + +- sigemptyset_ - Empty a Signal Set + +- sigaction_ - Examine and Change Signal Action + +- pthread_kill_ - Send a Signal to a Thread + +- sigprocmask_ - Examine and Change Process Blocked Signals + +- pthread_sigmask_ - Examine and Change Thread Blocked Signals + +- kill_ - Send a Signal to a Process + +- sigpending_ - Examine Pending Signals + +- sigsuspend_ - Wait for a Signal + +- pause_ - Suspend Process Execution + +- sigwait_ - Synchronously Accept a Signal + +- sigwaitinfo_ - Synchronously Accept a Signal + +- sigtimedwait_ - Synchronously Accept a Signal with Timeout + +- sigqueue_ - Queue a Signal to a Process + +- alarm_ - Schedule Alarm + +- ualarm_ - Schedule Alarm in Microseconds + +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. + +.. 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. + +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: + +#. 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 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. + +#. 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 +========== + +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. + +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. + +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()`` + +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. + +.. _sigaddset: + +sigaddset - Add a Signal to a Signal Set +---------------------------------------- +.. index:: sigaddset +.. index:: add a signal to a signal set + +**CALLING SEQUENCE:** + +.. code-block:: c + + #include + int sigaddset( + 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: + +.. list-table:: + :class: rtems-table + + * - ``EINVAL`` + - Invalid argument passed. + +**DESCRIPTION:** + +This function adds the signal ``signo`` to the specified signal ``set``. + +**NOTES:** + +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 +.. index:: delete a signal from a signal set + +**CALLING SEQUENCE:** + +.. code-block:: c + + #include + int sigdelset( + 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: + +.. list-table:: + :class: rtems-table + + * - ``EINVAL`` + - Invalid argument passed. + +**DESCRIPTION:** + +This function deletes the signal specified by ``signo`` from the specified +signal ``set``. + +**NOTES:** + +The set must be initialized using either ``sigemptyset`` or ``sigfillset`` +before using this function. + +.. _sigfillset: + +sigfillset - Fill a Signal Set +------------------------------ +.. index:: sigfillset +.. index:: fill a signal set + +**CALLING SEQUENCE:** + +.. code-block:: c + + #include + int sigfillset( + 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: + +.. list-table:: + :class: rtems-table + + * - ``EINVAL`` + - Invalid argument passed. + +**DESCRIPTION:** + +This function fills the specified signal ``set`` such that all signals are set. + +.. _sigismember: + +sigismember - Is Signal a Member of a Signal Set +------------------------------------------------ +.. index:: sigismember +.. index:: is signal a member of a signal set + +**CALLING SEQUENCE:** + +.. code-block:: c + + #include + int sigismember( + 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: + +.. 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. + +**NOTES:** + +The set must be initialized using either ``sigemptyset`` or ``sigfillset`` +before using this function. + +.. _sigemptyset: + +sigemptyset - Empty a Signal Set +-------------------------------- +.. index:: sigemptyset +.. index:: empty a signal set + +**CALLING SEQUENCE:** + +.. code-block:: c + + #include + int sigemptyset( + 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: + +.. 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 +.. index:: examine and change signal action + +**CALLING SEQUENCE:** + +.. code-block:: c + + #include + int sigaction( + 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: + +.. list-table:: + :class: rtems-table + + * - ``EINVAL`` + - Invalid argument passed. + * - ``ENOTSUP`` + - Realtime Signals Extension option not supported. + +**DESCRIPTION:** + +If the argument act is not a null pointer, it points to a structure specifying +the action to be associated with the specified signal. If the argument oact is +not a null pointer, the action previously associated with the signal is stored +in the location pointed to by the argument oact. If the argument act is a null +pointer, signal handling is unchanged; thus, the call can be used to enquire +about the current handling of a given signal. + +The structure ``sigaction`` has the following members: + +.. 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: + +.. 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-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 */ + } + +**NOTES:** + +The signal number cannot be SIGKILL. + +.. _pthread_kill: + +pthread_kill - Send a Signal to a Thread +---------------------------------------- +.. index:: pthread_kill +.. index:: send a signal to a thread + +**CALLING SEQUENCE:** + +.. code-block:: c + + #include + int pthread_kill( + 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: + +.. list-table:: + :class: rtems-table + + * - ``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``. + +If the signal code is ``0``, arguments are validated and no signal is sent. + +.. _sigprocmask: + +sigprocmask - Examine and Change Process Blocked Signals +-------------------------------------------------------- +.. index:: sigprocmask +.. index:: examine and change process blocked signals + +**CALLING SEQUENCE:** + +.. code-block:: c + + #include + int sigprocmask( + 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: + +.. list-table:: + :class: rtems-table + + * - ``EINVAL`` + - Invalid argument passed. + +**DESCRIPTION:** + +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: + +.. list-table:: + :class: rtems-table + + * - ``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. + +**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()``. + +.. _pthread_sigmask: + +pthread_sigmask - Examine and Change Thread Blocked Signals +----------------------------------------------------------- +.. index:: pthread_sigmask +.. index:: examine and change thread blocked signals + +**CALLING SEQUENCE:** + +.. code-block:: c + + #include + int pthread_sigmask( + 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: + +*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: + +.. list-table:: + :class: rtems-table + + * - ``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. + +**NOTES:** + +It is not an error to unblock a signal which is not blocked. + +.. _kill: + +kill - Send a Signal to a Process +--------------------------------- +.. index:: kill +.. index:: send a signal to a process + +**CALLING SEQUENCE:** + +.. code-block:: c + + #include + #include + int kill( + 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: + +.. list-table:: + :class: rtems-table + + * - ``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:** + +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). + +.. _sigpending: + +sigpending - Examine Pending Signals +------------------------------------ +.. index:: sigpending +.. index:: examine pending signals + +**CALLING SEQUENCE:** + +.. code-block:: c + + #include + 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: + +.. list-table:: + :class: rtems-table + + * - ``EFAULT`` + - Invalid address for set. + +**DESCRIPTION:** + +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 +.. index:: wait for a signal + +**CALLING SEQUENCE:** + +.. code-block:: c + + #include + 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: + +.. 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. + +.. _pause: + +pause - Suspend Process Execution +--------------------------------- +.. index:: pause +.. index:: suspend process execution + +**CALLING SEQUENCE:** + +.. code-block:: c + + #include + 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: + +.. 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. + +.. _sigwait: + +sigwait - Synchronously Accept a Signal +--------------------------------------- +.. index:: sigwait +.. index:: synchronously accept a signal + +**CALLING SEQUENCE:** + +.. code-block:: c + + #include + int sigwait( + 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: + +.. list-table:: + :class: rtems-table + + * - ``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``. + +.. _sigwaitinfo: + +sigwaitinfo - Synchronously Accept a Signal +------------------------------------------- +.. index:: sigwaitinfo +.. index:: synchronously accept a signal + +**CALLING SEQUENCE:** + +.. code-block:: c + + #include + int sigwaitinfo( + 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: + +*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 prototype of the ``siginfo_t`` structure is the following: + +.. 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 */ + } + +.. _sigtimedwait: + +sigtimedwait - Synchronously Accept a Signal with Timeout +--------------------------------------------------------- +.. index:: sigtimedwait +.. index:: synchronously accept a signal with timeout + +**CALLING SEQUENCE:** + +.. code-block:: c + + #include + int sigtimedwait( + 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: + +.. list-table:: + :class: rtems-table + + * - ``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. + +The ``timespec`` structure is defined as follows: + +.. code-block:: c + + struct timespec + { + 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. + +.. _sigqueue: + +sigqueue - Queue a Signal to a Process +-------------------------------------- +.. index:: sigqueue +.. index:: queue a signal to a process + +**CALLING SEQUENCE:** + +.. code-block:: c + + #include + int sigqueue( + 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: + +.. 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`` + +The ``sigval`` union is specified as: + +.. code-block:: c + + union sigval + { + 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). + +.. _alarm: + +alarm - Schedule Alarm +---------------------- +.. index:: alarm +.. index:: schedule alarm + +**CALLING SEQUENCE:** + +.. code-block:: c + + #include + unsigned int alarm( + 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. + +**DESCRIPTION:** + +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. + +If the notification signal, ``SIGALRM``, is not caught or ignored, the calling +process is terminated. + +.. _ualarm: + +ualarm - Schedule Alarm in Microseconds +--------------------------------------- +.. index:: alarm +.. index:: microseonds alarm +.. index:: usecs alarm +.. index:: schedule alarm in microseonds + +**CALLING SEQUENCE:** + +.. code-block:: c + + #include + useconds_t ualarm( + 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. + +**DESCRIPTION:** + +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``. + +**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. diff --git a/posix-users/status_of_implementation.rst b/posix-users/status_of_implementation.rst new file mode 100644 index 0000000..cc234fc --- /dev/null +++ b/posix-users/status_of_implementation.rst @@ -0,0 +1,46 @@ +.. comment SPDX-License-Identifier: CC-BY-SA-4.0 + +Status of Implementation +######################## + +This chapter provides an overview of the status of the implementation +of the POSIX API for RTEMS. The *POSIX 1003.1b Compliance Guide* +provides more detailed information regarding the implementation of +each of the numerous functions, constants, and macros specified by +the POSIX 1003.1b standard. + +RTEMS supports many of the process and user/group oriented services +in a "single user/single process" manner. This means that although +these services may be of limited usefulness or functionality, they +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. + - The ``flockfile()`` family is not implemented + - 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 + + - Many of the service description pages are not complete in this + manual. These need to be completed and information added to the + 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 new file mode 100644 index 0000000..871cca8 --- /dev/null +++ b/posix-users/system_database.rst @@ -0,0 +1,256 @@ +.. comment SPDX-License-Identifier: CC-BY-SA-4.0 + +.. COMMENT: COPYRIGHT(c) 1988-2002. +.. COMMENT: On-Line Applications Research Corporation(OAR). +.. COMMENT: All rights reserved. + +System Databases Manager +######################## + +Introduction +============ + +The system databases manager is ... + +The directives provided by the system databases manager are: + +- getgrgid_ - Get Group File Entry for ID + +- getgrgid_r_ - Reentrant Get Group File Entry + +- getgrnam_ - Get Group File Entry for Name + +- getgrnam_r_ - Reentrant Get Group File Entry for Name + +- getpwuid_ - Get Password File Entry for UID + +- getpwuid_r_ - Reentrant Get Password File Entry for UID + +- getpwnam_ - Get Password File Entry for Name + +- getpwnam_r_ - Reentrant Get Password File Entry for Name + +Background +========== + +There is currently no text in this section. + +Operations +========== + +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. + +.. _getgrgid: + +getgrgid - Get Group File Entry for ID +-------------------------------------- +.. index:: getgrgid +.. index:: get group file entry for id + +**CALLING SEQUENCE:** + +.. code-block:: c + + int getgrgid( + ); + +**STATUS CODES:** + +.. list-table:: + :class: rtems-table + + * - ``E`` + - The + +**DESCRIPTION:** + +**NOTES:** + +.. _getgrgid_r: + +getgrgid_r - Reentrant Get Group File Entry +------------------------------------------- +.. index:: getgrgid_r +.. index:: reentrant get group file entry + +**CALLING SEQUENCE:** + +.. code-block:: c + + int getgrgid_r( + ); + +**STATUS CODES:** + +.. list-table:: + :class: rtems-table + + * - ``E`` + - The + +**DESCRIPTION:** + +**NOTES:** + +.. _getgrnam: + +getgrnam - Get Group File Entry for Name +---------------------------------------- +.. index:: getgrnam +.. index:: get group file entry for name + +**CALLING SEQUENCE:** + +.. code-block:: c + + int getgrnam( + ); + +**STATUS CODES:** + +.. list-table:: + :class: rtems-table + + * - ``E`` + - The + +**DESCRIPTION:** + +**NOTES:** + +.. _getgrnam_r: + +getgrnam_r - Reentrant Get Group File Entry for Name +---------------------------------------------------- +.. index:: getgrnam_r +.. index:: reentrant get group file entry for name + +**CALLING SEQUENCE:** + +.. code-block:: c + + int getgrnam_r( + ); + +**STATUS CODES:** + +.. list-table:: + :class: rtems-table + + * - ``E`` + - The + +**DESCRIPTION:** + +**NOTES:** + +.. _getpwuid: + +getpwuid - Get Password File Entry for UID +------------------------------------------ +.. index:: getpwuid +.. index:: get password file entry for uid + +**CALLING SEQUENCE:** + +.. code-block:: c + + int getpwuid( + ); + +**STATUS CODES:** + +.. list-table:: + :class: rtems-table + + * - ``E`` + - The + +**DESCRIPTION:** + +**NOTES:** + +.. _getpwuid_r: + +getpwuid_r - Reentrant Get Password File Entry for UID +------------------------------------------------------ +.. index:: getpwuid_r +.. index:: reentrant get password file entry for uid + +**CALLING SEQUENCE:** + +.. code-block:: c + + int getpwuid_r( + ); + +**STATUS CODES:** + +.. list-table:: + :class: rtems-table + + * - ``E`` + - The + +**DESCRIPTION:** + +**NOTES:** + +.. _getpwnam: + +getpwnam - Password File Entry for Name +--------------------------------------- +.. index:: getpwnam +.. index:: password file entry for name + +**CALLING SEQUENCE:** + +.. code-block:: c + + int getpwnam( + ); + +**STATUS CODES:** + +.. list-table:: + :class: rtems-table + + * - ``E`` + - The + +**DESCRIPTION:** + +**NOTES:** + +.. _getpwnam_r: + +getpwnam_r - Reentrant Get Password File Entry for Name +------------------------------------------------------- +.. index:: getpwnam_r +.. index:: reentrant get password file entry for name + +**CALLING SEQUENCE:** + +.. code-block:: c + + int getpwnam_r( + ); + +**STATUS CODES:** + +.. list-table:: + :class: rtems-table + + * - ``E`` + - The + +**DESCRIPTION:** + +**NOTES:** diff --git a/posix-users/thread.rst b/posix-users/thread.rst new file mode 100644 index 0000000..e5f47c5 --- /dev/null +++ b/posix-users/thread.rst @@ -0,0 +1,1425 @@ +.. comment SPDX-License-Identifier: CC-BY-SA-4.0 + +.. COMMENT: COPYRIGHT (c) 1988-2002. +.. COMMENT: On-Line Applications Research Corporation (OAR). +.. COMMENT: All rights reserved. + +Thread Manager +############## + +Introduction +============ + +The thread manager implements the functionality required of the thread manager +as defined by POSIX 1003.1b. This standard requires that a compliant operating +system provide the facilties to manage multiple threads of control and defines +the API that must be provided. + +The services provided by the thread manager are: + +- pthread_attr_init_ - Initialize a Thread Attribute Set + +- pthread_attr_destroy_ - Destroy a Thread Attribute Set + +- pthread_attr_setdetachstate_ - Set Detach State + +- pthread_attr_getdetachstate_ - Get Detach State + +- pthread_attr_setstacksize_ - Set Thread Stack Size + +- pthread_attr_getstacksize_ - Get Thread Stack Size + +- pthread_attr_setstackaddr_ - Set Thread Stack Address + +- pthread_attr_getstackaddr_ - Get Thread Stack Address + +- pthread_attr_setscope_ - Set Thread Scheduling Scope + +- pthread_attr_getscope_ - Get Thread Scheduling Scope + +- pthread_attr_setinheritsched_ - Set Inherit Scheduler Flag + +- pthread_attr_getinheritsched_ - Get Inherit Scheduler Flag + +- pthread_attr_setschedpolicy_ - Set Scheduling Policy + +- pthread_attr_getschedpolicy_ - Get Scheduling Policy + +- pthread_attr_setschedparam_ - Set Scheduling Parameters + +- pthread_attr_getschedparam_ - Get Scheduling Parameters + +- pthread_attr_getaffinity_np_ - Get Thread Affinity Attribute + +- pthread_attr_setaffinity_np_ - Set Thread Affinity Attribute + +- pthread_create_ - Create a Thread + +- pthread_exit_ - Terminate the Current Thread + +- pthread_detach_ - Detach a Thread + +- pthread_getattr_np_ - Get Thread Attributes + +- pthread_join_ - Wait for Thread Termination + +- pthread_self_ - Get Thread ID + +- pthread_equal_ - Compare Thread IDs + +- pthread_once_ - Dynamic Package Initialization + +- pthread_setschedparam_ - Set Thread Scheduling Parameters + +- pthread_getschedparam_ - Get Thread Scheduling Parameters + +- pthread_getaffinity_np_ - Get Thread Affinity + +- pthread_setaffinity_np_ - Set Thread Affinity + +Background +========== + +Thread Attributes +----------------- + +Thread attributes are utilized only at thread creation time. A thread attribute +structure may be initialized and passed as an argument to the +``pthread_create`` routine. + +*stack address* + is the address of the optionally user specified stack area for this thread. + If this value is NULL, then RTEMS allocates the memory for the thread stack + from the RTEMS Workspace Area. Otherwise, this is the user specified + address for the memory to be used for the thread's stack. Each thread must + have a distinct stack area. Each processor family has different alignment + rules which should be followed. + +*stack size* + is the minimum desired size for this thread's stack area. If the size of + this area as specified by the stack size attribute is smaller than the + minimum for this processor family and the stack is not user specified, then + RTEMS will automatically allocate a stack of the minimum size for this + processor family. + +*contention scope* + specifies the scheduling contention scope. RTEMS only supports the + PTHREAD_SCOPE_PROCESS scheduling contention scope. + +*scheduling inheritance* + specifies whether a user specified or the scheduling policy and parameters + of the currently executing thread are to be used. When this is + PTHREAD_INHERIT_SCHED, then the scheduling policy and parameters of the + currently executing thread are inherited by the newly created thread. + +*scheduling policy and parameters* + specify the manner in which the thread will contend for the processor. The + scheduling parameters are interpreted based on the specified policy. All + policies utilize the thread priority parameter. + +Operations +========== + +There is currently no text in this section. + +Services +======== + +This section details the thread manager's services. A subsection is dedicated +to each of this manager's services and describes the calling sequence, related +constants, usage, and status codes. + +.. _pthread_attr_init: + +pthread_attr_init - Initialize a Thread Attribute Set +----------------------------------------------------- +.. index:: pthread_attr_init +.. index:: initialize a thread attribute set + +**CALLING SEQUENCE:** + +.. code-block:: c + + #include + int pthread_attr_init( + pthread_attr_t *attr + ); + +**STATUS CODES:** + +.. list-table:: + :class: rtems-table + + * - ``EINVAL`` + - The attribute pointer argument is invalid. + +**DESCRIPTION:** + +The ``pthread_attr_init`` routine initializes the thread attributes object +specified by ``attr`` with the default value for all of the individual +attributes. + +**NOTES:** + +The settings in the default attributes are implementation defined. For RTEMS, +the default attributes are as follows: + +.. list-table:: + :class: rtems-table + + * - *stackadr* + - is not set to indicate that RTEMS is to allocate the stack memory. + * - *stacksize* + - is set to ``PTHREAD_MINIMUM_STACK_SIZE``. + * - *contentionscope* + - is set to ``PTHREAD_SCOPE_PROCESS``. + * - *inheritsched* + - is set to ``PTHREAD_INHERIT_SCHED`` to indicate that the created thread + inherits its scheduling attributes from its parent. + * - detachstate + - is set to ``PTHREAD_CREATE_JOINABLE``. + +.. _pthread_attr_destroy: + +pthread_attr_destroy - Destroy a Thread Attribute Set +----------------------------------------------------- +.. index:: pthread_attr_destroy +.. index:: destroy a thread attribute set + +**CALLING SEQUENCE:** + +.. code-block:: c + + #include + int pthread_attr_destroy( + pthread_attr_t *attr + ); + +**STATUS CODES:** + +.. list-table:: + :class: rtems-table + + * - ``EINVAL`` + - The attribute pointer argument is invalid. + * - ``EINVAL`` + - The attribute set is not initialized. + +**DESCRIPTION:** + +The ``pthread_attr_destroy`` routine is used to destroy a thread attributes +object. The behavior of using an attributes object after it is destroyed is +implementation dependent. + +**NOTES:** + +NONE + +.. _pthread_attr_setdetachstate: + +pthread_attr_setdetachstate - Set Detach State +---------------------------------------------- +.. index:: pthread_attr_setdetachstate +.. index:: set detach state + +**CALLING SEQUENCE:** + +.. code-block:: c + + #include + int pthread_attr_setdetachstate( + pthread_attr_t *attr, + int detachstate + ); + +**STATUS CODES:** + +.. list-table:: + :class: rtems-table + + * - ``EINVAL`` + - The attribute pointer argument is invalid. + * - ``EINVAL`` + - The attribute set is not initialized. + * - ``EINVAL`` + - The detachstate argument is invalid. + +**DESCRIPTION:** + +The ``pthread_attr_setdetachstate`` routine is used to value of the +``detachstate`` attribute. This attribute controls whether the thread is +created in a detached state. + +The ``detachstate`` can be either ``PTHREAD_CREATE_DETACHED`` or +``PTHREAD_CREATE_JOINABLE``. The default value for all threads is +``PTHREAD_CREATE_JOINABLE``. + +**NOTES:** + +If a thread is in a detached state, then the use of the ID with the +``pthread_detach`` or ``pthread_join`` routines is an error. + +.. _pthread_attr_getdetachstate: + +pthread_attr_getdetachstate - Get Detach State +---------------------------------------------- +.. index:: pthread_attr_getdetachstate +.. index:: get detach state + +**CALLING SEQUENCE:** + +.. code-block:: c + + #include + int pthread_attr_getdetachstate( + const pthread_attr_t *attr, + int *detachstate + ); + +**STATUS CODES:** + +.. list-table:: + :class: rtems-table + + * - ``EINVAL`` + - The attribute pointer argument is invalid. + * - ``EINVAL`` + - The attribute set is not initialized. + * - ``EINVAL`` + - The detatchstate pointer argument is invalid. + +**DESCRIPTION:** + +The ``pthread_attr_getdetachstate`` routine is used to obtain the current value +of the ``detachstate`` attribute as specified by the ``attr`` thread attribute +object. + +**NOTES:** + +NONE + +.. _pthread_attr_setstacksize: + +pthread_attr_setstacksize - Set Thread Stack Size +------------------------------------------------- +.. index:: pthread_attr_setstacksize +.. index:: set thread stack size + +**CALLING SEQUENCE:** + +.. code-block:: c + + #include + int pthread_attr_setstacksize( + pthread_attr_t *attr, + size_t stacksize + ); + +**STATUS CODES:** + +.. list-table:: + :class: rtems-table + + * - ``EINVAL`` + - The attribute pointer argument is invalid. + * - ``EINVAL`` + - The attribute set is not initialized. + +**DESCRIPTION:** + +The ``pthread_attr_setstacksize`` routine is used to set the ``stacksize`` +attribute in the ``attr`` thread attribute object. + +**NOTES:** + +As required by POSIX, RTEMS defines the feature symbol +``_POSIX_THREAD_ATTR_STACKSIZE`` to indicate that this routine is supported. + +If the specified stacksize is below the minimum required for this CPU +(``PTHREAD_STACK_MIN``, then the stacksize will be set to the minimum for this +CPU. + +.. _pthread_attr_getstacksize: + +pthread_attr_getstacksize - Get Thread Stack Size +------------------------------------------------- +.. index:: pthread_attr_getstacksize +.. index:: get thread stack size + +**CALLING SEQUENCE:** + +.. code-block:: c + + #include + int pthread_attr_getstacksize( + const pthread_attr_t *attr, + size_t *stacksize + ); + +**STATUS CODES:** + +.. list-table:: + :class: rtems-table + + * - ``EINVAL`` + - The attribute pointer argument is invalid. + * - ``EINVAL`` + - The attribute set is not initialized. + * - ``EINVAL`` + - The stacksize pointer argument is invalid. + +**DESCRIPTION:** + +The ``pthread_attr_getstacksize`` routine is used to obtain the ``stacksize`` +attribute in the ``attr`` thread attribute object. + +**NOTES:** + +As required by POSIX, RTEMS defines the feature symbol +``_POSIX_THREAD_ATTR_STACKSIZE`` to indicate that this routine is supported. + +.. _pthread_attr_setstackaddr: + +pthread_attr_setstackaddr - Set Thread Stack Address +---------------------------------------------------- +.. index:: pthread_attr_setstackaddr +.. index:: set thread stack address + +**CALLING SEQUENCE:** + +.. code-block:: c + + #include + int pthread_attr_setstackaddr( + pthread_attr_t *attr, + void *stackaddr + ); + +**STATUS CODES:** + +.. list-table:: + :class: rtems-table + + * - ``EINVAL`` + - The attribute pointer argument is invalid. + * - ``EINVAL`` + - The attribute set is not initialized. + +**DESCRIPTION:** + +The ``pthread_attr_setstackaddr`` routine is used to set the ``stackaddr`` +attribute in the ``attr`` thread attribute object. + +**NOTES:** + +As required by POSIX, RTEMS defines the feature symbol +``_POSIX_THREAD_ATTR_STACKADDR`` to indicate that this routine is supported. + +It is imperative to the proper operation of the system that each thread have +sufficient stack space. + +.. _pthread_attr_getstackaddr: + +pthread_attr_getstackaddr - Get Thread Stack Address +---------------------------------------------------- +.. index:: pthread_attr_getstackaddr +.. index:: get thread stack address + +**CALLING SEQUENCE:** + +.. code-block:: c + + #include + int pthread_attr_getstackaddr( + const pthread_attr_t *attr, + void **stackaddr + ); + +**STATUS CODES:** + +.. list-table:: + :class: rtems-table + + * - ``EINVAL`` + - The attribute pointer argument is invalid. + * - ``EINVAL`` + - The attribute set is not initialized. + * - ``EINVAL`` + - The stackaddr pointer argument is invalid. + +**DESCRIPTION:** + +The ``pthread_attr_getstackaddr`` routine is used to obtain the ``stackaddr`` +attribute in the ``attr`` thread attribute object. + +**NOTES:** + +As required by POSIX, RTEMS defines the feature symbol +``_POSIX_THREAD_ATTR_STACKADDR`` to indicate that this routine is supported. + +.. _pthread_attr_setscope: + +pthread_attr_setscope - Set Thread Scheduling Scope +--------------------------------------------------- +.. index:: pthread_attr_setscope +.. index:: set thread scheduling scope + +**CALLING SEQUENCE:** + +.. code-block:: c + + #include + int pthread_attr_setscope( + pthread_attr_t *attr, + int contentionscope + ); + +**STATUS CODES:** + +.. list-table:: + :class: rtems-table + + * - ``EINVAL`` + - The attribute pointer argument is invalid. + * - ``EINVAL`` + - The attribute set is not initialized. + * - ``EINVAL`` + - The contention scope specified is not valid. + * - ``ENOTSUP`` + - The contention scope specified (``PTHREAD_SCOPE_SYSTEM``) is not supported. + +**DESCRIPTION:** + +The ``pthread_attr_setscope`` routine is used to set the contention scope field +in the thread attribute object ``attr`` to the value specified by +``contentionscope``. + +The ``contentionscope`` must be either ``PTHREAD_SCOPE_SYSTEM`` to indicate +that the thread is to be within system scheduling contention or +``PTHREAD_SCOPE_PROCESS`` indicating that the thread is to be within the +process scheduling contention scope. + +**NOTES:** + +As required by POSIX, RTEMS defines the feature symbol +``_POSIX_THREAD_PRIORITY_SCHEDULING`` to indicate that the family of routines +to which this routine belongs is supported. + +.. _pthread_attr_getscope: + +pthread_attr_getscope - Get Thread Scheduling Scope +--------------------------------------------------- +.. index:: pthread_attr_getscope +.. index:: get thread scheduling scope + +**CALLING SEQUENCE:** + +.. code-block:: c + + #include + int pthread_attr_getscope( + const pthread_attr_t *attr, + int *contentionscope + ); + +**STATUS CODES:** + +.. list-table:: + :class: rtems-table + + * - ``EINVAL`` + - The attribute pointer argument is invalid. + * - ``EINVAL`` + - The attribute set is not initialized. + * - ``EINVAL`` + - The contentionscope pointer argument is invalid. + +**DESCRIPTION:** + +The ``pthread_attr_getscope`` routine is used to obtain the value of the +contention scope field in the thread attributes object ``attr``. The current +value is returned in ``contentionscope``. + +**NOTES:** + +As required by POSIX, RTEMS defines the feature symbol +``_POSIX_THREAD_PRIORITY_SCHEDULING`` to indicate that the family of routines +to which this routine belongs is supported. + +.. _pthread_attr_setinheritsched: + +pthread_attr_setinheritsched - Set Inherit Scheduler Flag +--------------------------------------------------------- +.. index:: pthread_attr_setinheritsched +.. index:: set inherit scheduler flag + +**CALLING SEQUENCE:** + +.. code-block:: c + + #include + int pthread_attr_setinheritsched( + pthread_attr_t *attr, + int inheritsched + ); + +**STATUS CODES:** + +.. list-table:: + :class: rtems-table + + * - ``EINVAL`` + - The attribute pointer argument is invalid. + * - ``EINVAL`` + - The attribute set is not initialized. + * - ``EINVAL`` + - The specified scheduler inheritance argument is invalid. + +**DESCRIPTION:** + +The ``pthread_attr_setinheritsched`` routine is used to set the inherit +scheduler field in the thread attribute object ``attr`` to the value specified +by ``inheritsched``. + +The ``contentionscope`` must be either ``PTHREAD_INHERIT_SCHED`` to indicate +that the thread is to inherit the scheduling policy and parameters fromthe +creating thread, or ``PTHREAD_EXPLICIT_SCHED`` to indicate that the scheduling +policy and parameters for this thread are to be set from the corresponding +values in the attributes object. If ``contentionscope`` is +``PTHREAD_INHERIT_SCHED``, then the scheduling attributes in the ``attr`` +structure will be ignored at thread creation time. + +**NOTES:** + +As required by POSIX, RTEMS defines the feature symbol +``_POSIX_THREAD_PRIORITY_SCHEDULING`` to indicate that the family of routines +to which this routine belongs is supported. + +.. _pthread_attr_getinheritsched: + +pthread_attr_getinheritsched - Get Inherit Scheduler Flag +--------------------------------------------------------- +.. index:: pthread_attr_getinheritsched +.. index:: get inherit scheduler flag + +**CALLING SEQUENCE:** + +.. code-block:: c + + #include + int pthread_attr_getinheritsched( + const pthread_attr_t *attr, + int *inheritsched + ); + +**STATUS CODES:** + +.. list-table:: + :class: rtems-table + + * - ``EINVAL`` + - The attribute pointer argument is invalid. + * - ``EINVAL`` + - The attribute set is not initialized. + * - ``EINVAL`` + - The inheritsched pointer argument is invalid. + +**DESCRIPTION:** + +The ``pthread_attr_getinheritsched`` routine is used to object the current +value of the inherit scheduler field in the thread attribute object ``attr``. + +**NOTES:** + +As required by POSIX, RTEMS defines the feature symbol +``_POSIX_THREAD_PRIORITY_SCHEDULING`` to indicate that the family of routines +to which this routine belongs is supported. + +.. _pthread_attr_setschedpolicy: + +pthread_attr_setschedpolicy - Set Scheduling Policy +--------------------------------------------------- +.. index:: pthread_attr_setschedpolicy +.. index:: set scheduling policy + +**CALLING SEQUENCE:** + +.. code-block:: c + + #include + int pthread_attr_setschedpolicy( + pthread_attr_t *attr, + int policy + ); + +**STATUS CODES:** + +.. list-table:: + :class: rtems-table + + * - ``EINVAL`` + - The attribute pointer argument is invalid. + * - ``EINVAL`` + - The attribute set is not initialized. + * - ``ENOTSUP`` + - The specified scheduler policy argument is invalid. + +**DESCRIPTION:** + +The ``pthread_attr_setschedpolicy`` routine is used to set the scheduler policy +field in the thread attribute object ``attr`` to the value specified by +``policy``. + +Scheduling policies may be one of the following: + +- ``SCHED_DEFAULT`` + +- ``SCHED_FIFO`` + +- ``SCHED_RR`` + +- ``SCHED_SPORADIC`` + +- ``SCHED_OTHER`` + +The precise meaning of each of these is discussed elsewhere in this manual. + +**NOTES:** + +As required by POSIX, RTEMS defines the feature symbol +``_POSIX_THREAD_PRIORITY_SCHEDULING`` to indicate that the family of routines +to which this routine belongs is supported. + +.. _pthread_attr_getschedpolicy: + +pthread_attr_getschedpolicy - Get Scheduling Policy +--------------------------------------------------- +.. index:: pthread_attr_getschedpolicy +.. index:: get scheduling policy + +**CALLING SEQUENCE:** + +.. code-block:: c + + #include + int pthread_attr_getschedpolicy( + const pthread_attr_t *attr, + int *policy + ); + +**STATUS CODES:** + +.. list-table:: + :class: rtems-table + + * - ``EINVAL`` + - The attribute pointer argument is invalid. + * - ``EINVAL`` + - The attribute set is not initialized. + * - ``EINVAL`` + - The specified scheduler policy argument pointer is invalid. + +**DESCRIPTION:** + +The ``pthread_attr_getschedpolicy`` routine is used to obtain the scheduler +policy field from the thread attribute object ``attr``. The value of this +field is returned in ``policy``. + +**NOTES:** + +As required by POSIX, RTEMS defines the feature symbol +``_POSIX_THREAD_PRIORITY_SCHEDULING`` to indicate that the family of routines +to which this routine belongs is supported. + +.. _pthread_attr_setschedparam: + +pthread_attr_setschedparam - Set Scheduling Parameters +------------------------------------------------------ +.. index:: pthread_attr_setschedparam +.. index:: set scheduling parameters + +**CALLING SEQUENCE:** + +.. code-block:: c + + #include + int pthread_attr_setschedparam( + pthread_attr_t *attr, + const struct sched_param param + ); + +**STATUS CODES:** + +.. list-table:: + :class: rtems-table + + * - ``EINVAL`` + - The attribute pointer argument is invalid. + * - ``EINVAL`` + - The attribute set is not initialized. + * - ``EINVAL`` + - The specified scheduler parameter argument is invalid. + +**DESCRIPTION:** + +The ``pthread_attr_setschedparam`` routine is used to set the scheduler +parameters field in the thread attribute object ``attr`` to the value specified +by ``param``. + +**NOTES:** + +As required by POSIX, RTEMS defines the feature symbol +``_POSIX_THREAD_PRIORITY_SCHEDULING`` to indicate that the family of routines +to which this routine belongs is supported. + +.. _pthread_attr_getschedparam: + +pthread_attr_getschedparam - Get Scheduling Parameters +------------------------------------------------------ +.. index:: pthread_attr_getschedparam +.. index:: get scheduling parameters + +**CALLING SEQUENCE:** + +.. code-block:: c + + #include + int pthread_attr_getschedparam( + const pthread_attr_t *attr, + struct sched_param *param + ); + +**STATUS CODES:** + +.. list-table:: + :class: rtems-table + + * - ``EINVAL`` + - The attribute pointer argument is invalid. + * - ``EINVAL`` + - The attribute set is not initialized. + * - ``EINVAL`` + - The specified scheduler parameter argument pointer is invalid. + +**DESCRIPTION:** + +The ``pthread_attr_getschedparam`` routine is used to obtain the scheduler +parameters field from the thread attribute object ``attr``. The value of this +field is returned in ``param``. + +**NOTES:** + +As required by POSIX, RTEMS defines the feature symbol +``_POSIX_THREAD_PRIORITY_SCHEDULING`` to indicate that the family of routines +to which this routine belongs is supported. + +.. _pthread_attr_getaffinity_np: + +pthread_attr_getaffinity_np - Get Thread Affinity Attribute +----------------------------------------------------------- + +**CALLING SEQUENCE:** + +.. code-block:: c + + #define _GNU_SOURCE + #include + int pthread_attr_getaffinity_np( + const pthread_attr_t *attr, + size_t cpusetsize, + cpu_set_t *cpuset + ); + +**STATUS CODES:** + +.. list-table:: + :class: rtems-table + + * - ``EFAULT`` + - The attribute pointer argument is invalid. + * - ``EFAULT`` + - The cpuset pointer argument is invalid. + * - ``EINVAL`` + - The ``cpusetsize`` does not match the value of ``affinitysetsize`` field + in the thread attribute object. + +**DESCRIPTION:** + +The ``pthread_attr_getaffinity_np`` routine is used to obtain the +``affinityset`` field from the thread attribute object ``attr``. The value of +this field is returned in ``cpuset``. + +**NOTES:** + +NONE + +.. _pthread_attr_setaffinity_np: + +pthread_attr_setaffinity_np - Set Thread Affinity Attribute +----------------------------------------------------------- + +**CALLING SEQUENCE:** + +.. code-block:: c + + #define _GNU_SOURCE + #include + int pthread_attr_setaffinity_np( + pthread_attr_t *attr, + size_t cpusetsize, + const cpu_set_t *cpuset + ); + +**STATUS CODES:** + +.. list-table:: + :class: rtems-table + + * - ``EFAULT`` + - The attribute pointer argument is invalid. + * - ``EFAULT`` + - The cpuset pointer argument is invalid. + * - ``EINVAL`` + - The ``cpusetsize`` does not match the value of ``affinitysetsize`` field + in the thread attribute object. + * - ``EINVAL`` + - The ``cpuset`` did not select a valid cpu. + * - ``EINVAL`` + - The ``cpuset`` selected a cpu that was invalid. + +**DESCRIPTION:** + +The ``pthread_attr_setaffinity_np`` routine is used to set the ``affinityset`` +field in the thread attribute object ``attr``. The value of this field is +returned in ``cpuset``. + +**NOTES:** + +NONE + +.. _pthread_create: + +pthread_create - Create a Thread +-------------------------------- +.. index:: pthread_create +.. index:: create a thread + +**CALLING SEQUENCE:** + +.. code-block:: c + + #include + int pthread_create( + pthread_t *thread, + const pthread_attr_t *attr, + void (*start_routine)( void *), + void *arg + ); + +**STATUS CODES:** + +.. list-table:: + :class: rtems-table + + * - ``EINVAL`` + - The attribute set is not initialized. + * - ``EINVAL`` + - The user specified a stack address and the size of the area was not large + enough to meet this processor's minimum stack requirements. + * - ``EINVAL`` + - The specified scheduler inheritance policy was invalid. + * - ``ENOTSUP`` + - The specified contention scope was ``PTHREAD_SCOPE_PROCESS``. + * - ``EINVAL`` + - The specified thread priority was invalid. + * - ``EINVAL`` + - The specified scheduling policy was invalid. + * - ``EINVAL`` + - The scheduling policy was ``SCHED_SPORADIC`` and the specified + replenishment period is less than the initial budget. + * - ``EINVAL`` + - The scheduling policy was ``SCHED_SPORADIC`` and the specified low + priority is invalid. + * - ``EAGAIN`` + - The system lacked the necessary resources to create another thread, or the + self imposed limit on the total number of threads in a process + ``PTHREAD_THREAD_MAX`` would be exceeded. + * - ``EINVAL`` + - Invalid argument passed. + +**DESCRIPTION:** + +The ``pthread_create`` routine is used to create a new thread with the +attributes specified by ``attr``. If the ``attr`` argument is ``NULL``, then +the default attribute set will be used. Modification of the contents of +``attr`` after this thread is created does not have an impact on this thread. + +The thread begins execution at the address specified by ``start_routine`` with +``arg`` as its only argument. If ``start_routine`` returns, then it is +functionally equivalent to the thread executing the ``pthread_exit`` service. + +Upon successful completion, the ID of the created thread is returned in the +``thread`` argument. + +**NOTES:** + +There is no concept of a single main thread in RTEMS as there is in a tradition +UNIX system. POSIX requires that the implicit return of the main thread results +in the same effects as if there were a call to ``exit``. This does not occur in +RTEMS. + +The signal mask of the newly created thread is inherited from its creator and +the set of pending signals for this thread is empty. + +.. _pthread_exit: + +pthread_exit - Terminate the Current Thread +------------------------------------------- +.. index:: pthread_exit +.. index:: terminate the current thread + +**CALLING SEQUENCE:** + +.. code-block:: c + + #include + void pthread_exit( + void *status + ); + +**STATUS CODES:** + +*NONE* + +**DESCRIPTION:** + +The ``pthread_exit`` routine is used to terminate the calling thread. The +``status`` is made available to any successful join with the terminating +thread. + +When a thread returns from its start routine, it results in an implicit call to +the ``pthread_exit`` routine with the return value of the function serving as +the argument to ``pthread_exit``. + +**NOTES:** + +Any cancellation cleanup handlers that hace been pushed and not yet popped +shall be popped in reverse of the order that they were pushed. After all +cancellation cleanup handlers have been executed, if the thread has any +thread-specific data, destructors for that data will be invoked. + +Thread termination does not release or free any application visible resources +including byt not limited to mutexes, file descriptors, allocated memory, +etc.. Similarly, exitting a thread does not result in any process-oriented +cleanup activity. + +There is no concept of a single main thread in RTEMS as there is in a tradition +UNIX system. POSIX requires that the implicit return of the main thread results +in the same effects as if there were a call to ``exit``. This does not occur in +RTEMS. + +All access to any automatic variables allocated by the threads is lost when the +thread exits. Thus references (i.e. pointers) to local variables of a thread +should not be used in a global manner without care. As a specific example, a +pointer to a local variable should NOT be used as the return value. + +.. _pthread_detach: + +pthread_detach - Detach a Thread +-------------------------------- +.. index:: pthread_detach +.. index:: detach a thread + +**CALLING SEQUENCE:** + +.. code-block:: c + + #include + int pthread_detach( + pthread_t thread + ); + +**STATUS CODES:** + +.. list-table:: + :class: rtems-table + + * - ``ESRCH`` + - The thread specified is invalid. + * - ``EINVAL`` + - The thread specified is not a joinable thread. + +**DESCRIPTION:** + +The ``pthread_detach`` routine is used to to indicate that storage for +``thread`` can be reclaimed when the thread terminates without another thread +joinging with it. + +**NOTES:** + +If any threads have previously joined with the specified thread, then they will +remain joined with that thread. Any subsequent calls to ``pthread_join`` on the +specified thread will fail. + +.. COMMENT: pthread_getattr_np + +.. _pthread_getattr_np: + +pthread_getattr_np - Get Thread Attributes +------------------------------------------ +.. index:: pthread_getattr_np +.. index:: get thread attributes + +**CALLING SEQUENCE:** + +.. code-block:: c + + #define _GNU_SOURCE + #include + int pthread_getattr_np( + pthread_t thread, + pthread_attr_t *attr + ); + +**STATUS CODES:** + +.. list-table:: + :class: rtems-table + + * - ``ESRCH`` + - The thread specified is invalid. + * - ``EINVAL`` + - The attribute pointer argument is invalid. + +**DESCRIPTION:** + +The ``pthread_getattr_np`` routine is used to obtain the attributes associated +with ``thread``. + +**NOTES:** + +Modification of the execution modes and priority through the Classic API may +result in a combination that is not representable in the POSIX API. + +.. _pthread_join: + +pthread_join - Wait for Thread Termination +------------------------------------------ +.. index:: pthread_join +.. index:: wait for thread termination + +**CALLING SEQUENCE:** + +.. code-block:: c + + #include + int pthread_join( + pthread_t thread, + void **value_ptr + ); + +**STATUS CODES:** + +.. list-table:: + :class: rtems-table + + * - ``ESRCH`` + - The thread specified is invalid. + * - ``EINVAL`` + - The thread specified is not a joinable thread. + * - ``EDEADLK`` + - A deadlock was detected or thread is the calling thread. + +**DESCRIPTION:** + +The ``pthread_join`` routine suspends execution of the calling thread until +``thread`` terminates. If ``thread`` has already terminated, then this routine +returns immediately. The value returned by ``thread`` (i.e. passed to +``pthread_exit`` is returned in ``value_ptr``. + +When this routine returns, then ``thread`` has been terminated. + +**NOTES:** + +The results of multiple simultaneous joins on the same thread is undefined. + +If any threads have previously joined with the specified thread, then they will +remain joined with that thread. Any subsequent calls to ``pthread_join`` on the +specified thread will fail. + +If value_ptr is NULL, then no value is returned. + +.. _pthread_self: + +pthread_self - Get Thread ID +---------------------------- +.. index:: pthread_self +.. index:: get thread id + +**CALLING SEQUENCE:** + +.. code-block:: c + + #include + pthread_t pthread_self( void ); + +**STATUS CODES:** + +The value returned is the ID of the calling thread. + +**DESCRIPTION:** + +This routine returns the ID of the calling thread. + +**NOTES:** + +NONE + +.. _pthread_equal: + +pthread_equal - Compare Thread IDs +---------------------------------- +.. index:: pthread_equal +.. index:: compare thread ids + +**CALLING SEQUENCE:** + +.. code-block:: c + + #include + int pthread_equal( + pthread_t t1, + pthread_t t2 + ); + +**STATUS CODES:** + +.. list-table:: + :class: rtems-table + + * - ``zero`` + - The thread ids are not equal. + * - ``non-zero`` + - The thread ids are equal. + +**DESCRIPTION:** + +The ``pthread_equal`` routine is used to compare two thread IDs and determine +if they are equal. + +**NOTES:** + +The behavior is undefined if the thread IDs are not valid. + +.. _pthread_once: + +pthread_once - Dynamic Package Initialization +--------------------------------------------- +.. index:: pthread_once +.. index:: dynamic package initialization + +**CALLING SEQUENCE:** + +.. code-block:: c + + #include + pthread_once_t once_control = PTHREAD_ONCE_INIT; + int pthread_once( + pthread_once_t *once_control, + void (*init_routine)(void) + ); + +**STATUS CODES:** + +NONE + +**DESCRIPTION:** + +The ``pthread_once`` routine is used to provide controlled initialization of +variables. The first call to ``pthread_once`` by any thread with the same +``once_control`` will result in the ``init_routine`` being invoked with no +arguments. Subsequent calls to ``pthread_once`` with the same ``once_control`` +will have no effect. + +The ``init_routine`` is guaranteed to have run to completion when this routine +returns to the caller. + +**NOTES:** + +The behavior of ``pthread_once`` is undefined if ``once_control`` is automatic +storage (i.e. on a task stack) or is not initialized using +``PTHREAD_ONCE_INIT``. + +.. _pthread_setschedparam: + +pthread_setschedparam - Set Thread Scheduling Parameters +-------------------------------------------------------- +.. index:: pthread_setschedparam +.. index:: set thread scheduling parameters + +**CALLING SEQUENCE:** + +.. code-block:: c + + #include + int pthread_setschedparam( + pthread_t thread, + int policy, + struct sched_param *param + ); + +**STATUS CODES:** + +.. list-table:: + :class: rtems-table + + * - ``EINVAL`` + - The scheduling parameters indicated by the parameter param is invalid. + * - ``EINVAL`` + - The value specified by policy is invalid. + * - ``EINVAL`` + - The scheduling policy was ``SCHED_SPORADIC`` and the specified + replenishment period is less than the initial budget. + * - ``EINVAL`` + - The scheduling policy was ``SCHED_SPORADIC`` and the specified low + priority is invalid. + * - ``ESRCH`` + - The thread indicated was invalid. + +**DESCRIPTION:** + +The ``pthread_setschedparam`` routine is used to set the scheduler parameters +currently associated with the thread specified by ``thread`` to the policy +specified by ``policy``. The contents of ``param`` are interpreted based upon +the ``policy`` argument. + +**NOTES:** + +As required by POSIX, RTEMS defines the feature symbol +``_POSIX_THREAD_PRIORITY_SCHEDULING`` to indicate that the family of routines +to which this routine belongs is supported. + +.. _pthread_getschedparam: + +pthread_getschedparam - Get Thread Scheduling Parameters +-------------------------------------------------------- +.. index:: pthread_getschedparam +.. index:: get thread scheduling parameters + +**CALLING SEQUENCE:** + +.. code-block:: c + + #include + int pthread_getschedparam( + pthread_t thread, + int *policy, + struct sched_param *param + ); + +**STATUS CODES:** + +.. list-table:: + :class: rtems-table + + * - ``EINVAL`` + - The policy pointer argument is invalid. + * - ``EINVAL`` + - The scheduling parameters pointer argument is invalid. + * - ``ESRCH`` + - The thread indicated by the parameter thread is invalid. + +**DESCRIPTION:** + +The ``pthread_getschedparam`` routine is used to obtain the scheduler policy +and parameters associated with ``thread``. The current policy and associated +parameters values returned in``policy`` and ``param``, respectively. + +**NOTES:** + +As required by POSIX, RTEMS defines the feature symbol +``_POSIX_THREAD_PRIORITY_SCHEDULING`` to indicate that the family of routines +to which this routine belongs is supported. + +.. COMMENT: pthread_getaffinity_np + +.. _pthread_getaffinity_np: + +pthread_getaffinity_np - Get Thread Affinity +-------------------------------------------- + +**CALLING SEQUENCE:** + +.. code-block:: c + + #define _GNU_SOURCE + #include + int pthread_getaffinity_np( + const pthread_t id, + size_t cpusetsize, + cpu_set_t *cpuset + ); + +**STATUS CODES:** + +.. list-table:: + :class: rtems-table + + * - ``EFAULT`` + - The cpuset pointer argument is invalid. + * - ``EINVAL`` + - The ``cpusetsize`` does not match the value of ``affinitysetsize`` field + in the thread attribute object. + +**DESCRIPTION:** + +The ``pthread_getaffinity_np`` routine is used to obtain the ``affinity.set`` +field from the thread control object associated with the ``id``. The value of +this field is returned in ``cpuset``. + +**NOTES:** + +NONE + +.. COMMENT: pthread_setaffinity_np + +.. _pthread_setaffinity_np: + +pthread_setaffinity_np - Set Thread Affinity +-------------------------------------------- + +**CALLING SEQUENCE:** + +.. code-block:: c + + #define _GNU_SOURCE + #include + int pthread_setaffinity_np( + pthread_t id, + size_t cpusetsize, + const cpu_set_t *cpuset + ); + +**STATUS CODES:** + +.. list-table:: + :class: rtems-table + + * - ``EFAULT`` + - The cpuset pointer argument is invalid. + * - ``EINVAL`` + - The ``cpusetsize`` does not match the value of ``affinitysetsize`` field + in the thread attribute object. + * - ``EINVAL`` + - The ``cpuset`` did not select a valid cpu. + * - ``EINVAL`` + - The ``cpuset`` selected a cpu that was invalid. + +**DESCRIPTION:** + +The ``pthread_setaffinity_np`` routine is used to set the ``affinityset`` field +of the thread object ``id``. The value of this field is returned in ``cpuset`` + +**NOTES:** + +NONE diff --git a/posix-users/thread_cancellation.rst b/posix-users/thread_cancellation.rst new file mode 100644 index 0000000..ae14542 --- /dev/null +++ b/posix-users/thread_cancellation.rst @@ -0,0 +1,201 @@ +.. comment SPDX-License-Identifier: CC-BY-SA-4.0 + +.. COMMENT: COPYRIGHT (c) 1988-2002. +.. COMMENT: On-Line Applications Research Corporation (OAR). +.. COMMENT: All rights reserved. + +Thread Cancellation Manager +########################### + +Introduction +============ + +The +thread cancellation manager is ... + +The directives provided by the thread cancellation manager are: + +- pthread_cancel_ - Cancel Execution of a Thread + +- pthread_setcancelstate_ - Set Cancelability State + +- pthread_setcanceltype_ - Set Cancelability Type + +- pthread_testcancel_ - Create Cancellation Point + +- pthread_cleanup_push_ - Establish Cancellation Handler + +- pthread_cleanup_pop_ - Remove Cancellation Handler + +Background +========== + +There is currently no text in this section. + +Operations +========== + +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. + +.. _pthread_cancel: + +pthread_cancel - Cancel Execution of a Thread +--------------------------------------------- +.. index:: pthread_cancel +.. index:: cancel execution of a thread + +**CALLING SEQUENCE:** + +.. code-block:: c + + int pthread_cancel( + ); + +**STATUS CODES:** + +.. list-table:: + :class: rtems-table + + * - ``E`` + - The + +**DESCRIPTION:** + +**NOTES:** + +.. _pthread_setcancelstate: + +pthread_setcancelstate - Set Cancelability State +------------------------------------------------ +.. index:: pthread_setcancelstate +.. index:: set cancelability state + +**CALLING SEQUENCE:** + +.. code-block:: c + + int pthread_setcancelstate( + ); + +**STATUS CODES:** + +.. list-table:: + :class: rtems-table + + * - ``E`` + - The + +**DESCRIPTION:** + +**NOTES:** + +.. _pthread_setcanceltype: + +pthread_setcanceltype - Set Cancelability Type +---------------------------------------------- +.. index:: pthread_setcanceltype +.. index:: set cancelability type + +**CALLING SEQUENCE:** + +.. code-block:: c + + int pthread_setcanceltype( + ); + +**STATUS CODES:** + +.. list-table:: + :class: rtems-table + + * - ``E`` + - The + +**DESCRIPTION:** + +**NOTES:** + +.. _pthread_testcancel: + +pthread_testcancel - Create Cancellation Point +---------------------------------------------- +.. index:: pthread_testcancel +.. index:: create cancellation point + +**CALLING SEQUENCE:** + +.. code-block:: c + + int pthread_testcancel( + ); + +**STATUS CODES:** + +.. list-table:: + :class: rtems-table + + * - ``E`` + - The + +**DESCRIPTION:** + +**NOTES:** + +.. _pthread_cleanup_push: + +pthread_cleanup_push - Establish Cancellation Handler +----------------------------------------------------- +.. index:: pthread_cleanup_push +.. index:: establish cancellation handler + +**CALLING SEQUENCE:** + +.. code-block:: c + + int pthread_cleanup_push( + ); + +**STATUS CODES:** + +.. list-table:: + :class: rtems-table + + * - ``E`` + - The + +**DESCRIPTION:** + +**NOTES:** + +.. _pthread_cleanup_pop: + +pthread_cleanup_pop - Remove Cancellation Handler +------------------------------------------------- +.. index:: pthread_cleanup_pop +.. index:: remove cancellation handler + +**CALLING SEQUENCE:** + +.. code-block:: c + + int pthread_cleanup_push( + ); + +**STATUS CODES:** + +.. list-table:: + :class: rtems-table + + * - ``E`` + - The + +**DESCRIPTION:** + +**NOTES:** diff --git a/posix-users/timer.rst b/posix-users/timer.rst new file mode 100644 index 0000000..f5be6c8 --- /dev/null +++ b/posix-users/timer.rst @@ -0,0 +1,165 @@ +.. comment SPDX-License-Identifier: CC-BY-SA-4.0 + +.. COMMENT: COPYRIGHT(c) 1988-2002. +.. COMMENT: On-Line Applications Research Corporation(OAR). +.. COMMENT: All rights reserved. + +Timer Manager +############# + +Introduction +============ + +The timer manager is ... + +The services provided by the timer manager are: + +- timer_create_ - Create a Per-Process Timer + +- timer_delete_ - Delete a Per-Process Timer + +- timer_settime_ - Set Next Timer Expiration + +- timer_gettime_ - Get Time Remaining on Timer + +- timer_getoverrun_ - Get Timer Overrun Count + +Background +========== + +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. + +.. COMMENT: timer_create + +.. _timer_create: + +timer_create - Create a Per-Process Timer +----------------------------------------- + +**CALLING SEQUENCE:** + +.. code-block:: c + + #include + #include + int timer_create( + clockid_t clock_id, + struct sigevent *evp, + timer_t *timerid + ); + +**STATUS CODES:** + +``EXXX`` - + +**DESCRIPTION:** + +**NOTES:** + +.. COMMENT: timer_delete + +.. _timer_delete: + +timer_delete - Delete a Per-Process Timer +----------------------------------------- + +**CALLING SEQUENCE:** + +.. code-block:: c + + #include + int timer_delete( + timer_t timerid + ); + +**STATUS CODES:** + +``EXXX`` - + +**DESCRIPTION:** + +**NOTES:** + +.. COMMENT: timer_settime + +.. _timer_settime: + +timer_settime - Set Next Timer Expiration +----------------------------------------- + +**CALLING SEQUENCE:** + +.. code-block:: c + + #include + int timer_settime( + timer_t timerid, + int flags, + const struct itimerspec *value, + struct itimerspec *ovalue + ); + +**STATUS CODES:** + +``EXXX`` - + +**DESCRIPTION:** + +**NOTES:** + +.. COMMENT: timer_gettime + +.. _timer_gettime: + +timer_gettime - Get Time Remaining on Timer +------------------------------------------- + +**CALLING SEQUENCE:** + +.. code-block:: c + + #include + int timer_gettime( + timer_t timerid, + struct itimerspec *value + ); + +**STATUS CODES:** + +``EXXX`` - + +**DESCRIPTION:** + +**NOTES:** + +.. COMMENT: timer_getoverrun + +.. _timer_getoverrun: + +timer_getoverrun - Get Timer Overrun Count +------------------------------------------ + +**CALLING SEQUENCE:** + +.. code-block:: c + + #include + int timer_getoverrun( + timer_t timerid + ); + +**STATUS CODES:** + +``EXXX`` - + +**DESCRIPTION:** + +**NOTES:** diff --git a/posix-users/wscript b/posix-users/wscript new file mode 100644 index 0000000..4a5f474 --- /dev/null +++ b/posix-users/wscript @@ -0,0 +1,6 @@ +from sys import path +from os.path import abspath +path.append(abspath('../common/')) + +from waf import cmd_configure as configure, cmd_build as build, spell, cmd_spell, cmd_options as options, linkcheck, cmd_linkcheck + -- cgit v1.2.3