settimeofday(3C)

NAME

     gettimeofday, settimeofday - get or set the date and time

SYNOPSIS

     #include <sys/time.h>

     int gettimeofday(struct timeval *tp, void *);

     int settimeofday(struct timeval *tp, void *);

DESCRIPTION

     The gettimeofday()  function  gets  and  the  settimeofday()
     function  sets  the system's notion of the current time. The
     current  time  is   expressed   in   elapsed   seconds   and
     microseconds since 00:00 Universal Coordinated Time, January
     1, 1970. The resolution of  the  system  clock  is  hardware
     dependent;  the time may be updated continuously or in clock
     ticks.

     The  tp  argument  points  to  a  timeval  structure,  which
     includes the following members:

     long    tv_sec;    /* seconds since Jan. 1, 1970 */
     long    tv_usec;   /* and microseconds */

     If tp is a null pointer, the current time information is not
     returned or set.

     The TZ environment variable holds time zone information. See
     TIMEZONE(4).

     The second argument to gettimeofday() and settimeofday()  is
     ignored.

     Only the super-user may set the time of day.

RETURN VALUES

     Upon successful completion, 0 is returned.  Otherwise, -1 is
     returned and errno is set to indicate the error.

ERRORS

     The gettimeofday() function will fail if:

     EINVAL
           The structure pointed to by tp  specifies  an  invalid
           time.

     EPERM A user other than the privileged user attempted to set
           the time or time zone.

     Additionally, the gettimeofday() function will fail for  32-
     bit interfaces if:
     EOVERFLOW
           The system time has progressed beyond 2038,  thus  the
           size  of  the  tv_sec  member of the timeval structure
           pointed to by tp is insufficient to hold  the  current
           time in seconds.

USAGE

     If the tv_usec member of  tp  is  >  500000,  settimeofday()
     rounds  the seconds upward. If the time needs to be set with
     better than one second accuracy, call settimeofday() for the
     seconds and then adjtime(2) for finer accuracy.

ATTRIBUTES

     See attributes(5) for descriptions of the  following  attri-
     butes:

     ____________________________________________________________
    |       ATTRIBUTE TYPE        |       ATTRIBUTE VALUE       |
    |_____________________________|_____________________________|
    | MT-Level                    | MT-Safe                     |
    |_____________________________|_____________________________|

SEE ALSO

     adjtime(2), ctime(3C), TIMEZONE(4), attributes(5)