GETTIMEOFDAY(2) | System Calls Manual | GETTIMEOFDAY(2) |
gettimeofday
,
settimeofday
— get or set
the time of day
#include
<sys/time.h>
int
gettimeofday
(struct
timeval *now, struct
timezone *tz);
int
settimeofday
(const
struct timeval *now,
const struct timezone
*tz);
The
gettimeofday
()
function writes the absolute value of the system's Coordinated Universal
Time (UTC) clock to now unless
now is NULL
.
The UTC clock's absolute value is the time
elapsed since Jan 1 1970 00:00:00 +0000 (the Epoch). The clock normally
advances continuously, though it may jump discontinuously if a process calls
settimeofday
()
or clock_settime(2). For this
reason, gettimeofday
() is not generally suitable for
measuring elapsed time. Whenever possible, use
clock_gettime(2) to measure
elapsed time with one of the system's monotonic clocks instead.
The
settimeofday
()
function sets the system's UTC clock to the absolute value
now unless now is
NULL
. Only the superuser may set the clock. If the
system securelevel(7) is 2 or
greater, the clock may only be advanced. This limitation prevents a
malicious superuser from setting arbitrary timestamps on files. Setting the
clock cancels any ongoing adjtime(2)
adjustment.
The structure pointed to by now is defined
in <sys/time.h>
as:
struct timeval { time_t tv_sec; /* seconds */ suseconds_t tv_usec; /* and microseconds */ };
The tz argument is
historical: the system no longer maintains timezone information in the
kernel. The tz argument should always be
NULL
.
gettimeofday
()
zeroes tz if it is not NULL
.
settimeofday
() ignores the contents of
tz if it is not NULL
.
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.
gettimeofday
() and
settimeofday
() will fail if:
EFAULT
]NULL
and reference invalid memory.settimeofday
() will also fail if:
EINVAL
]EPERM
]EPERM
]date(1), adjtime(2), clock_gettime(2), getitimer(2), ctime(3), time(3), timeradd(3)
The gettimeofday
() function conforms to
IEEE Std 1003.1-2008 (“POSIX.1”).
The settimeofday
() function is
non-standard, though many systems offer it.
As predecessors of these functions, former system calls
time
() and stime
() first
appeared in Version 1 AT&T UNIX, and
ftime
() first appeared in
Version 7 AT&T UNIX. The
gettimeofday
() and
settimeofday
() system calls first appeared in
4.1cBSD.
Setting the time with settimeofday
() is
dangerous; if possible use adjtime(2)
instead. Many daemon programming techniques utilize time-delta techniques
using the results from gettimeofday
() instead of
from clock_gettime(2) on the
CLOCK_MONOTONIC
clock. Time jumps can cause these
programs to malfunction in unexpected ways. If the time must be set,
consider rebooting the machine for safety.
March 31, 2022 | OpenBSD-current |