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