.TH TIME  2
.UC 4
.SH NAME
gettimeofday, time, settimeofday, stime \- get / set time
.SH SYNOPSIS
.nf
.B #include <sys/types.h>
.B #include <unistd.h>
.B time_t time (time_t *t);
.B int stime (const time_t *t);
.B int gettimeofday (struct timeval *tv, struct timezone *tz);
.B int settimeofday (const struct timeval *tv,
.ti 25
.B const struct timezone *tz);
.fi
.SH DESCRIPTION
.B time()
sets the variable pointed to by
.I t
to the time elapsed since the Epoch in seconds, and returns this value.
.PP
.B  stime()
sets system time to the value pointed to by 
.I t,
returning 0 on success, and a negative number on failure.  
.B stime() 
may only be executed by the super user.
.PP 
.B gettimeofday()
and
.B settimeofday()
can set the time as well as a timezone.      
.I tv
is a 
.B timeval 
struct, as specififed  in /usr/include/sys/time.h:
.br
.nf
struct timeval {
.in 22
long	tv_sec;		/* seconds */
long	tv_usec;	/* microseconds */
};
.in 10
.fi
.PP
and 
.I tz
is a 
.B timezone 
:
.br
.nf
struct timezone {
.in 23
int	tz_minuteswest;
/* minutes west of Greenwich */
int	tz_dsttime;
/* type of dst correction */
};
.in 10
.fi
.PP
With daylight savings times defined as follows : 
.PP
.B DST_NONE
/* not on dst */
.br
.B DST_USA	
/* USA style dst */
.br
.B DST_AUST	
/* Australian style dst */
.br
.B DST_WET
/* Western European dst */
.br
.B DST_MET
/* Middle European dst */
.br
.B DST_EET
/* Eastern European dst */
.br
.B DST_CAN
/* Canada */
.br
.B DST_GB	
/* Great Britain and Eire */
.br
.B DST_RUM
/* Rumania */
.br
.B  DST_TUR
/* Turkey */
.br
.B DST_AUSTALT	
/* Australian style with shift in 1986 */
.PP
And the following macros are defined to operate on this :
.br
.nf
#define FD_SET(fd,fdsetp)	(*(fdsetp) |= (1 << (fd)))
#define FD_CLR(fd,fdsetp)	(*(fdsetp) &= ~(1 << (fd)))
#define FD_ISSET(fd,fdsetp)	((*(fdsetp) >> fd) & 1)
#define FD_ZERO(fdsetp)		(*(fdsetp) = 0)
#define	timerisset(tvp)\\
.ti 18
((tvp)->tv_sec || (tvp)->tv_usec)
#define	timercmp(tvp, uvp, cmp)\\
.in 18
((tvp)->tv_sec cmp (uvp)->tv_sec ||\\
(tvp)->tv_sec == (uvp)->tv_sec &&\\
(tvp)->tv_usec cmp (uvp)->tv_usec)
.in 10
#define timerclear(tvp)
.ti 18
((tvp)->tv_sec = (tvp)->tv_usec = 0)
.fi
.PP
Like 
.B stime(),
only the super user is permitted to use settime().  If either
.I tv
or 
.I tz
is null, then it is not set.
.SH ERRORS
.B -EPERM 
is returned if either
.B stime() 
or
.B settimeofday()
is called by someone other than the superuser.
.PP
.B -EINVAL
may be returned if an invalid timezone, etc is specified.
.SH FILES 
linux/kernel/sys.c
.br
linux/kernel/sched.c
.br
/usr/include/linux/sys.h
.br
/usr/include/unistd.h
.SH BUGS
Linux currently is hazy about GMT and local time.  
timercmp
does not work for >= or <=.