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.