CLOCK_GETTIME(2) | System Calls Manual | CLOCK_GETTIME(2)

# NAME

`clock_gettime`, `clock_settime`, `clock_getres` — get or set the time

# SYNOPSIS

`#include <time.h>`

int
`clock_gettime`(clockid_t clock, struct timespec *now);

int
`clock_settime`(clockid_t clock, const struct timespec *now);

int
`clock_getres`(clockid_t clock, struct timespec *res);

# DESCRIPTION

The `clock_gettime`() function reads the given clock and writes its absolute value to now. The clock may be a value returned by clock_getcpuclockid(3) or pthread_getcpuclockid(3), or any of the following constants:

`CLOCK_REALTIME`
  The Coordinated Universal Time (UTC) clock. Its absolute value is the time elapsed since Jan 1 1970 00:00:00 UTC (the Epoch). The clock normally advances continuously, though it may jump discontinuously if a process calls settimeofday(2) or `clock_settime`() (see below).
`CLOCK_MONOTONIC`
  The monotonic clock. Its absolute value is meaningless. The clock begins at an undefined positive point and advances continuously.
`CLOCK_BOOTTIME`
  The uptime clock. Its absolute value is the time elapsed since the system booted. The clock begins at zero and advances continuously.
`CLOCK_UPTIME`
  The runtime clock. Its absolute value is the time elapsed since the system booted less any time the system was suspended. The clock begins at zero and advances while the system is not suspended.
`CLOCK_PROCESS_CPUTIME_ID`
  The process CPU clock. Its absolute value begins at zero and advances while the calling process is running in user or kernel mode.
`CLOCK_THREAD_CPUTIME_ID`
  The thread CPU clock. Its absolute value begins at zero and advances while the calling thread is running in user or kernel mode.

The `clock_settime`() function sets the given clock to the absolute value now. Only the `CLOCK_REALTIME` clock may be set and only the superuser may set it. If the system securelevel(7) is 2 or greater, the time may only be advanced. This limitation is imposed to prevent a malicious superuser from setting arbitrary timestamps on files.

The `clock_getres`() function retrieves the resolution of the given clock and writes it to res if res is non-`NULL`. The clock may be any of the clocks accepted by `clock_gettime`() as described earlier.

The now and res arguments are `timespec` structures as defined in `<sys/time.h>`:

    struct timespec {
    	time_t	tv_sec;		/* seconds */
    	long	tv_nsec;	/* and nanoseconds */
    };

# RETURN VALUES

Upon successful completion, the value 0 is returned; otherwise the value -1 is returned and the global variable errno is set to indicate the error.

# EXAMPLES

Use the `CLOCK_REALTIME` clock to determine the time of day. Its absolute value can be passed to functions like gmtime(3) and strftime(3) to produce a human-readable string:

    char str[64];
    struct timespec now;
    struct tm *tmbuf;

    clock_gettime(CLOCK_REALTIME, &now);
    tmbuf = gmtime(&now.tv_sec);
    if (tmbuf == NULL)
    	err(1, "gmtime");
    if (strftime(str, sizeof(str), "%a %b %e %T %Y %Z", tmbuf) == 0)
    	err(1, "strftime");
    printf("%s (%lld.%09ld seconds since the Epoch)\n",
        str, (long long)now.tv_sec, now.tv_nsec);

Use the `CLOCK_MONOTONIC` clock to measure elapsed time. The timespecsub(3) function simplifies arithmetic operations on `timespec` structures:

    struct timespec elapsed, start, stop, timeout;

    timeout.tv_sec = 2;
    timeout.tv_nsec = 500000000;

    clock_gettime(CLOCK_MONOTONIC, &start);
    nanosleep(&timeout, NULL);
    clock_gettime(CLOCK_MONOTONIC, &stop);

    timespecsub(&stop, &start, &elapsed);
    printf("nanosleep: expected %lld.%09ld actual %lld.%09ld\n",
        (long long)timeout.tv_sec, timeout.tv_nsec,
        (long long)elapsed.tv_sec, elapsed.tv_nsec);

