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 ++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 341 insertions(+) create mode 100644 posix-users/clock.rst (limited to 'posix-users/clock.rst') diff --git a/posix-users/clock.rst b/posix-users/clock.rst new file mode 100644 index 0000000..e3387e7 --- /dev/null +++ b/posix-users/clock.rst @@ -0,0 +1,341 @@ +.. comment SPDX-License-Identifier: CC-BY-SA-4.0 + +.. COMMENT: This is the chapter from the RTEMS POSIX 1003.1b API User's Guide that +.. COMMENT: documents the services provided by the timer @c manager. + +Clock Manager +############# + +Introduction +============ + +The clock manager provides services two primary classes of services. The first +focuses on obtaining and setting the current date and time. The other category +of services focus on allowing a thread to delay for a specific length of time. + +The directives provided by the clock manager are: + +- clock_gettime_ - Obtain Time of Day + +- clock_settime_ - Set Time of Day + +- clock_getres_ - Get Clock Resolution + +- sleep_ - Delay Process Execution + +- usleep_ - Delay Process Execution in Microseconds + +- nanosleep_ - Delay with High Resolution + +- gettimeofday_ - Get the Time of Day + +- time_ - Get time in seconds + +Background +========== + +There is currently no text in this section. + +Operations +========== + +There is currently no text in this section. + +Directives +========== + +This section details the clock manager's directives. A subsection is dedicated +to each of this manager's directives and describes the calling sequence, +related constants, usage, and status codes. + +.. _clock_gettime: + +clock_gettime - Obtain Time of Day +---------------------------------- +.. index:: clock_gettime +.. index:: obtain time of day + +**CALLING SEQUENCE:** + +.. code-block:: c + + #include + int clock_gettime( + clockid_t clock_id, + struct timespec *tp + ); + +**STATUS CODES:** + +On error, this routine returns -1 and sets ``errno`` to one of the following: + +.. list-table:: + :class: rtems-table + + * - ``EINVAL`` + - The tp pointer parameter is invalid. + * - ``EINVAL`` + - The clock_id specified is invalid. + +**DESCRIPTION:** + +**NOTES:** + +NONE + +.. _clock_settime: + +clock_settime - Set Time of Day +------------------------------- +.. index:: clock_settime +.. index:: set time of day + +**CALLING SEQUENCE:** + +.. code-block:: c + + #include + int clock_settime( + clockid_t clock_id, + const struct timespec *tp + ); + +**STATUS CODES:** + +On error, this routine returns -1 and sets ``errno`` to one of the following: + +.. list-table:: + :class: rtems-table + + * - ``EINVAL`` + - The tp pointer parameter is invalid. + * - ``EINVAL`` + - The clock_id specified is invalid. + * - ``EINVAL`` + - The contents of the tp structure are invalid. + +**DESCRIPTION:** + +**NOTES:** + +NONE + +.. _clock_getres: + +clock_getres - Get Clock Resolution +----------------------------------- +.. index:: clock_getres +.. index:: get clock resolution + +**CALLING SEQUENCE:** + +.. code-block:: c + + #include + int clock_getres( + clockid_t clock_id, + struct timespec *res + ); + +**STATUS CODES:** + +On error, this routine returns -1 and sets ``errno`` to one of the following: + +.. list-table:: + :class: rtems-table + + * - ``EINVAL`` + - The res pointer parameter is invalid. + * - ``EINVAL`` + - The clock_id specified is invalid. + +**DESCRIPTION:** + +**NOTES:** + +If ``res`` is ``NULL``, then the resolution is not returned. + +.. _sleep: + +sleep - Delay Process Execution +------------------------------- +.. index:: sleep +.. index:: delay process execution + +**CALLING SEQUENCE:** + +.. code-block:: c + + #include + unsigned int sleep( + unsigned int seconds + ); + +**STATUS CODES:** + +This routine returns the number of unslept seconds. + +**DESCRIPTION:** + +The ``sleep()`` function delays the calling thread by the specified number of +``seconds``. + +**NOTES:** + +This call is interruptible by a signal. + +.. _usleep: + +usleep - Delay Process Execution in Microseconds +------------------------------------------------ +.. index:: usleep +.. index:: delay process execution +.. index:: delay process execution +.. index:: usecs delay process execution +.. index:: microsecond delay process execution + +**CALLING SEQUENCE:** + +.. code-block:: c + + #include + useconds_t usleep( + useconds_t useconds + ); + +**STATUS CODES:** + +This routine returns the number of unslept seconds. + +**DESCRIPTION:** + +The ``sleep()`` function delays the calling thread by the specified number of +``seconds``. + +The ``usleep()`` function suspends the calling thread from execution until +either the number of microseconds specified by the ``useconds`` argument has +elapsed or a signal is delivered to the calling thread and its action is to +invoke a signal-catching function or to terminate the process. + +Because of other activity, or because of the time spent in processing the call, +the actual length of time the thread is blocked may be longer than the amount +of time specified. + +**NOTES:** + +This call is interruptible by a signal. + +The Single UNIX Specification allows this service to be implemented using the +same timer as that used by the ``alarm()`` service. This is *NOT* the case for +*RTEMS* and this call has no interaction with the ``SIGALRM`` signal. + +.. _nanosleep: + +nanosleep - Delay with High Resolution +-------------------------------------- +.. index:: nanosleep +.. index:: delay with high resolution + +**CALLING SEQUENCE:** + +.. code-block:: c + + #include + int nanosleep( + const struct timespec *rqtp, + struct timespec *rmtp + ); + +**STATUS CODES:** + +On error, this routine returns -1 and sets ``errno`` to one of the following: + +.. list-table:: + :class: rtems-table + + * - ``EINTR`` + - The routine was interrupted by a signal. + * - ``EAGAIN`` + - The requested sleep period specified negative seconds or nanoseconds. + * - ``EINVAL`` + - The requested sleep period specified an invalid number for the nanoseconds + field. + +**DESCRIPTION:** + +**NOTES:** + +This call is interruptible by a signal. + +.. _gettimeofday: + +gettimeofday - Get the Time of Day +---------------------------------- +.. index:: gettimeofday +.. index:: get the time of day + +**CALLING SEQUENCE:** + +.. code-block:: c + + #include + #include + int gettimeofday( + struct timeval *tp, + struct timezone *tzp + ); + +**STATUS CODES:** + +On error, this routine returns -1 and sets ``errno`` as appropriate. + +.. list-table:: + :class: rtems-table + + * - ``EPERM`` + - ``settimeofdat`` is called by someone other than the superuser. + * - ``EINVAL`` + - Timezone (or something else) is invalid. + * - ``EFAULT`` + - One of ``tv`` or ``tz`` pointed outside your accessible address space + +**DESCRIPTION:** + +This routine returns the current time of day in the ``tp`` structure. + +**NOTES:** + +Currently, the timezone information is not supported. The ``tzp`` argument is +ignored. + +.. _time: + +time - Get time in seconds +-------------------------- +.. index:: time +.. index:: get time in seconds + +**CALLING SEQUENCE:** + +.. code-block:: c + + #include + int time( + time_t *tloc + ); + +**STATUS CODES:** + +This routine returns the number of seconds since the Epoch. + +**DESCRIPTION:** + +``time`` returns the time since 00:00:00 GMT, January 1, 1970, measured in +seconds + +If ``tloc`` in non null, the return value is also stored in the memory pointed +to by ``t``. + +**NOTES:** + +NONE -- cgit v1.2.3