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
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
clock_settime
() (see below).CLOCK_MONOTONIC
CLOCK_BOOTTIME
CLOCK_UPTIME
CLOCK_PROCESS_CPUTIME_ID
CLOCK_THREAD_CPUTIME_ID
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 */ };
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:
In addition, clock_settime
() may return
the following errors:
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 |