diff options
Diffstat (limited to 'man/man2/gettimeofday.2')
| -rw-r--r-- | man/man2/gettimeofday.2 | 296 |
1 files changed, 296 insertions, 0 deletions
diff --git a/man/man2/gettimeofday.2 b/man/man2/gettimeofday.2 new file mode 100644 index 000000000..e0231e230 --- /dev/null +++ b/man/man2/gettimeofday.2 @@ -0,0 +1,296 @@ +.\" Copyright (c) 1992 Drew Eckhardt (drew@cs.colorado.edu), March 28, 1992 +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.\" 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@gmail.com> +.\" Added notes on capability requirement. +.\" +.TH gettimeofday 2 (date) "Linux man-pages (unreleased)" +.SH NAME +gettimeofday, settimeofday \- get / set time +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include <sys/time.h> +.P +.BI "int gettimeofday(struct timeval *restrict " tv , +.BI " struct timezone *_Nullable restrict " tz ); +.BI "int settimeofday(const struct timeval *" tv , +.BI " const struct timezone *_Nullable " tz ); +.fi +.P +.RS -4 +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.RE +.P +.BR settimeofday (): +.nf + Since glibc 2.19: + _DEFAULT_SOURCE + glibc 2.19 and earlier: + _BSD_SOURCE +.fi +.SH DESCRIPTION +The functions +.BR gettimeofday () +and +.BR settimeofday () +can get and set the time as well as a timezone. +.P +The +.I tv +argument is a +.I struct timeval +(as specified in +.IR <sys/time.h> ): +.P +.in +4n +.EX +struct timeval { + time_t tv_sec; /* seconds */ + suseconds_t tv_usec; /* microseconds */ +}; +.EE +.in +.P +and gives the number of seconds and microseconds since the Epoch (see +.BR time (2)). +.P +The +.I tz +argument is a +.IR "struct timezone" : +.P +.in +4n +.EX +struct timezone { + int tz_minuteswest; /* minutes west of Greenwich */ + int tz_dsttime; /* type of DST correction */ +}; +.EE +.in +.P +If either +.I tv +or +.I tz +is NULL, the corresponding structure is not set or returned. +.\" FIXME . The compilation warning looks to be going away in glibc 2.17 +.\" see glibc commit 4b7634a5e03b0da6f8875de9d3f74c1cf6f2a6e8 +(However, compilation warnings will result if +.I tv +is NULL.) +.\" The following is covered under EPERM below: +.\" .P +.\" Only the superuser may use +.\" .BR settimeofday (). +.P +The use of the +.I timezone +structure is obsolete; the +.I tz +argument should normally be specified as NULL. +(See NOTES below.) +.P +Under Linux, there are some peculiar "warp clock" semantics associated +with 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 nonzero. +(The +.I tz_dsttime +field should be zero for this case.) +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. +.SH RETURN VALUE +.BR gettimeofday () +and +.BR settimeofday () +return 0 for success. +On error, \-1 is returned and +.I errno +is set to indicate the error. +.SH ERRORS +.TP +.B EFAULT +One of +.I tv +or +.I tz +pointed outside the accessible address space. +.TP +.B EINVAL +.RB ( settimeofday ()): +.I timezone +is invalid. +.TP +.B EINVAL +.RB ( settimeofday ()): +.I tv.tv_sec +is negative or +.I tv.tv_usec +is outside the range [0, 999,999]. +.TP +.BR EINVAL " (since Linux 4.3)" +.\" commit e1d7ba8735551ed79c7a0463a042353574b96da3 +.RB ( settimeofday ()): +An attempt was made to set the time to a value less than +the current value of the +.B CLOCK_MONOTONIC +clock (see +.BR clock_gettime (2)). +.TP +.B EPERM +The calling process has insufficient privilege to call +.BR settimeofday (); +under Linux the +.B CAP_SYS_TIME +capability is required. +.SH VERSIONS +.SS C library/kernel differences +On some architectures, an implementation of +.BR gettimeofday () +is provided in the +.BR vdso (7). +.P +The kernel accepts NULL for both +.I tv +and +.IR tz . +The timezone argument is ignored by glibc and musl, +and not passed to/from the kernel. +Android's bionic passes the timezone argument to/from the kernel, +but Android does not update the kernel timezone +based on the device timezone in Settings, +so the kernel's timezone is typically UTC. +.SH STANDARDS +.TP +.BR gettimeofday () +POSIX.1-2008 (obsolete). +.TP +.BR settimeofday () +None. +.SH HISTORY +SVr4, 4.3BSD. +POSIX.1-2001 describes +.BR gettimeofday () +but not +.BR settimeofday (). +POSIX.1-2008 marks +.BR gettimeofday () +as obsolete, recommending the use of +.BR clock_gettime (2) +instead. +.P +Traditionally, the fields of +.I struct timeval +were of type +.IR long . +.\" +.SS The tz_dsttime field +On a non-Linux kernel, with glibc, the +.I tz_dsttime +field of +.I struct timezone +will be set to a nonzero value by +.BR gettimeofday () +if the current timezone has ever had or will have a daylight saving +rule applied. +In this sense it exactly mirrors the meaning of +.BR daylight (3) +for the current zone. +On Linux, with glibc, the setting of the +.I tz_dsttime +field of +.I struct timezone +has never been used by +.BR settimeofday () +or +.BR gettimeofday (). +.\" 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 historical interest. +.P +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: +.P +.in +4n +.EX +\fBDST_NONE\fP /* not on DST */ +\fBDST_USA\fP /* USA style DST */ +\fBDST_AUST\fP /* Australian style DST */ +\fBDST_WET\fP /* Western European DST */ +\fBDST_MET\fP /* Middle European DST */ +\fBDST_EET\fP /* Eastern European DST */ +\fBDST_CAN\fP /* Canada */ +\fBDST_GB\fP /* Great Britain and Eire */ +\fBDST_RUM\fP /* Romania */ +\fBDST_TUR\fP /* Turkey */ +\fBDST_AUSTALT\fP /* Australian style with shift in 1986 */ +.EE +.in +.P +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. +.SH NOTES +The time returned by +.BR gettimeofday () +.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). +.P +Macros for operating on +.I timeval +structures are described in +.BR timeradd (3). +.SH SEE ALSO +.BR date (1), +.BR adjtimex (2), +.BR clock_gettime (2), +.BR time (2), +.BR ctime (3), +.BR ftime (3), +.BR timeradd (3), +.BR capabilities (7), +.BR time (7), +.BR vdso (7), +.BR hwclock (8) |