GETTIMEOFDAY(2) | System Calls Manual | GETTIMEOFDAY(2)

# 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.

March 31, 2022 | Debian