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 deletions(-) delete mode 100644 posix_users/clock.rst delete mode 100644 posix_users/command.rst delete mode 100644 posix_users/condition_variable.rst delete mode 100644 posix_users/conf.py delete mode 100644 posix_users/device_and_class_specific.rst delete mode 100644 posix_users/files_and_directory.rst delete mode 100644 posix_users/index.rst delete mode 100644 posix_users/input_and_output.rst delete mode 100644 posix_users/key.rst delete mode 100644 posix_users/language_specific_services.rst delete mode 100644 posix_users/memory_managment.rst delete mode 100644 posix_users/message_passing.rst delete mode 100644 posix_users/mutex.rst delete mode 100644 posix_users/preface.rst delete mode 100644 posix_users/process_creation_and_execution.rst delete mode 100644 posix_users/process_environment.rst delete mode 100644 posix_users/scheduler.rst delete mode 100644 posix_users/semaphore.rst delete mode 100644 posix_users/services_provided_by_c.rst delete mode 100644 posix_users/services_provided_by_math.rst delete mode 100644 posix_users/signal.rst delete mode 100644 posix_users/status_of_implementation.rst delete mode 100644 posix_users/system_database.rst delete mode 100644 posix_users/thread.rst delete mode 100644 posix_users/thread_cancellation.rst delete mode 100644 posix_users/timer.rst delete mode 100644 posix_users/wscript (limited to 'posix_users') diff --git a/posix_users/clock.rst b/posix_users/clock.rst deleted file mode 100644 index e3387e7..0000000 --- a/posix_users/clock.rst +++ /dev/null @@ -1,341 +0,0 @@ -.. 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 deleted file mode 100644 index 5994765..0000000 --- a/posix_users/command.rst +++ /dev/null @@ -1,7 +0,0 @@ -.. 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 deleted file mode 100644 index ced9a8a..0000000 --- a/posix_users/condition_variable.rst +++ /dev/null @@ -1,361 +0,0 @@ -.. 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 deleted file mode 100644 index 4aa287e..0000000 --- a/posix_users/conf.py +++ /dev/null @@ -1,13 +0,0 @@ -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 deleted file mode 100644 index 24b2763..0000000 --- a/posix_users/device_and_class_specific.rst +++ /dev/null @@ -1,460 +0,0 @@ -.. 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 deleted file mode 100644 index 3a228b7..0000000 --- a/posix_users/files_and_directory.rst +++ /dev/null @@ -1,1943 +0,0 @@ -.. 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 deleted file mode 100644 index 072579c..0000000 --- a/posix_users/index.rst +++ /dev/null @@ -1,67 +0,0 @@ -.. 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 deleted file mode 100644 index 5a3b9d8..0000000 --- a/posix_users/input_and_output.rst +++ /dev/null @@ -1,1040 +0,0 @@ -.. 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 deleted file mode 100644 index 5b16ddb..0000000 --- a/posix_users/key.rst +++ /dev/null @@ -1,212 +0,0 @@ -.. 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 deleted file mode 100644 index d871e8a..0000000 --- a/posix_users/language_specific_services.rst +++ /dev/null @@ -1,621 +0,0 @@ -.. 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 deleted file mode 100644 index 631ba45..0000000 --- a/posix_users/memory_managment.rst +++ /dev/null @@ -1,313 +0,0 @@ -.. 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 deleted file mode 100644 index 64c64a3..0000000 --- a/posix_users/message_passing.rst +++ /dev/null @@ -1,741 +0,0 @@ -.. 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 deleted file mode 100644 index 6fad624..0000000 --- a/posix_users/mutex.rst +++ /dev/null @@ -1,673 +0,0 @@ -.. 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 deleted file mode 100644 index 0028d51..0000000 --- a/posix_users/preface.rst +++ /dev/null @@ -1,52 +0,0 @@ -.. 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 deleted file mode 100644 index 1668695..0000000 --- a/posix_users/process_creation_and_execution.rst +++ /dev/null @@ -1,421 +0,0 @@ -.. 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 deleted file mode 100644 index 0556d12..0000000 --- a/posix_users/process_environment.rst +++ /dev/null @@ -1,807 +0,0 @@ -.. 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 deleted file mode 100644 index 9209391..0000000 --- a/posix_users/scheduler.rst +++ /dev/null @@ -1,209 +0,0 @@ -.. 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 deleted file mode 100644 index 27fdf51..0000000 --- a/posix_users/semaphore.rst +++ /dev/null @@ -1,543 +0,0 @@ -.. 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 deleted file mode 100644 index e6b8f58..0000000 --- a/posix_users/services_provided_by_c.rst +++ /dev/null @@ -1,442 +0,0 @@ -.. 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 deleted file mode 100644 index 43a6aa5..0000000 --- a/posix_users/services_provided_by_math.rst +++ /dev/null @@ -1,98 +0,0 @@ -.. 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 deleted file mode 100644 index 490c132..0000000 --- a/posix_users/signal.rst +++ /dev/null @@ -1,989 +0,0 @@ -.. 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 deleted file mode 100644 index cc234fc..0000000 --- a/posix_users/status_of_implementation.rst +++ /dev/null @@ -1,46 +0,0 @@ -.. 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 deleted file mode 100644 index 871cca8..0000000 --- a/posix_users/system_database.rst +++ /dev/null @@ -1,256 +0,0 @@ -.. 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 deleted file mode 100644 index e5f47c5..0000000 --- a/posix_users/thread.rst +++ /dev/null @@ -1,1425 +0,0 @@ -.. 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 deleted file mode 100644 index ae14542..0000000 --- a/posix_users/thread_cancellation.rst +++ /dev/null @@ -1,201 +0,0 @@ -.. 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 deleted file mode 100644 index f5be6c8..0000000 --- a/posix_users/timer.rst +++ /dev/null @@ -1,165 +0,0 @@ -.. 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 deleted file mode 100644 index 4a5f474..0000000 --- a/posix_users/wscript +++ /dev/null @@ -1,6 +0,0 @@ -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