diff options
Diffstat (limited to 'man2/gettimeofday.2')
| -rw-r--r-- | man2/gettimeofday.2 | 228 |
1 files changed, 228 insertions, 0 deletions
diff --git a/man2/gettimeofday.2 b/man2/gettimeofday.2 new file mode 100644 index 000000000..eafd7df55 --- /dev/null +++ b/man2/gettimeofday.2 @@ -0,0 +1,228 @@ +.\" 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 <mtk16@ext.canterbury.ac.nz> +.\" 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 +.B gettimeofday +and +.B settimeofday +can get and set the time as well as a timezone. +The +.I tv +argument is a +.B timeval +struct, as specified in <sys/time.h>: +.sp +.nf +struct timeval { +.in +8 +time_t tv_sec; /* seconds */ +suseconds_t tv_usec; /* microseconds */ +.in -8 +}; +.fi +.sp +and gives the number of seconds and microseconds since the Epoch (see +.BR time (2)). +The +.I tz +argument is a +.B timezone +: +.sp +.nf +struct timezone { +.in +8 +int tz_minuteswest; /* minutes W of Greenwich */ +int tz_dsttime; /* type of dst correction */ +.in -8 +}; +.fi +.PP +The use of the timezone struct is obsolete; 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 +.ta 14 +\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 +.B settimeofday +the +.I tz_dsttime +field should be zero. +.PP +Under Linux there is some peculiar `warp clock' semantics associated +to the +.B 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 nonzero. 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 struct timeval : +.br +.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 +.PP +If either +.I tv +or +.I tz +is null, the corresponding structure is not set or returned. +.PP +Only the super user may use +.BR settimeofday . +.SH "RETURN VALUE" +.B gettimeofday +and +.B 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 +.B 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 (either explicitly, or implicitly, by not defining +_POSIX_SOURCE or compiling with the -ansi flag). +.LP +Traditionally, the fields of struct timeval were longs. +.SH "CONFORMING TO" +SVr4, BSD 4.3. POSIX 1003.1-2001 describes gettimeofday() +but not settimeofday(). +.SH "SEE ALSO" +.BR date (1), +.BR adjtimex (2), +.BR time (2), +.BR ctime (3), +.BR ftime (3), +.BR capabilities (7) |