371 lines
16 KiB
ReStructuredText
371 lines
16 KiB
ReStructuredText
Clocks and Timers
|
|
*****************
|
|
|
|
- :c:func:`clock_settime`
|
|
- :c:func:`clock_gettime`
|
|
- :c:func:`clock_getres`
|
|
- :c:func:`mktime`
|
|
- :c:func:`gmtime`
|
|
- :c:func:`localtime`
|
|
- :c:func:`asctime`
|
|
- :c:func:`ctime`
|
|
- :c:func:`gmtime_r`
|
|
- :c:func:`localtime_r`
|
|
- :c:func:`asctime_r`
|
|
- :c:func:`ctime_r`
|
|
- :c:func:`timer_create`
|
|
- :c:func:`timer_delete`
|
|
- :c:func:`timer_settime`
|
|
- :c:func:`timer_gettime`
|
|
- :c:func:`timer_getoverrun`
|
|
- :c:func:`gettimeofday`
|
|
- :c:func:`gethrtime`
|
|
|
|
.. c:function:: int clock_settime(clockid_t clockid, const struct timespec *tp)
|
|
|
|
:return: If successful, returns zero (``OK``). Otherwise,
|
|
a non-zero error number will be returned to indicate the error.
|
|
|
|
.. c:function:: int clock_gettime(clockid_t clockid, struct timespec *tp)
|
|
|
|
:return: If successful, returns zero (``OK``). Otherwise,
|
|
a non-zero error number will be returned to indicate the error.
|
|
|
|
.. c:function:: int clock_getres(clockid_t clockid, struct timespec *res)
|
|
|
|
:return: If successful, returns zero (``OK``). Otherwise,
|
|
a non-zero error number will be returned to indicate the error.
|
|
|
|
.. c:function:: time_t mktime(struct tm *tp);
|
|
|
|
:return: If successful, returns zero (``OK``). Otherwise,
|
|
a non-zero error number will be returned to indicate the error.
|
|
|
|
.. c:function:: FAR struct tm *gmtime(FAR const time_t *timep);
|
|
|
|
Represents GMT date/time in a type ``struct tm``. This
|
|
function is not re-entrant.
|
|
|
|
:param timep: Represents GMT calendar time. This is an absolute time
|
|
value representing the number of seconds elapsed since 00:00:00 on
|
|
January 1, 1970, Coordinated Universal Time (UTC).
|
|
|
|
:return: If successful, the function will return the pointer to a statically defined
|
|
instance of ``struct tm``. Otherwise, a NULL will be returned to
|
|
indicate the error:
|
|
|
|
.. c:function:: FAR struct tm *localtime(FAR const time_t *timep)
|
|
|
|
Represents local date/time in a type ``struct tm``.
|
|
This function is not re-entrant.
|
|
|
|
:param timep: Represents GMT calendar time. This is an absolute time
|
|
value representing the number of seconds elapsed since 00:00:00 on
|
|
January 1, 1970, Coordinated Universal Time (UTC).
|
|
|
|
:return: If successful, the function will return the pointer to a statically defined
|
|
instance of ``struct tm``. Otherwise, a NULL will be returned to
|
|
indicate the error:
|
|
|
|
.. c:function:: FAR char *asctime(FAR const struct tm *tp);
|
|
|
|
Converts the time provided in a
|
|
``struct tm`` to a string representation. ``asctime()`` is not
|
|
re-entrant.
|
|
|
|
:param tp: Pointer to the time to be converted.
|
|
:return: If successful, the function will
|
|
return a pointer to a statically defined string holding the converted
|
|
time. Otherwise, a NULL will be returned to indicate the error.
|
|
|
|
.. c:function:: FAR char *ctime(FAR const time_t *timep)
|
|
|
|
Converts the time provided in seconds since
|
|
the epoch to a string representation. ``ctime()`` is not re-entrant.
|
|
|
|
:param timep: The current time represented as seconds since the epoch.
|
|
:return: If successful, the function will return
|
|
the pointer to the converted string. Otherwise, a NULL will be returned
|
|
to indicate the error.
|
|
|
|
.. c:function:: struct tm *gmtime_r(const time_t *timep, struct tm *result);
|
|
|
|
Represents GMT date/time in a type ``struct tm``. This
|
|
function is re-entrant.
|
|
|
|
:param timep: Represents GMT calendar time. This is an absolute time
|
|
value representing the number of seconds elapsed since 00:00:00 on
|
|
January 1, 1970, Coordinated Universal Time (UTC).
|
|
:param result: A user-provided buffer to receive the converted time
|
|
structure.
|
|
:return: If successful, the ``gmtime_r()`` function will
|
|
return the pointer, ``result``, provided by the caller. Otherwise, a
|
|
NULL will be returned to indicate the error:
|
|
|
|
.. c:function:: FAR struct tm *localtime_r(FAR const time_t *timep, FAR struct tm *result)
|
|
|
|
Represents local date/time in a type ``struct tm``.
|
|
This function is re-entrant.
|
|
|
|
:param timep: Represents GMT calendar time. This is an absolute time
|
|
value representing the number of seconds elapsed since 00:00:00 on
|
|
January 1, 1970, Coordinated Universal Time (UTC).
|
|
:param result: A user-provided buffer to receive the converted time
|
|
structure.
|
|
:return: If successful, the
|
|
``localtime_r()`` function will return the pointer, ``result``, provided
|
|
by the caller. Otherwise, a NULL will be returned to indicate the error:
|
|
|
|
.. c:function:: FAR char *asctime_r(FAR const struct tm *tp, FAR char *buf)
|
|
|
|
Converts the time provided in a
|
|
``struct tm`` to a string representation. ``asctime-r()`` is re-entrant.
|
|
|
|
:param tp: Pointer to the time to be converted.
|
|
:param buf: The user provider buffer. of size >= 26 characters, to
|
|
receive the converted time.
|
|
:return: If successful, the ``asctime_r()`` function will
|
|
return the pointer, ``buf``, provided by the caller. Otherwise, a NULL
|
|
will be returned to indicate the error.
|
|
|
|
.. c:function:: FAR char *ctime_r(FAR const time_t *timep, FAR char *buf)
|
|
|
|
Converts the time provided in seconds
|
|
since the epoch to a string representation. ``ctime()`` is re-entrant.
|
|
|
|
:param timep: The current time represented as seconds since the epoch.
|
|
:param buf: The user provider buffer. of size >= 26 characters, to
|
|
receive the converted time.
|
|
:return: If successful, the ``ctime_r()`` function will
|
|
return the pointer, ``buf``, provided by the caller. Otherwise, a NULL
|
|
will be returned to indicate the error.
|
|
|
|
.. c:function:: int timer_create(clockid_t clockid, struct sigevent *evp, timer_t *timerid);
|
|
|
|
Creates per-thread
|
|
timer using the specified clock, ``clock_id``, as the timing base. The
|
|
``timer_create()`` function returns, in the location referenced by
|
|
``timerid``, a timer ID of type timer_t used to identify the timer in
|
|
timer requests. This timer ID is unique until the timer is deleted. The
|
|
particular clock, ``clock_id``, is defined in ``<time.h>``. The timer
|
|
whose ID is returned will be in a disarmed state upon return from
|
|
``timer_create()``.
|
|
|
|
The ``evp`` argument, if non-NULL, points to a ``sigevent`` structure.
|
|
This structure is allocated by the called and defines the asynchronous
|
|
notification to occur. If the ``evp`` argument is NULL, the effect is as
|
|
if the ``evp`` argument pointed to a ``sigevent`` structure with the
|
|
``sigev_notify`` member having the value ``SIGEV_SIGNAL``, the
|
|
``sigev_signo`` having a default signal number, and the ``sigev_value``
|
|
member having the value of the timer ID.
|
|
|
|
Each implementation defines a set of clocks that can be used as timing
|
|
bases for per-thread timers. All implementations will support a
|
|
``clock_id`` of ``CLOCK_REALTIME``.
|
|
|
|
:param clockid: Specifies the clock to use as the timing base. Must be
|
|
``CLOCK_REALTIME``.
|
|
:param ``evp``: Refers to a user allocated sigevent structure that defines
|
|
the asynchronous notification. evp may be NULL (see above).
|
|
:param ``timerid``: The pre-thread timer created by the call to
|
|
timer_create().
|
|
:return: If the call succeeds, ``timer_create()`` will return
|
|
0 (``OK``) and update the location referenced by ``timerid`` to a
|
|
``timer_t``, which can be passed to the other per-thread timer calls. If
|
|
an error occurs, the function will return a value of -1 (``ERROR``) and
|
|
set ``errno`` to indicate the error.
|
|
|
|
- ``EAGAIN``. The system lacks sufficient signal queuing resources to
|
|
honor the request.
|
|
- ``EAGAIN``. The calling process has already created all of the timers
|
|
it is allowed by this implementation.
|
|
- ``EINVAL``. The specified clock ID is not defined.
|
|
- ``ENOTSUP``. The implementation does not support the creation of a
|
|
timer attached to the CPU-time clock that is specified by clock_id
|
|
and associated with a thread different thread invoking
|
|
timer_create().
|
|
|
|
**POSIX Compatibility:** Comparable to the POSIX interface of the same
|
|
name. Differences from the full POSIX implementation include:
|
|
|
|
- Only ``CLOCK_REALTIME`` is supported for the ``clockid`` argument.
|
|
|
|
.. c:function:: int timer_delete(timer_t timerid);
|
|
|
|
Deletes the specified
|
|
timer, ``timerid``, previously created by the ``timer_create()``
|
|
function. If the timer is armed when ``timer_delete()`` is called, the
|
|
timer will be automatically disarmed before removal. The disposition of
|
|
pending signals for the deleted timer is unspecified.
|
|
|
|
:param timerid: The pre-thread timer, previously created by the call to
|
|
timer_create(), to be deleted.
|
|
:return: If successful, the ``timer_delete()`` function will
|
|
return zero (``OK``). Otherwise, the function will return a value of -1
|
|
(``ERROR``) and set ``errno`` to indicate the error:
|
|
|
|
- ``EINVAL``. The timer specified timerid is not valid.
|
|
|
|
**POSIX Compatibility:** Comparable to the POSIX interface of the same
|
|
name.
|
|
|
|
.. c:function:: int timer_settime(timer_t timerid, int flags, const struct itimerspec *value, \
|
|
struct itimerspec *ovalue);
|
|
|
|
Sets the time until
|
|
the next expiration of the timer specified by ``timerid`` from the
|
|
``it_value`` member of the value argument and arm the timer if the
|
|
``it_value`` member of value is non-zero. If the specified timer was
|
|
already armed when ``timer_settime()`` is called, this call will reset
|
|
the time until next expiration to the value specified. If the
|
|
``it_value`` member of value is zero, the timer will be disarmed. The
|
|
effect of disarming or resetting a timer with pending expiration
|
|
notifications is unspecified.
|
|
|
|
If the flag ``TIMER_ABSTIME`` is not set in the argument flags,
|
|
``timer_settime()`` will behave as if the time until next expiration is
|
|
set to be equal to the interval specified by the ``it_value`` member of
|
|
value. That is, the timer will expire in ``it_value`` nanoseconds from
|
|
when the call is made. If the flag ``TIMER_ABSTIME`` is set in the
|
|
argument flags, ``timer_settime()`` will behave as if the time until
|
|
next expiration is set to be equal to the difference between the
|
|
absolute time specified by the ``it_value`` member of value and the
|
|
current value of the clock associated with ``timerid``. That is, the
|
|
timer will expire when the clock reaches the value specified by the
|
|
``it_value`` member of value. If the specified time has already passed,
|
|
the function will succeed and the expiration notification will be made.
|
|
|
|
The reload value of the timer will be set to the value specified by the
|
|
``it_interval`` member of value. When a timer is armed with a non-zero
|
|
``it_interval``, a periodic (or repetitive) timer is specified.
|
|
|
|
Time values that are between two consecutive non-negative integer
|
|
multiples of the resolution of the specified timer will be rounded up to
|
|
the larger multiple of the resolution. Quantization error will not cause
|
|
the timer to expire earlier than the rounded time value.
|
|
|
|
If the argument ``ovalue`` is not NULL, the t\ ``imer_settime()``
|
|
function will store, in the location referenced by ``ovalue``, a value
|
|
representing the previous amount of time before the timer would have
|
|
expired, or zero if the timer was disarmed, together with the previous
|
|
timer reload value. Timers will not expire before their scheduled time.
|
|
|
|
**NOTE:**\ At present, the ``ovalue`` argument is ignored.
|
|
|
|
:param timerid: The pre-thread timer, previously created by the call to
|
|
timer_create(), to be be set.
|
|
:param flags: Specify characteristics of the timer (see above)
|
|
:param value: Specifies the timer value to set
|
|
:param ovalue: A location in which to return the time remaining from the
|
|
previous timer setting (ignored).
|
|
|
|
:return: If the timer_gettime() succeeds, a value of 0
|
|
(``OK``) will be returned. If an error occurs, the value -1 (``ERROR``)
|
|
will be returned, and ```errno`` <#ErrnoAccess>`__ set to indicate the
|
|
error.
|
|
|
|
- ``EINVAL``. The timerid argument does not correspond to an ID
|
|
returned by timer_create() but not yet deleted by timer_delete().
|
|
- ``EINVAL``. A value structure specified a nanosecond value less than
|
|
zero or greater than or equal to 1000 million, and the it_value
|
|
member of that structure did not specify zero seconds and
|
|
nanoseconds.
|
|
|
|
**POSIX Compatibility:** Comparable to the POSIX interface of the same
|
|
name. Differences from the full POSIX implementation include:
|
|
|
|
- The ``ovalue`` argument is ignored.
|
|
|
|
.. c:function:: int timer_gettime(timer_t timerid, struct itimerspec *value);
|
|
|
|
Stores the amount
|
|
of time until the specified timer, ``timerid``, expires and the reload
|
|
value of the timer into the space pointed to by the ``value`` argument.
|
|
The ``it_value`` member of this structure will contain the amount of
|
|
time before the timer expires, or zero if the timer is disarmed. This
|
|
value is returned as the interval until timer expiration, even if the
|
|
timer was armed with absolute time. The ``it_interval`` member of
|
|
``value`` will contain the reload value last set by ``timer_settime()``.
|
|
|
|
Due to the asynchronous operation of this function, the time reported by
|
|
this function could be significantly more than that actual time
|
|
remaining on the timer at any time.
|
|
|
|
:param timerid: Specifies pre-thread timer, previously created by the
|
|
call to ``timer_create()``, whose remaining count will be returned.
|
|
:return: If successful, the ``timer_gettime()`` function will
|
|
return zero (``OK``). Otherwise, an non-zero error number will be
|
|
returned to indicate the error:
|
|
|
|
- ``EINVAL``. The ``timerid`` argument does not correspond to an ID
|
|
returned by ``timer_create()`` but not yet deleted by
|
|
``timer_delete()``.
|
|
|
|
**POSIX Compatibility:** Comparable to the POSIX interface of the same
|
|
name.
|
|
|
|
.. c:function:: int timer_getoverrun(timer_t timerid);
|
|
|
|
Only a single signal will be queued to the process for
|
|
a given timer at any point in time. When a timer for which a signal is
|
|
still pending expires, no signal will be queued, and a timer overrun
|
|
will occur. When a timer expiration signal is delivered to or accepted
|
|
by a process, if the implementation supports the *Realtime Signals
|
|
Extension*, the ``timer_getoverrun()`` function will return the timer
|
|
expiration overrun count for the specified timer. The overrun count
|
|
returned contains the number of extra timer expirations that occurred
|
|
between the time the signal was generated (queued) and when it was
|
|
delivered or accepted, up to but not including an implementation-defined
|
|
maximum of ``DELAYTIMER_MAX``. If the number of such extra expirations
|
|
is greater than or equal to ``DELAYTIMER_MAX``, then the overrun count
|
|
will be set to ``DELAYTIMER_MAX``. The value returned by
|
|
``timer_getoverrun()`` will apply to the most recent expiration signal
|
|
delivery or acceptance for the timer. If no expiration signal has been
|
|
delivered for the timer, or if the *Realtime Signals Extension* is not
|
|
supported, the return value of ``timer_getoverrun()`` is unspecified.
|
|
|
|
**NOTE:** This interface is not currently implemented in NuttX.
|
|
|
|
:param timerid: Specifies pre-thread timer, previously created by the
|
|
call to ``timer_create()``, whose overrun count will be returned.
|
|
|
|
:return: If the ``timer_getoverrun()`` function succeeds, it
|
|
will return the timer expiration overrun count as explained above.
|
|
``timer_getoverrun()`` will fail if:
|
|
|
|
- ``EINVAL``. The ``timerid`` argument does not correspond to an ID
|
|
returned by ``timer_create()`` but not yet deleted by
|
|
``timer_delete()``.
|
|
|
|
**POSIX Compatibility:** Comparable to the POSIX interface of the same
|
|
name. Differences from the full POSIX implementation include:
|
|
|
|
- This interface is not currently implemented by NuttX.
|
|
|
|
**Assumptions/Limitations:**
|
|
|
|
**POSIX Compatibility:** Comparable to the POSIX interface of the same
|
|
name.
|
|
|
|
.. c:function:: int gettimeofday(struct timeval *tp, void *tzp);
|
|
|
|
This implementation of ``gettimeofday()`` is simply a
|
|
thin wrapper around :c:func:`clock_gettime`. It simply
|
|
calls ``clock_gettime()`` using the ``CLOCK_REALTIME`` timer and
|
|
converts the result to the required ``struct timeval``.
|
|
|
|
:param tp: The current time will be returned to this user provided
|
|
location.
|
|
:param tzp: A reference to the timezone -- *IGNORED*.
|
|
|
|
:return: See :c:func:`clock_gettime`.
|
|
|
|
.. c:function:: hrtime_t gethrtime(void);
|
|
|
|
This implementation of ``gethrtime()`` is simply a
|
|
thin wrapper around :c:func:`clock_gettime`. It simply
|
|
calls ``clock_gettime()`` using the ``CLOCK_REALTIME`` or ``CLOCK_MONOTONIC``,
|
|
and converts the result to the required hrtime_t.
|
|
|
|
:return: current system time in ns
|