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

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 p1003.1-2008.

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 p1003.1b-93 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.