'\" te
.\" Copyright 1989 AT&T.  Copyright (c) 1980 Regents of the University of California.  All rights reserved.  The Berkeley software License Agreement  specifies the terms and conditions for redistribution.  Copyright (c) 2003, Sun Microsystems, Inc.  All Rights Reserved.
.TH GETTIMEOFDAY 3C "Aug 1, 2003"
.SH NAME
gettimeofday, settimeofday \- get or set the date and time
.SH SYNOPSIS
.LP
.nf
#include <sys/time.h>

\fBint\fR \fBgettimeofday\fR(\fBstruct timeval *\fR\fItp\fR, \fBvoid *\fR\fItzp\fR);
.fi

.LP
.nf
\fBint\fR \fBsettimeofday\fR(\fBstruct timeval *\fR\fItp\fR, \fBvoid *\fR\fItzp\fR);
.fi

.SH DESCRIPTION
.sp
.LP
The \fBgettimeofday()\fR function gets and the \fBsettimeofday()\fR 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.
.sp
.LP
The \fItp\fR argument points to a \fBtimeval\fR structure, which includes the
following members:
.sp
.in +2
.nf
long    tv_sec;    /* seconds since Jan. 1, 1970 */
long    tv_usec;   /* and microseconds */
.fi
.in -2

.sp
.LP
If \fItp\fR is a null pointer, the current time information is not returned or
set.
.sp
.LP
The \fBTZ\fR environment variable holds time zone information. See
\fBTIMEZONE\fR(4).
.sp
.LP
The \fItzp\fR argument to \fBgettimeofday()\fR and \fBsettimeofday()\fR is
ignored.
.sp
.LP
Only privileged processes can set the time of day.
.SH RETURN VALUES
.sp
.LP
Upon successful completion, \fB0\fR is returned.  Otherwise, \fB\(mi1\fR is
returned and \fBerrno\fR is set to indicate the error.
.SH ERRORS
.sp
.LP
The \fBsettimeofday()\fR function will fail if:
.sp
.ne 2
.na
\fB\fBEINVAL\fR\fR
.ad
.RS 10n
The structure pointed to by \fItp\fR specifies an invalid time.
.RE

.sp
.ne 2
.na
\fB\fBEPERM\fR\fR
.ad
.RS 10n
The {\fBPRIV_SYS_TIME\fR} privilege was not asserted in the effective set of
the calling process.
.RE

.sp
.LP
The \fBgettimeofday()\fR function will fail for 32-bit interfaces if:
.sp
.ne 2
.na
\fB\fBEOVERFLOW\fR\fR
.ad
.RS 13n
The system time has progressed beyond 2038, thus the size of the \fBtv_sec\fR
member of the \fBtimeval\fR structure pointed to by \fItp\fR is insufficient to
hold the current time in seconds.
.RE

.SH USAGE
.sp
.LP
If the \fBtv_usec\fR member of \fItp\fR is > 500000, \fBsettimeofday()\fR
rounds the seconds upward. If the time needs to be set with better than one
second accuracy, call \fBsettimeofday()\fR for the seconds and then
\fBadjtime\fR(2) for finer accuracy.
.SH ATTRIBUTES
.sp
.LP
See \fBattributes\fR(5) for descriptions of the following attributes:
.sp

.sp
.TS
box;
c | c
l | l .
ATTRIBUTE TYPE	ATTRIBUTE VALUE
_
Interface Stability	\fBgettimeofday()\fR is Standard.
_
MT-Level	MT-Safe
.TE

.SH SEE ALSO
.sp
.LP
\fBadjtime\fR(2), \fBctime\fR(3C), \fBgethrtime\fR(3C), \fBTIMEZONE\fR(4),
\fBattributes\fR(5), \fBprivileges\fR(5), \fBstandards\fR(5)