2004-11-03 13:51:07 +00:00
|
|
|
.\" 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.
|
2007-04-12 22:42:49 +00:00
|
|
|
.\"
|
2004-11-03 13:51:07 +00:00
|
|
|
.\" 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.
|
2007-04-12 22:42:49 +00:00
|
|
|
.\"
|
2004-11-03 13:51:07 +00:00
|
|
|
.\" 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.
|
2007-09-20 06:52:22 +00:00
|
|
|
.\" Modified, 2004-05-27 by Michael Kerrisk <mtk.manpages@gmail.com>
|
2004-11-03 13:51:07 +00:00
|
|
|
.\" Added notes on capability requirement.
|
|
|
|
.\"
|
2012-04-25 20:41:05 +00:00
|
|
|
.TH GETTIMEOFDAY 2 2012-04-26 "Linux" "Linux Programmer's Manual"
|
2004-11-03 13:51:07 +00:00
|
|
|
.SH NAME
|
|
|
|
gettimeofday, settimeofday \- get / set time
|
|
|
|
.SH SYNOPSIS
|
2008-01-04 04:30:10 +00:00
|
|
|
.nf
|
2004-11-03 13:51:07 +00:00
|
|
|
.B #include <sys/time.h>
|
2008-01-04 04:30:10 +00:00
|
|
|
|
2004-11-03 13:51:07 +00:00
|
|
|
.BI "int gettimeofday(struct timeval *" tv ", struct timezone *" tz );
|
2008-01-04 04:30:10 +00:00
|
|
|
|
|
|
|
.BI "int settimeofday(const struct timeval *" tv \
|
|
|
|
", const struct timezone *" tz );
|
|
|
|
|
|
|
|
.fi
|
2007-07-08 12:11:40 +00:00
|
|
|
.in -4n
|
|
|
|
Feature Test Macro Requirements for glibc (see
|
|
|
|
.BR feature_test_macros (7)):
|
|
|
|
.in
|
|
|
|
.sp
|
|
|
|
.BR settimeofday ():
|
|
|
|
_BSD_SOURCE
|
2004-11-03 13:51:07 +00:00
|
|
|
.SH DESCRIPTION
|
|
|
|
The functions
|
2005-10-19 06:54:38 +00:00
|
|
|
.BR gettimeofday ()
|
2004-11-03 13:51:07 +00:00
|
|
|
and
|
2005-10-19 06:54:38 +00:00
|
|
|
.BR settimeofday ()
|
2004-11-03 13:51:07 +00:00
|
|
|
can get and set the time as well as a timezone.
|
2007-04-12 22:42:49 +00:00
|
|
|
The
|
2004-11-03 13:51:07 +00:00
|
|
|
.I tv
|
2007-04-12 22:42:49 +00:00
|
|
|
argument is a
|
|
|
|
.I struct timeval
|
2008-07-01 14:15:13 +00:00
|
|
|
(as specified in
|
2005-11-02 13:55:25 +00:00
|
|
|
.IR <sys/time.h> ):
|
2004-11-03 13:51:07 +00:00
|
|
|
.sp
|
2007-12-19 05:53:30 +00:00
|
|
|
.in +4n
|
2004-11-03 13:51:07 +00:00
|
|
|
.nf
|
|
|
|
struct timeval {
|
2006-04-20 21:07:10 +00:00
|
|
|
time_t tv_sec; /* seconds */
|
|
|
|
suseconds_t tv_usec; /* microseconds */
|
2004-11-03 13:51:07 +00:00
|
|
|
};
|
|
|
|
.fi
|
2007-12-19 05:53:30 +00:00
|
|
|
.in
|
2004-11-03 13:51:07 +00:00
|
|
|
.sp
|
|
|
|
and gives the number of seconds and microseconds since the Epoch (see
|
|
|
|
.BR time (2)).
|
2007-04-12 22:42:49 +00:00
|
|
|
The
|
2004-11-03 13:51:07 +00:00
|
|
|
.I tz
|
2007-04-12 22:42:49 +00:00
|
|
|
argument is a
|
2005-11-02 13:55:25 +00:00
|
|
|
.IR "struct timezone" :
|
2004-11-03 13:51:07 +00:00
|
|
|
.sp
|
2007-12-19 05:53:30 +00:00
|
|
|
.in +4n
|
2004-11-03 13:51:07 +00:00
|
|
|
.nf
|
|
|
|
struct timezone {
|
2006-04-26 06:51:15 +00:00
|
|
|
int tz_minuteswest; /* minutes west of Greenwich */
|
|
|
|
int tz_dsttime; /* type of DST correction */
|
2004-11-03 13:51:07 +00:00
|
|
|
};
|
|
|
|
.fi
|
2007-12-19 05:53:30 +00:00
|
|
|
.in
|
2006-04-20 21:07:10 +00:00
|
|
|
.PP
|
|
|
|
If either
|
|
|
|
.I tv
|
2007-04-12 22:42:49 +00:00
|
|
|
or
|
2006-04-20 21:07:10 +00:00
|
|
|
.I tz
|
|
|
|
is NULL, the corresponding structure is not set or returned.
|
2012-04-12 01:16:49 +00:00
|
|
|
(However, compilation warnings will result if
|
|
|
|
.I tv
|
|
|
|
is NULL.)
|
2006-04-20 21:07:10 +00:00
|
|
|
.\" The following is covered under EPERM below:
|
|
|
|
.\" .PP
|
|
|
|
.\" Only the superuser may use
|
|
|
|
.\" .BR settimeofday ().
|
2004-11-03 13:51:07 +00:00
|
|
|
.PP
|
2007-04-12 22:42:49 +00:00
|
|
|
The use of the
|
|
|
|
.I timezone
|
2006-04-20 21:07:10 +00:00
|
|
|
structure is obsolete; the
|
|
|
|
.I tz
|
2006-06-03 01:26:30 +00:00
|
|
|
argument should normally be specified as NULL.
|
2012-04-12 01:10:57 +00:00
|
|
|
(See NOTES below.)
|
2004-11-03 13:51:07 +00:00
|
|
|
|
2007-12-17 17:05:09 +00:00
|
|
|
Under Linux there are some peculiar "warp clock" semantics associated
|
|
|
|
with the
|
2005-10-19 06:54:38 +00:00
|
|
|
.BR settimeofday ()
|
2004-11-03 13:51:07 +00:00
|
|
|
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
|
intro.1, time.1, adjtimex.2, capget.2, eventfd.2, fcntl.2, getrlimit.2, getsockopt.2, gettimeofday.2, intro.2, ioctl_list.2, ioperm.2, mlock.2, pivot_root.2, poll.2, prctl.2, ptrace.2, sched_setscheduler.2, select_tut.2, semget.2, sigaltstack.2, signalfd.2, sysctl.2, timer_settime.2, timerfd_create.2, wait.2, CPU_SET.3, argz_add.3, assert_perror.3, atexit.3, backtrace.3, bcmp.3, clearenv.3, ctime.3, dl_iterate_phdr.3, dlopen.3, ecvt.3, errno.3, error.3, ether_aton.3, exit.3, fenv.3, ferror.3, finite.3, flockfile.3, fnmatch.3, fpathconf.3, fpclassify.3, ftime.3, ftok.3, ftw.3, fwide.3, getaddrinfo.3, gethostbyname.3, getlogin.3, getnameinfo.3, getnetent.3, getopt.3, getprotoent.3, getrpcent.3, getservent.3, glob.3, hsearch.3, inet.3, isalpha.3, iswalnum.3, iswalpha.3, iswblank.3, iswcntrl.3, iswctype.3, iswdigit.3, iswgraph.3, iswlower.3, iswprint.3, iswpunct.3, iswspace.3, iswupper.3, iswxdigit.3, longjmp.3, lsearch.3, malloc.3, matherr.3, mblen.3, mbsinit.3, mbtowc.3, on_exit.3, printf.3, pthread_attr_init.3, pthread_attr_setaffinity_np.3, pthread_attr_setdetachstate.3, pthread_attr_setguardsize.3, pthread_attr_setinheritsched.3, pthread_attr_setschedparam.3, pthread_attr_setschedpolicy.3, pthread_attr_setscope.3, pthread_attr_setstack.3, pthread_attr_setstackaddr.3, pthread_attr_setstacksize.3, pthread_cancel.3, pthread_cleanup_push.3, pthread_equal.3, pthread_getattr_np.3, pthread_getcpuclockid.3, pthread_setaffinity_np.3, pthread_setcancelstate.3, pthread_setconcurrency.3, pthread_setschedparam.3, pthread_setschedprio.3, ptsname.3, putenv.3, putgrent.3, raise.3, rcmd.3, regex.3, rexec.3, rpc.3, rpmatch.3, rtnetlink.3, scandir.3, sem_init.3, setaliasent.3, setbuf.3, setenv.3, setjmp.3, signbit.3, stdio_ext.3, strtod.3, strtol.3, strtoul.3, system.3, termios.3, timeradd.3, tzset.3, ualarm.3, wctomb.3, xdr.3, st.4, tty_ioctl.4, core.5, elf.5, proc.5, bootparam.7, capabilities.7, icmp.7, ip.7, ipv6.7, math_error.7, mdoc.samples.7, mq_overview.7, pthreads.7, raw.7, regex.7, socket.7, tcp.7, tzselect.8: Global fix: s/non-zero/nonzero/
The tendency in English, as prescribed in style guides like
Chicago MoS, is towards removing hyphens after prefixes
like "non-" etc.
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
2010-01-16 16:40:55 +00:00
|
|
|
field is nonzero.
|
2012-04-12 01:10:57 +00:00
|
|
|
(The
|
|
|
|
.I tz_dsttime
|
|
|
|
field should be zero for this case.)
|
2007-04-12 22:42:49 +00:00
|
|
|
In such a case it is assumed that the CMOS clock
|
2004-11-03 13:51:07 +00:00
|
|
|
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.
|
|
|
|
.SH "RETURN VALUE"
|
2005-10-19 06:54:38 +00:00
|
|
|
.BR gettimeofday ()
|
2004-11-03 13:51:07 +00:00
|
|
|
and
|
2005-10-19 06:54:38 +00:00
|
|
|
.BR settimeofday ()
|
2004-11-03 13:51:07 +00:00
|
|
|
return 0 for success, or \-1 for failure (in which case
|
|
|
|
.I errno
|
|
|
|
is set appropriately).
|
|
|
|
.SH ERRORS
|
|
|
|
.TP
|
|
|
|
.B EFAULT
|
2007-04-12 22:42:49 +00:00
|
|
|
One of
|
2004-11-03 13:51:07 +00:00
|
|
|
.I tv
|
|
|
|
or
|
|
|
|
.I tz
|
|
|
|
pointed outside the accessible address space.
|
|
|
|
.TP
|
|
|
|
.B EINVAL
|
|
|
|
Timezone (or something else) is invalid.
|
|
|
|
.TP
|
|
|
|
.B EPERM
|
2007-04-12 22:42:49 +00:00
|
|
|
The calling process has insufficient privilege to call
|
2005-10-19 06:54:38 +00:00
|
|
|
.BR settimeofday ();
|
2004-11-03 13:51:07 +00:00
|
|
|
under Linux the
|
|
|
|
.B CAP_SYS_TIME
|
|
|
|
capability is required.
|
2007-05-18 16:06:42 +00:00
|
|
|
.SH "CONFORMING TO"
|
|
|
|
SVr4, 4.3BSD.
|
|
|
|
POSIX.1-2001 describes
|
|
|
|
.BR gettimeofday ()
|
|
|
|
but not
|
|
|
|
.BR settimeofday ().
|
2008-08-21 06:01:46 +00:00
|
|
|
POSIX.1-2008 marks
|
|
|
|
.BR gettimeofday ()
|
2010-06-20 01:42:49 +00:00
|
|
|
as obsolete, recommending the use of
|
2009-03-14 17:53:47 +00:00
|
|
|
.BR clock_gettime (2)
|
|
|
|
instead.
|
2007-05-16 02:54:18 +00:00
|
|
|
.SH NOTES
|
2012-04-25 00:57:59 +00:00
|
|
|
The time returned by
|
|
|
|
.BR gettimeofday (2)
|
|
|
|
.I is
|
|
|
|
affected by discontinuous jumps in the system time
|
|
|
|
(e.g., if the system administrator manually changes the system time).
|
|
|
|
If you need a monotonically increasing clock, see
|
|
|
|
.BR clock_gettime (2).
|
|
|
|
|
2012-04-12 01:10:57 +00:00
|
|
|
Macros for operating on
|
|
|
|
.I timeval
|
|
|
|
structures are described in
|
|
|
|
.BR timeradd (3).
|
|
|
|
|
2007-04-12 22:42:49 +00:00
|
|
|
Traditionally, the fields of
|
|
|
|
.I struct timeval
|
2007-06-25 10:03:10 +00:00
|
|
|
were of type
|
|
|
|
.IR long .
|
2012-04-12 01:10:57 +00:00
|
|
|
|
|
|
|
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.
|
|
|
|
|
|
|
|
On old systems, 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: this 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:
|
|
|
|
.in +4n
|
|
|
|
.nf
|
|
|
|
|
|
|
|
\fBDST_NONE\fP /* not on DST */
|
|
|
|
.br
|
|
|
|
\fBDST_USA\fP /* USA style DST */
|
|
|
|
.br
|
|
|
|
\fBDST_AUST\fP /* Australian style DST */
|
|
|
|
.br
|
|
|
|
\fBDST_WET\fP /* Western European DST */
|
|
|
|
.br
|
|
|
|
\fBDST_MET\fP /* Middle European DST */
|
|
|
|
.br
|
|
|
|
\fBDST_EET\fP /* Eastern European DST */
|
|
|
|
.br
|
|
|
|
\fBDST_CAN\fP /* Canada */
|
|
|
|
.br
|
|
|
|
\fBDST_GB\fP /* Great Britain and Eire */
|
|
|
|
.br
|
|
|
|
\fBDST_RUM\fP /* Romania */
|
|
|
|
.br
|
|
|
|
\fBDST_TUR\fP /* Turkey */
|
|
|
|
.br
|
|
|
|
\fBDST_AUSTALT\fP /* Australian style with shift in 1986 */
|
|
|
|
.fi
|
|
|
|
.in
|
|
|
|
.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 timezones
|
|
|
|
has been abandoned.
|
2004-11-03 13:51:07 +00:00
|
|
|
.SH "SEE ALSO"
|
|
|
|
.BR date (1),
|
|
|
|
.BR adjtimex (2),
|
2012-04-25 00:46:32 +00:00
|
|
|
.BR clock_gettime (2),
|
2004-11-03 13:51:07 +00:00
|
|
|
.BR time (2),
|
|
|
|
.BR ctime (3),
|
|
|
|
.BR ftime (3),
|
2012-04-12 01:10:57 +00:00
|
|
|
.BR timeradd (3),
|
2006-04-26 07:26:36 +00:00
|
|
|
.BR capabilities (7),
|
|
|
|
.BR time (7)
|