Time

https://pubs.opengroup.org/onlinepubs/9799919799/basedefs/time.h.html

Copyright: Copyright (c) 2025 TNX Software Ltd. All rights reserved. Licensed under the terms of the QuantumRT Kernel License. the LICENSE file in the root of this package for details.

Defines

CLOCK_REALTIME (0): Real-time clock.

CLOCK_MONOTONIC (1): Monotonic clock.

TIMER_ABSTIME (0x01): Absolute time flag.

Functions

int clock_getcpuclockid(pid_t pid, clockid_t *clock_id)

Not supported.

Returns:: ENOSYS.

int clock_getres(clockid_t clock_id, struct timespec *res)

Retrieves the resolution of a specified clock. If the time is not a multiple of res, then the value is truncated to a multiple of res.

Error numbers:

EINVAL if the clock ID is invalid.

Parameters:

clock_id – Clock identifier.
res – Pointer to a timespec where the resolution will be stored.

Returns:

0 on success, or -1 on error.

int clock_gettime(clockid_t clock_id, struct timespec *tp)

Retrieves the current system time.

Error numbers:

EINVAL if the clock ID is invalid.
EOVERFLOW if the time cannot fit in an object of type time_t.

Parameters:

clock_id – Clock identifier.
tp – Pointer to a timespec where the current time will be stored.

Returns:

0 on success, or -1 on error.

int clock_settime(clockid_t clock_id, const struct timespec *tp)

Retrieves the current system time.

Error numbers:

EINVAL if the clock ID is invalid.
EINVAL if the clock ID is CLOCK_MONOTONIC.
EINVAL if the nanoseconds of tp argument are not in the range [0, 999’999’999].

Parameters:

clock_id – Clock identifier.
tp – Pointer to a timespec that specifies the new time for the specified clock.

Returns:

0 on success, or -1 on error.

int clock_nanosleep(clockid_t clock_id, int flags, const struct timespec *rqtp, struct timespec *rmtp)

Suspends the calling thread until the specified time.

Error numbers:

EINVAL if the rqtp is invalid, nanoseconds have to be => 0 and < 1000 million.
ENOTSUP if the clock ID is not supported.

Parameters:

clock_id – Clock identifier.
flags – Flags to control the behavior of the sleep operation.
- TIMER_ABSTIME : the sleep time is interpreted as an absolute time.
rqtp – Pointer to a timespec that specifies the requested sleep duration.
rmtp – Not supported.

Returns:

0 on success, or error number.

int nanosleep(const struct timespec *rqtp, struct timespec *rmtp)

Suspends the calling thread until the specified time.

Error numbers:

EINVAL if the rqtp is invalid, nanoseconds have to be => 0 and < 1000 million.

Parameters:

rqtp – Pointer to a timespec that specifies the requested sleep duration.
rmtp – Not supported.

Returns:

0 on success, or -1 on error.

int timer_create(clockid_t clockid, struct sigevent *evp, timer_t *timerid)

Create a new timer.

Note

errno:

EINVAL if the clock ID is invalid.
EINVAL if timerid is NULL.

ENOTSUP if unsupported sigevent notification (SIGEV_SIGNAL) is passed.

// Example - Timeout implementation for Modbus Master
// --------------------------------------------------
// This example demonstrates using a POSIX timer to implement
// a timeout mechanism for a Modbus master thread.

#include <stdio.h>
#include "signal.h"
#include "time.h"
#include "pthread.h"

#define MODBUS_TIMEOUT_MS 200

timer_t      modbus_timer;
volatile int timeout_flag = 0;

void timeout_handler(union sigval sv)
{
    (void)sv;
    timeout_flag = 1;
}

void *modbus_master_thread(void *arg)
{
    struct itimerspec its;
    struct sigevent   sev = {
        .sigev_notify          = SIGEV_THREAD,
        .sigev_notify_function = timeout_handler,
        .sigev_value.sival_ptr = &modbus_timer
    };

    // Create timer (CLOCK_MONOTONIC preferred for real-time use)
    timer_create(CLOCK_MONOTONIC, &sev, &modbus_timer);

    // Configure timer as one-shot
    its.it_interval.tv_sec  = 0;
    its.it_interval.tv_nsec = 0;

    for (;;)
    {
        send_modbus_request();

        // Start timeout supervision
        its.it_value.tv_sec  = 0;
        its.it_value.tv_nsec = MODBUS_TIMEOUT_MS * 1000000ull;
        timer_settime(modbus_timer, 0, &its, NULL);

        while (timeout_flag == 0)
        {
            if (check_for_modbus_response())
            {
                // Response received → cancel timer
                struct itimerspec stop = {0};
                timer_settime(modbus_timer, 0, &stop, NULL);
                process_modbus_response();
                break;
            }
        }

        if (timeout_flag == 1)
        {
            timeout_flag = 0;

            handle_modbus_timeout();
        }
    }
}

Parameters:

clockid – Clock identifier, CLOCK_MONOTONIC or CLOCK_REALTIME.
evp – Pointer to a sigevent that specifies the event to be delivered when the timer expires.
timerid – Pointer to a timer_t where the created timer ID will be stored.

Returns:

0 on success, -1 on error.

int timer_delete(timer_t timerid)

Delete a timer.

Parameters:

timerid – Timer ID to be deleted.

Returns:

0 on success, -1 on error.

int timer_getoverrun(timer_t timerid)

Not supported.

Returns:: -1 and sets errno to ENOSYS.

int timer_gettime(timer_t timerid, struct itimerspec *value)

Get the time remaining for a timer and its reload value. Reload value of 0 means the timer is disarmed.

Error numbers:

EINVAL if the timer ID is invalid.

Parameters:

timerid – Timer ID.
value – Pointer to a itimerspec where the remaining time will be stored.

Returns:

0 on success, -1 on error and errno set.

int timer_settime(timer_t timerid, int flags, const struct itimerspec *value, struct itimerspec *ovalue)

Set a timer’s time until expiration and, optionally, its reload value:

To set a timer to expire after a certain duration, set the it_value field to the desired duration and the it_interval field to zero.
To set a periodic timer, set the it_value field to the initial expiration duration and the it_interval field to the desired period.
To disarm a timer, set the it_value field to zero.

Parameters:

timerid – Timer ID.
flags – Flags to control the behavior of the timer set operation.
- TIMER_ABSTIME : the time is interpreted as an absolute time.
value – Pointer to a itimerspec that specifies the new timer settings.
ovalue – Pointer to a itimerspec where the old timer settings will be stored. Can be NULL if not needed.

Returns:

0 on success, -1 on error and errno set.

struct timespec

Public Members

time_t tv_sec: Seconds.

long tv_nsec: Nanoseconds. [0, 999’999’999]

struct itimerspec

Public Members

struct timespec it_interval: Timer period.

struct timespec it_value: Timer expiration.