Clocks and Timers

• clock_settime()

• clock_gettime()

• clock_getres()

• mktime()

• gmtime()

• localtime()

• asctime()

• ctime()

• gmtime_r()

• localtime_r()

• asctime_r()

• ctime_r()

• timer_create()

• timer_delete()

• timer_settime()

• timer_gettime()

• timer_getoverrun()

• gettimeofday()

• gethrtime()

int clock_settime(clockid_t clockid, const struct timespec *tp)

Returns:

If successful, returns zero (OK). Otherwise, a non-zero error number will be returned to indicate the error.

int clock_gettime(clockid_t clockid, struct timespec *tp)

Returns:

If successful, returns zero (OK). Otherwise, a non-zero error number will be returned to indicate the error.

int clock_getres(clockid_t clockid, struct timespec *res)

Returns:

If successful, returns zero (OK). Otherwise, a non-zero error number will be returned to indicate the error.

time_t mktime(struct tm *tp);

Returns:

If successful, returns zero (OK). Otherwise, a non-zero error number will be returned to indicate the error.

FAR struct tm *gmtime(FAR const time_t *timep);

Represents GMT date/time in a type struct tm. This function is not re-entrant.

Parameters:

• 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).

Returns:

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:

FAR struct tm *localtime(FAR const time_t *timep)

Represents local date/time in a type struct tm. This function is not re-entrant.

Parameters:

• 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).

Returns:

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:

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.

Parameters:

• tp – Pointer to the time to be converted.

Returns:

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.

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.

Parameters:

• timep – The current time represented as seconds since the epoch.

Returns:

If successful, the function will return the pointer to the converted string. Otherwise, a NULL will be returned to indicate the error.

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.

Parameters:

• 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).

• result – A user-provided buffer to receive the converted time structure.

Returns:

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:

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.

Parameters:

• 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).

• result – A user-provided buffer to receive the converted time structure.

Returns:

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:

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.

Parameters:

• tp – Pointer to the time to be converted.

• buf – The user provider buffer. of size >= 26 characters, to receive the converted time.

Returns:

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.

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.

Parameters:

• timep – The current time represented as seconds since the epoch.

• buf – The user provider buffer. of size >= 26 characters, to receive the converted time.

Returns:

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.

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.

Parameters:

• clockid – Specifies the clock to use as the timing base. Must be CLOCK_REALTIME.

• evp – Refers to a user allocated sigevent structure that defines the asynchronous notification. evp may be NULL (see above).

• timerid – The pre-thread timer created by the call to timer_create().

Returns:

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.

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.

Parameters:

• timerid – The pre-thread timer, previously created by the call to timer_create(), to be deleted.

Returns:

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.

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 timer_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.

Parameters:

• timerid – The pre-thread timer, previously created by the call to timer_create(), to be be set.

• flags – Specify characteristics of the timer (see above)

• value – Specifies the timer value to set

• ovalue – A location in which to return the time remaining from the previous timer setting (ignored).

Returns:

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.

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.

Parameters:

• timerid – Specifies pre-thread timer, previously created by the call to timer_create(), whose remaining count will be returned.

Returns:

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.

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.

Parameters:

• timerid – Specifies pre-thread timer, previously created by the call to timer_create(), whose overrun count will be returned.

Returns:

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.

int gettimeofday(struct timeval *tp, void *tzp);

This implementation of gettimeofday() is simply a thin wrapper around clock_gettime(). It simply calls clock_gettime() using the CLOCK_REALTIME timer and converts the result to the required struct timeval.

Parameters:

• tp – The current time will be returned to this user provided location.

• tzp – A reference to the timezone – IGNORED.

Returns:

See clock_gettime().

hrtime_t gethrtime(void);

This implementation of gethrtime() is simply a thin wrapper around clock_gettime(). It simply calls clock_gettime() using the CLOCK_REALTIME or CLOCK_MONOTONIC, and converts the result to the required hrtime_t.

Returns:

current system time in ns