mirror of https://github.com/mkerrisk/man-pages
245 lines
6.3 KiB
Groff
245 lines
6.3 KiB
Groff
.\" Hey Emacs! This file is -*- nroff -*- source.
|
|
.\"
|
|
.\" Copyright (c) 1992 Drew Eckhardt (drew@cs.colorado.edu), March 28, 1992
|
|
.\"
|
|
.\" Permission is granted to make and distribute verbatim copies of this
|
|
.\" manual provided the copyright notice and this permission notice are
|
|
.\" preserved on all copies.
|
|
.\"
|
|
.\" Permission is granted to copy and distribute modified versions of this
|
|
.\" manual under the conditions for verbatim copying, provided that the
|
|
.\" entire resulting derived work is distributed under the terms of a
|
|
.\" permission notice identical to this one.
|
|
.\"
|
|
.\" Since the Linux kernel and libraries are constantly changing, this
|
|
.\" manual page may be incorrect or out-of-date. The author(s) assume no
|
|
.\" responsibility for errors or omissions, or for damages resulting from
|
|
.\" the use of the information contained herein. The author(s) may not
|
|
.\" have taken the same level of care in the production of this manual,
|
|
.\" which is licensed free of charge, as they might when working
|
|
.\" professionally.
|
|
.\"
|
|
.\" Formatted or processed versions of this manual, if unaccompanied by
|
|
.\" the source, must acknowledge the copyright and authors of this work.
|
|
.\"
|
|
.\" Modified by Michael Haardt (michael@moria.de)
|
|
.\" Modified 1993-07-23 by Rik Faith (faith@cs.unc.edu)
|
|
.\" Modified 1994-08-21 by Michael Chastain (mec@shell.portal.com):
|
|
.\" Fixed necessary '#include' lines.
|
|
.\" Modified 1995-04-15 by Michael Chastain (mec@shell.portal.com):
|
|
.\" Added reference to adjtimex.
|
|
.\" Removed some nonsense lines pointed out by Urs Thuermann,
|
|
.\" (urs@isnogud.escape.de), aeb, 950722.
|
|
.\" Modified 1997-01-14 by Austin Donnelly (and1000@debian.org):
|
|
.\" Added return values section, and bit on EFAULT
|
|
.\" Added clarification on timezone, aeb, 971210.
|
|
.\" Removed "#include <unistd.h>", aeb, 010316.
|
|
.\" Modified, 2004-05-27 by Michael Kerrisk <mtk-manpages@gmx.net>
|
|
.\" Added notes on capability requirement.
|
|
.\"
|
|
.TH GETTIMEOFDAY 2 2004-05-27 "Linux 2.6.6" "Linux Programmer's Manual"
|
|
.SH NAME
|
|
gettimeofday, settimeofday \- get / set time
|
|
.SH SYNOPSIS
|
|
.B #include <sys/time.h>
|
|
.sp
|
|
.BI "int gettimeofday(struct timeval *" tv ", struct timezone *" tz );
|
|
.br
|
|
.BI "int settimeofday(const struct timeval *" tv
|
|
.BI ", const struct timezone *" tz );
|
|
.SH DESCRIPTION
|
|
The functions
|
|
.BR gettimeofday ()
|
|
and
|
|
.BR settimeofday ()
|
|
can get and set the time as well as a timezone.
|
|
The
|
|
.I tv
|
|
argument is a
|
|
.I struct timeval
|
|
(as specified in
|
|
.IR <sys/time.h> ):
|
|
.sp
|
|
.in +0.25i
|
|
.nf
|
|
struct timeval {
|
|
time_t tv_sec; /* seconds */
|
|
suseconds_t tv_usec; /* microseconds */
|
|
};
|
|
.fi
|
|
.in -0.25i
|
|
.sp
|
|
and gives the number of seconds and microseconds since the Epoch (see
|
|
.BR time (2)).
|
|
The
|
|
.I tz
|
|
argument is a
|
|
.IR "struct timezone" :
|
|
.sp
|
|
.in +0.25i
|
|
.nf
|
|
struct timezone {
|
|
int tz_minuteswest; /* minutes west of Greenwich */
|
|
int tz_dsttime; /* type of DST correction */
|
|
};
|
|
.fi
|
|
.in -0.25i
|
|
.PP
|
|
If either
|
|
.I tv
|
|
or
|
|
.I tz
|
|
is NULL, the corresponding structure is not set or returned.
|
|
.\" The following is covered under EPERM below:
|
|
.\" .PP
|
|
.\" Only the superuser may use
|
|
.\" .BR settimeofday ().
|
|
.PP
|
|
The use of the
|
|
.I timezone
|
|
structure is obsolete; the
|
|
.I tz
|
|
argument should normally be specified as NULL.
|
|
The
|
|
.I tz_dsttime
|
|
field has never been used under Linux; it has not
|
|
been and will not be supported by libc or glibc.
|
|
Each and every occurrence of this field in the kernel source
|
|
(other than the declaration) is a bug.
|
|
Thus, the following
|
|
is purely of historic interest.
|
|
|
|
The field
|
|
.I tz_dsttime
|
|
contains a symbolic constant (values are given below)
|
|
that indicates in which part of the year Daylight Saving Time
|
|
is in force.
|
|
(Note: its value is constant throughout the year:
|
|
it does not indicate that DST is in force, it just selects an
|
|
algorithm.)
|
|
The daylight saving time algorithms defined are as follows :
|
|
.PP
|
|
\fB DST_NONE\fP /* not on dst */
|
|
.br
|
|
\fB DST_USA\fP /* USA style dst */
|
|
.br
|
|
\fB DST_AUST\fP /* Australian style dst */
|
|
.br
|
|
\fB DST_WET\fP /* Western European dst */
|
|
.br
|
|
\fB DST_MET\fP /* Middle European dst */
|
|
.br
|
|
\fB DST_EET\fP /* Eastern European dst */
|
|
.br
|
|
\fB DST_CAN\fP /* Canada */
|
|
.br
|
|
\fB DST_GB\fP /* Great Britain and Eire */
|
|
.br
|
|
\fB DST_RUM\fP /* Rumania */
|
|
.br
|
|
\fB DST_TUR\fP /* Turkey */
|
|
.br
|
|
\fB DST_AUSTALT\fP /* Australian style with shift in 1986 */
|
|
.PP
|
|
Of course it turned out that the period in which
|
|
Daylight Saving Time is in force cannot be given
|
|
by a simple algorithm, one per country; indeed,
|
|
this period is determined by unpredictable political
|
|
decisions.
|
|
So this method of representing time zones
|
|
has been abandoned.
|
|
Under Linux, in a call to
|
|
.BR settimeofday ()
|
|
the
|
|
.I tz_dsttime
|
|
field should be zero.
|
|
.PP
|
|
Under Linux there is some peculiar `warp clock' semantics associated
|
|
to the
|
|
.BR settimeofday ()
|
|
system call if on the very first call (after booting)
|
|
that has a non-NULL
|
|
.I tz
|
|
argument, the
|
|
.I tv
|
|
argument is NULL and the
|
|
.I tz_minuteswest
|
|
field is non-zero.
|
|
In such a case it is assumed that the CMOS clock
|
|
is on local time, and that it has to be incremented by this amount
|
|
to get UTC system time.
|
|
No doubt it is a bad idea to use this feature.
|
|
.PP
|
|
The following macros are defined to operate on a
|
|
.IR "struct timeval" :
|
|
.sp
|
|
.nf
|
|
#define timerisset(tvp)\\
|
|
.ti +8
|
|
((tvp)\->tv_sec || (tvp)\->tv_usec)
|
|
#define timercmp(tvp, uvp, cmp)\\
|
|
.in +8
|
|
((tvp)\->tv_sec cmp (uvp)\->tv_sec ||\\
|
|
(tvp)\->tv_sec == (uvp)\->tv_sec &&\\
|
|
(tvp)\->tv_usec cmp (uvp)\->tv_usec)
|
|
.in -8
|
|
#define timerclear(tvp)\\
|
|
.ti +8
|
|
((tvp)\->tv_sec = (tvp)\->tv_usec = 0)
|
|
.fi
|
|
.SH "RETURN VALUE"
|
|
.BR gettimeofday ()
|
|
and
|
|
.BR settimeofday ()
|
|
return 0 for success, or \-1 for failure (in which case
|
|
.I errno
|
|
is set appropriately).
|
|
.SH ERRORS
|
|
.TP
|
|
.B EFAULT
|
|
One of
|
|
.I tv
|
|
or
|
|
.I tz
|
|
pointed outside the accessible address space.
|
|
.TP
|
|
.B EINVAL
|
|
Timezone (or something else) is invalid.
|
|
.TP
|
|
.B EPERM
|
|
The calling process has insufficient privilege to call
|
|
.BR settimeofday ();
|
|
under Linux the
|
|
.B CAP_SYS_TIME
|
|
capability is required.
|
|
.SH NOTE
|
|
The prototype for
|
|
.BR settimeofday ()
|
|
and the defines for
|
|
.BR timercmp ,
|
|
.BR timerisset ,
|
|
.BR timerclear ,
|
|
.BR timeradd ,
|
|
.BR timersub
|
|
are (since glibc2.2.2) only available if
|
|
.B _BSD_SOURCE
|
|
is defined.
|
|
.LP
|
|
Traditionally, the fields of
|
|
.I struct timeval
|
|
were longs.
|
|
.SH "CONFORMING TO"
|
|
SVr4, 4.3BSD.
|
|
POSIX.1-2001 describes
|
|
.BR gettimeofday ()
|
|
but not
|
|
.BR settimeofday ().
|
|
.SH "SEE ALSO"
|
|
.BR date (1),
|
|
.BR adjtimex (2),
|
|
.BR time (2),
|
|
.BR ctime (3),
|
|
.BR ftime (3),
|
|
.BR capabilities (7),
|
|
.BR time (7)
|