# gettimeofday

## NAME



           gettimeofday, settimeofday - get / set time
    


## LIBRARY



           Standard C library (_libc_ , _-lc_)
    


## SYNOPSIS



           **#include <sys/time.h>**
    
           **int gettimeofday(struct timeval *restrict** _tv_**,**
                            **struct timezone *_Nullable restrict** _tz_**);**
           **int settimeofday(const struct timeval ***_tv_**,**
                            **const struct timezone *_Nullable** _tz_**);**
    
       Feature Test Macro Requirements for glibc (see
       feature_test_macros(7)):
    
           **settimeofday**():
               Since glibc 2.19:
                   _DEFAULT_SOURCE
               glibc 2.19 and earlier:
                   _BSD_SOURCE
    


## DESCRIPTION



           The functions **gettimeofday**() and **settimeofday**() can get and set
           the time as well as a timezone.
    
           The _tv_ argument is a _struct timeval_ (as specified in
           _< sys/time.h>_):
    
               struct timeval {
                   time_t      tv_sec;     /* seconds */
                   suseconds_t tv_usec;    /* microseconds */
               };
    
           and gives the number of seconds and microseconds since the Epoch
           (see time(2)).
    
           The _tz_ argument is a _struct timezone_ :
    
               struct timezone {
                   int tz_minuteswest;     /* minutes west of Greenwich */
                   int tz_dsttime;         /* type of DST correction */
               };
    
           If either _tv_ or _tz_ is NULL, the corresponding structure is not set
           or returned.  (However, compilation warnings will result if _tv_ is
           NULL.)
    
           The use of the _timezone_ structure is obsolete; the _tz_ argument
           should normally be specified as NULL.  See VERSIONS.
    
           Under Linux, there are some peculiar "warp clock" semantics
           associated with the **settimeofday**() system call if on the very
           first call (after booting) that has a non-NULL _tz_ argument, the _tv_
           argument is NULL and the _tz_minuteswest_ field is nonzero.  (The
           _tz_dsttime_ field should be zero for this case.)  In such a case it
           is assumed that the CMOS clock is on local time, and that it has
           to be incremented by this amount to get UTC system time.  No doubt
           it is a bad idea to use this feature.
    


## RETURN VALUE



           **gettimeofday**() and **settimeofday**() return 0 for success.  On error,
           -1 is returned and _errno_ is set to indicate the error.
    


## ERRORS



           **EFAULT** One of _tv_ or _tz_ pointed outside the accessible address
                  space.
    
           **EINVAL**(**settimeofday**()): _timezone_ is invalid.
    
           **EINVAL**(**settimeofday**()): _tv.tv_sec_ is negative or _tv.tv_usec_ is
                  outside the range [0, 999,999].
    
           **EINVAL**(since Linux 4.3)
                  (**settimeofday**()): An attempt was made to set the time to a
                  value less than the current value of the **CLOCK_MONOTONIC**
                  clock (see clock_gettime(2)).
    
           **EPERM** The calling process has insufficient privilege to call
                  **settimeofday**(); under Linux the **CAP_SYS_TIME** capability is
                  required.
    


## VERSIONS



       **C library/kernel differences**
           On some architectures, an implementation of **gettimeofday**() is
           provided in the vdso(7).
    
           The kernel accepts NULL for both _tv_ and _tz_.  The timezone argument
           is ignored by glibc and musl, and not passed to/from the kernel.
           Android's bionic passes the timezone argument to/from the kernel,
           but Android does not update the kernel timezone based on the
           device timezone in Settings, so the kernel's timezone is typically
           UTC.
    


## STANDARDS



           **gettimeofday**()
                  POSIX.1-2008 (obsolete).
    
           **settimeofday**()
                  None.
    


## NOTES



           The time returned by **gettimeofday**() _is_ affected by discontinuous
           jumps in the system time (e.g., if the system administrator
           manually changes the system time).  If you need a monotonically
           increasing clock, see clock_gettime(2).
    
           Macros for operating on _timeval_ structures are described in
           timeradd(3).
    


* * *