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.