NAME
gettimeofday
,
settimeofday
—
get or set the time of day
SYNOPSIS
#include
<sys/time.h>
int
gettimeofday
(struct
timeval *now, struct
timezone *tz);
int
settimeofday
(const
struct timeval *now,
const struct timezone
*tz);
DESCRIPTION
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
.
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.
ERRORS
gettimeofday
() and
settimeofday
() will fail if:
- [
EFAULT
] - now or tz are not
NULL
and reference invalid memory.
settimeofday
() will also fail if:
- [
EINVAL
] - now specifies a microsecond value less than zero or greater than or equal to one million.
- [
EPERM
] - The caller is not the superuser.
- [
EPERM
] - The system securelevel(7) is 2 or greater and now specifies a time in the past.
SEE ALSO
date(1), adjtime(2), clock_gettime(2), getitimer(2), ctime(3), time(3), timeradd(3)
STANDARDS
The gettimeofday
() function conforms to
IEEE Std 1003.1-2008 (“POSIX.1”).
The settimeofday
() function is
non-standard, though many systems offer it.
HISTORY
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.
CAVEATS
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.