Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
GETTIMEOFDAY(2)		  FreeBSD System Calls Manual	       GETTIMEOFDAY(2)

NAME
     gettimeofday, settimeofday	-- get/set date	and time

SYNOPSIS
     #include <sys/time.h>

     int
     gettimeofday(struct timeval *tp, struct timezone *tzp);

     int
     settimeofday(const	struct timeval *tp, const struct timezone *tzp);

DESCRIPTION
     The system's notion of the	current	Greenwich time is obtained with	the
     gettimeofday() call and set with the settimeofday() call.	The time is
     expressed in seconds and microseconds since midnight (0 hour), January 1,
     1970.  The	resolution of the system clock is hardware dependent, and the
     time may be updated continuously or in "ticks".  If tp is NULL, the time
     will not be returned or set.  The structure pointed to by tp is defined
     in	<sys/time.h> as:

     struct timeval {
	     time_t	     tv_sec;	     /*	seconds	since Jan. 1, 1970 */
	     suseconds_t     tv_usec;	     /*	and microseconds */
     };

     The tzp parameter is historical and timezone information is no longer
     tracked by	the system.  All code should pass NULL for tzp.	 For
     gettimeofday(), if	tzp is non-NULL	an empty timezone structure will be
     returned.	For settimeofday(), if tzp is non-NULL its contents are	ig-
     nored.

     Only the superuser	may set	the time of day.  If the system	securelevel is
     greater than 1 (see init(8)), the time may	only be	advanced.  This	limi-
     tation is imposed to prevent a malicious superuser	from setting arbitrary
     time stamps on files.  The	system time can	still be adjusted backwards
     using the adjtime(2) system call even when	the system is secure.

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 succeed unless:

     [EFAULT]		An argument address referenced invalid memory.

     In	addition, settimeofday() may return the	following errors:

     [EINVAL]		tp specified a microsecond value less than zero	or
			greater	than or	equal to 1 million.

     [EPERM]		A user other than the superuser	attempted to set the
			time.

SEE ALSO
     date(1), adjtime(2), clock_gettime(2), getitimer(2), ctime(3), time(3)

STANDARDS
     The gettimeofday()	function conforms to IEEE Std 1003.1-2008 ("POSIX.1").

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.

FreeBSD	13.0		       September 4, 2019		  FreeBSD 13.0

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUES | ERRORS | SEE ALSO | STANDARDS | HISTORY | CAVEATS

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=gettimeofday&sektion=2&manpath=OpenBSD+6.9>

home | help