| .\" Copyright (c) 1992 Drew Eckhardt (drew@cs.colorado.edu), March 28, 1992 |
| .\" |
| .\" %%%LICENSE_START(VERBATIM) |
| .\" 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. |
| .\" %%%LICENSE_END |
| .\" |
| .\" 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 2021-03-22 "Linux" "Linux Programmer's Manual" |
| .SH NAME |
| gettimeofday, settimeofday \- get / set time |
| .SH SYNOPSIS |
| .nf |
| .B #include <sys/time.h> |
| .PP |
| .BI "int gettimeofday(struct timeval *restrict " tv , |
| .BI " struct timezone *restrict " tz ); |
| .BI "int settimeofday(const struct timeval *" tv , |
| .BI " const struct timezone *" tz ); |
| .fi |
| .PP |
| .RS -4 |
| Feature Test Macro Requirements for glibc (see |
| .BR feature_test_macros (7)): |
| .RE |
| .PP |
| .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. |
| .PP |
| The |
| .I tv |
| argument is a |
| .I struct timeval |
| (as specified in |
| .IR <sys/time.h> ): |
| .PP |
| .in +4n |
| .EX |
| struct timeval { |
| time_t tv_sec; /* seconds */ |
| suseconds_t tv_usec; /* microseconds */ |
| }; |
| .EE |
| .in |
| .PP |
| and gives the number of seconds and microseconds since the Epoch (see |
| .BR time (2)). |
| .PP |
| The |
| .I tz |
| argument is a |
| .IR "struct timezone" : |
| .PP |
| .in +4n |
| .EX |
| struct timezone { |
| int tz_minuteswest; /* minutes west of Greenwich */ |
| int tz_dsttime; /* type of DST correction */ |
| }; |
| .EE |
| .in |
| .PP |
| 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 2.17 |
| .\" see glibc commit 4b7634a5e03b0da6f8875de9d3f74c1cf6f2a6e8 |
| (However, compilation warnings will result if |
| .I tv |
| is NULL.) |
| .\" 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. |
| (See NOTES below.) |
| .PP |
| 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 CONFORMING TO |
| 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. |
| .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). |
| .PP |
| Macros for operating on |
| .I timeval |
| structures are described in |
| .BR timeradd (3). |
| .PP |
| Traditionally, the fields of |
| .I struct timeval |
| were of type |
| .IR long . |
| .\" |
| .SS C library/kernel differences |
| On some architectures, an implementation of |
| .BR gettimeofday () |
| is provided in the |
| .BR vdso (7). |
| .\" |
| .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. |
| .PP |
| 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: |
| .PP |
| .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 |
| .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. |
| .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) |