summaryrefslogtreecommitdiffstats
path: root/posix_users/clock.rst
diff options
context:
space:
mode:
authorAmar Takhar <amar@rtems.org>2016-01-17 00:55:21 -0500
committerAmar Takhar <verm@darkbeer.org>2016-05-02 20:51:23 -0400
commit1264a8f1089fad85cabb024c930b19b0a36864b4 (patch)
treef95424251f62abd513babf47148828ca402dc893 /posix_users/clock.rst
parentec76eca9cc967e0d8990316eee1d1841387f5210 (diff)
downloadrtems-docs-1264a8f1089fad85cabb024c930b19b0a36864b4.tar.bz2
Split document into seperate files by section.
Diffstat (limited to 'posix_users/clock.rst')
-rw-r--r--posix_users/clock.rst323
1 files changed, 323 insertions, 0 deletions
diff --git a/posix_users/clock.rst b/posix_users/clock.rst
new file mode 100644
index 0000000..f37c1b9
--- /dev/null
+++ b/posix_users/clock.rst
@@ -0,0 +1,323 @@
+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 - Obtain Time of Day
+----------------------------------
+.. index:: clock_gettime
+.. index:: obtain time of day
+
+**CALLING SEQUENCE:**
+
+.. code:: c
+
+ #include <time.h>
+ 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:
+
+*EINVAL*
+ The tp pointer parameter is invalid.
+
+*EINVAL*
+ The clock_id specified is invalid.
+
+**DESCRIPTION:**
+
+**NOTES:**
+
+NONE
+
+clock_settime - Set Time of Day
+-------------------------------
+.. index:: clock_settime
+.. index:: set time of day
+
+**CALLING SEQUENCE:**
+
+.. code:: c
+
+ #include <time.h>
+ 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:
+
+*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 - Get Clock Resolution
+-----------------------------------
+.. index:: clock_getres
+.. index:: get clock resolution
+
+**CALLING SEQUENCE:**
+
+.. code:: c
+
+ #include <time.h>
+ 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:
+
+*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 - Delay Process Execution
+-------------------------------
+.. index:: sleep
+.. index:: delay process execution
+
+**CALLING SEQUENCE:**
+
+.. code:: c
+
+ #include <unistd.h>
+ 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 - 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:: c
+
+ #include <time.h>
+ 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 - Delay with High Resolution
+--------------------------------------
+.. index:: nanosleep
+.. index:: delay with high resolution
+
+**CALLING SEQUENCE:**
+
+.. code:: c
+
+ #include <time.h>
+ 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:
+
+*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 - Get the Time of Day
+----------------------------------
+.. index:: gettimeofday
+.. index:: get the time of day
+
+**CALLING SEQUENCE:**
+
+.. code:: c
+
+ #include <sys/time.h>
+ #include <unistd.h>
+ int gettimeofday(
+ 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.
+
+*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 - Get time in seconds
+--------------------------
+.. index:: time
+.. index:: get time in seconds
+
+**CALLING SEQUENCE:**
+
+.. code:: c
+
+ #include <time.h>
+ 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
+
+.. 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.
+