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