./_Man_SunOS_4.1.3_html/html2/gettimeofday.2.html

Manual page for GETTIMEOFDAY(2)

gettimeofday, settimeofday - get or set the date and time

SYNOPSIS

#include <sys/time.h>

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

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

DESCRIPTION

The system's notion of the current Greenwich time and the current time zone is obtained with the gettimeofday() call, and set with the settimeofday() call. The current time is expressed in elapsed seconds and microseconds since 00:00 GMT, January 1, 1970 (zero hour). The resolution of the system clock is hardware dependent; the time may be updated continuously, or in ``ticks.''

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

tzp points to a timezone() structure, which includes the following members:

int	tz_minuteswest;	/* of Greenwich */
int	tz_dsttime;	/* type of dst correction to apply */

The timezone() structure indicates the local time zone (measured in minutes westward from Greenwich), and a flag that indicates the type of Daylight Saving Time correction to apply. Note: this flag does not indicate whether Daylight Saving Time is currently in effect.

Also note that the offset of the local time zone from GMT may change over time, as may the rules for Daylight Saving Time correction. The localtime() routine (see ctime.3v obtains this information from a file rather than from gettimeofday(). Programs should use localtime() to convert dates and times; the timezone() structure is filled in by gettimeofday() for backward compatibility with existing programs.

The flag indicating the type of Daylight Saving Time correction should have one of the following values (as defined in <sys/time.h>):

0: DST_NONE: Daylight Savings Time not observed
1: DST_USA: United States DST
2: DST_AUST: Australian DST
3: DST_WET: Western European DST
4: DST_MET: Middle European DST
5: DST_EET: Eastern European DST
6: DST_CAN: Canadian DST
7: DST_GB: Great Britain and Eire DST
8: DST_RUM: Rumanian DST
9: DST_TUR: Turkish DST
10: DST_AUSTALT: Australian-style DST with shift in 1986

If tzp is a NULL pointer, the time zone information is not returned or set.

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

RETURN VALUES

gettimeofday() returns:

0: on success.
-1: on failure and sets errno to indicate the error.

ERRORS

EFAULT: An argument address referenced invalid memory.
EPERM: A user other than the super-user attempted to set the time or time zone.

BUGS

Time is never correct enough to believe the microsecond values. There should a mechanism by which, at least, local clusters of systems might synchronize their clocks to millisecond granularity.