OpenBSD manual page server

Manual Page Search Parameters
CLOCK_GETTIME(2) System Calls Manual CLOCK_GETTIME(2)

clock_gettime, clock_settime, clock_getres — get or set the time

#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);

The () 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:

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).
The monotonic clock. Its absolute value is meaningless. The clock begins at an undefined positive point and advances continuously.
The uptime clock. Its absolute value is the time elapsed since the system booted. The clock begins at zero and advances continuously.
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.
The process CPU clock. Its absolute value begins at zero and advances while the calling process is running in user or kernel mode.
The thread CPU clock. Its absolute value begins at zero and advances while the calling thread is running in user or kernel mode.

The () 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 () 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 */
};

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.

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");

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

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

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

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

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

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.

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.

October 25, 2020 OpenBSD-current