Use the `CLOCK_PROCESS_CPUTIME_ID` or `CLOCK_THREAD_CPUTIME_ID` clocks to measure CPU time instead of elapsed time:

    struct timespec cputime, start, stop;
    volatile int i;

    clock_gettime(CLOCK_PROCESS_CPUTIME_ID, &start);
    for (i = 0; i < INT_MAX; i++)
    	continue;
    clock_gettime(CLOCK_PROCESS_CPUTIME_ID, &stop);

    timespecsub(&stop, &start, &cputime);
    printf("CPU time: %lld.%09lds\n",
        (long long)cputime.tv_sec, cputime.tv_nsec);

How much time has elapsed since the system booted? Has the system been suspended for any of that time?

    struct timespec diff, total, running;

    clock_gettime(CLOCK_BOOTTIME, &total);
    clock_gettime(CLOCK_UPTIME, &running);
    timespecsub(&total, &running, &diff);

    printf("Seconds since boot: %8lld.%09ld\n",
        (long long)total.tv_sec, total.tv_nsec);
    printf("Seconds suspended:  %8lld.%09ld\n",
        (long long)diff.tv_sec, diff.tv_nsec);

Set the `CLOCK_REALTIME` clock to Jan 1 00:00:00 2000 UTC:

    struct tm y2k;
    struct timespec ts;

    y2k.tm_year = 100;	/* 2000 */
    y2k.tm_mon = 0;		/* January */
    y2k.tm_mday = 1;
    y2k.tm_hour = 0;
    y2k.tm_min = 0;
    y2k.tm_sec = 0;

    ts.tv_nsec = 0;
    ts.tv_sec = timegm(&y2k);
    if (ts.tv_sec == -1)
    	err(1, "timegm");

    if (clock_settime(CLOCK_REALTIME, &ts) == -1)
    	err(1, "clock_settime");

# ERRORS

`clock_gettime`(), `clock_settime`(), and `clock_getres`() will fail if:

[`EINVAL`]
  The clock is invalid.
[`EFAULT`]
  now or res reference invalid memory.

In addition, `clock_settime`() may return the following errors:

[`EPERM`]
  A user other than the superuser attempted to set the time.
[`EINVAL`]
  The clock is not `CLOCK_REALTIME`.
[`EINVAL`]
  now specifies a nanosecond value less than zero or greater than or equal to one billion.
[`EINVAL`]
  now specifies a value outside the range of the given clock.

# SEE ALSO

date(1), adjtime(2), getitimer(2), gettimeofday(2), clock_getcpuclockid(3), ctime(3), pthread_getcpuclockid(3), strftime(3), time(3), timespecadd(3), securelevel(7)

# STANDARDS

The `clock_gettime`(), `clock_settime`(), and `clock_getres`() functions conform to IEEE Std 1003.1-2008 (“POSIX.1”).

The `CLOCK_BOOTTIME` and `CLOCK_UPTIME` clocks are extensions to that specification.

# HISTORY

The `clock_gettime`(), `clock_settime`(), and `clock_getres`() functions and the `CLOCK_REALTIME` clock first appeared in IEEE Std 1003.1b-1993 (“POSIX.1b”) and were first available in OpenBSD 2.1.

The `CLOCK_MONOTONIC` clock first appeared in IEEE Std 1003.1j-2000 ("POSIX.1j") and was first available in OpenBSD 3.4.

The `CLOCK_PROCESS_CPUTIME_ID` and `CLOCK_THREAD_CPUTIME_ID` clocks first appeared in IEEE Std 1003.1d-1999 ("POSIX.1d") and were first available in OpenBSD 5.4.

The `CLOCK_UPTIME` clock first appeared in FreeBSD 7.0 and was first available in OpenBSD 5.5.

The `CLOCK_BOOTTIME` clock first appeared in Linux 2.6.39 and was first available in OpenBSD 6.3.

March 31, 2022 | Debian