Documentation/reference/user/06_clocks_timers.rst - nuttx - Git at Google

 =================
 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
	=================
	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