]>
Commit | Line | Data |
---|---|---|
fea681da MK |
1 | .\" Copyright (c) 1992 Drew Eckhardt (drew@cs.colorado.edu), March 28, 1992 |
2 | .\" | |
93015253 | 3 | .\" %%%LICENSE_START(VERBATIM) |
fea681da MK |
4 | .\" Permission is granted to make and distribute verbatim copies of this |
5 | .\" manual provided the copyright notice and this permission notice are | |
6 | .\" preserved on all copies. | |
7 | .\" | |
8 | .\" Permission is granted to copy and distribute modified versions of this | |
9 | .\" manual under the conditions for verbatim copying, provided that the | |
10 | .\" entire resulting derived work is distributed under the terms of a | |
11 | .\" permission notice identical to this one. | |
c13182ef | 12 | .\" |
fea681da MK |
13 | .\" Since the Linux kernel and libraries are constantly changing, this |
14 | .\" manual page may be incorrect or out-of-date. The author(s) assume no | |
15 | .\" responsibility for errors or omissions, or for damages resulting from | |
16 | .\" the use of the information contained herein. The author(s) may not | |
17 | .\" have taken the same level of care in the production of this manual, | |
18 | .\" which is licensed free of charge, as they might when working | |
19 | .\" professionally. | |
c13182ef | 20 | .\" |
fea681da MK |
21 | .\" Formatted or processed versions of this manual, if unaccompanied by |
22 | .\" the source, must acknowledge the copyright and authors of this work. | |
4b72fb64 | 23 | .\" %%%LICENSE_END |
fea681da MK |
24 | .\" |
25 | .\" Modified by Michael Haardt (michael@moria.de) | |
26 | .\" Modified 1993-07-23 by Rik Faith (faith@cs.unc.edu) | |
27 | .\" Modified 1994-08-21 by Michael Chastain (mec@shell.portal.com): | |
28 | .\" Fixed necessary '#include' lines. | |
29 | .\" Modified 1995-04-15 by Michael Chastain (mec@shell.portal.com): | |
30 | .\" Added reference to adjtimex. | |
31 | .\" Removed some nonsense lines pointed out by Urs Thuermann, | |
32 | .\" (urs@isnogud.escape.de), aeb, 950722. | |
33 | .\" Modified 1997-01-14 by Austin Donnelly (and1000@debian.org): | |
34 | .\" Added return values section, and bit on EFAULT | |
35 | .\" Added clarification on timezone, aeb, 971210. | |
36 | .\" Removed "#include <unistd.h>", aeb, 010316. | |
c11b1abf | 37 | .\" Modified, 2004-05-27 by Michael Kerrisk <mtk.manpages@gmail.com> |
fea681da MK |
38 | .\" Added notes on capability requirement. |
39 | .\" | |
9ba01802 | 40 | .TH GETTIMEOFDAY 2 2019-03-06 "Linux" "Linux Programmer's Manual" |
fea681da MK |
41 | .SH NAME |
42 | gettimeofday, settimeofday \- get / set time | |
43 | .SH SYNOPSIS | |
a028f2ed | 44 | .nf |
fea681da | 45 | .B #include <sys/time.h> |
dbfe9c70 | 46 | .PP |
fea681da | 47 | .BI "int gettimeofday(struct timeval *" tv ", struct timezone *" tz ); |
dbfe9c70 | 48 | .PP |
a028f2ed MK |
49 | .BI "int settimeofday(const struct timeval *" tv \ |
50 | ", const struct timezone *" tz ); | |
a028f2ed | 51 | .fi |
dbfe9c70 | 52 | .PP |
cc4615cc MK |
53 | .in -4n |
54 | Feature Test Macro Requirements for glibc (see | |
55 | .BR feature_test_macros (7)): | |
56 | .in | |
68e4db0a | 57 | .PP |
cc4615cc | 58 | .BR settimeofday (): |
51c612fb MK |
59 | Since glibc 2.19: |
60 | _DEFAULT_SOURCE | |
61 | Glibc 2.19 and earlier: | |
62 | _BSD_SOURCE | |
fea681da MK |
63 | .SH DESCRIPTION |
64 | The functions | |
e511ffb6 | 65 | .BR gettimeofday () |
fea681da | 66 | and |
e511ffb6 | 67 | .BR settimeofday () |
fea681da | 68 | can get and set the time as well as a timezone. |
d2798763 | 69 | .PP |
c13182ef | 70 | The |
fea681da | 71 | .I tv |
c13182ef MK |
72 | argument is a |
73 | .I struct timeval | |
0425de01 | 74 | (as specified in |
8478ee02 | 75 | .IR <sys/time.h> ): |
51f5698d | 76 | .PP |
a08ea57c | 77 | .in +4n |
58c2a94b | 78 | .EX |
fea681da | 79 | struct timeval { |
1c382af4 MK |
80 | time_t tv_sec; /* seconds */ |
81 | suseconds_t tv_usec; /* microseconds */ | |
fea681da | 82 | }; |
58c2a94b | 83 | .EE |
a08ea57c | 84 | .in |
51f5698d | 85 | .PP |
fea681da MK |
86 | and gives the number of seconds and microseconds since the Epoch (see |
87 | .BR time (2)). | |
d2798763 | 88 | .PP |
c13182ef | 89 | The |
fea681da | 90 | .I tz |
c13182ef | 91 | argument is a |
8478ee02 | 92 | .IR "struct timezone" : |
51f5698d | 93 | .PP |
a08ea57c | 94 | .in +4n |
58c2a94b | 95 | .EX |
fea681da | 96 | struct timezone { |
79893ac3 MK |
97 | int tz_minuteswest; /* minutes west of Greenwich */ |
98 | int tz_dsttime; /* type of DST correction */ | |
fea681da | 99 | }; |
58c2a94b | 100 | .EE |
a08ea57c | 101 | .in |
1c382af4 MK |
102 | .PP |
103 | If either | |
104 | .I tv | |
c13182ef | 105 | or |
1c382af4 MK |
106 | .I tz |
107 | is NULL, the corresponding structure is not set or returned. | |
bea08fec | 108 | .\" FIXME . The compilation warning looks to be going away in 2.17 |
f70f94e8 | 109 | .\" see glibc commit 4b7634a5e03b0da6f8875de9d3f74c1cf6f2a6e8 |
f1e90ec4 MK |
110 | (However, compilation warnings will result if |
111 | .I tv | |
112 | is NULL.) | |
1c382af4 MK |
113 | .\" The following is covered under EPERM below: |
114 | .\" .PP | |
115 | .\" Only the superuser may use | |
116 | .\" .BR settimeofday (). | |
fea681da | 117 | .PP |
c13182ef MK |
118 | The use of the |
119 | .I timezone | |
1c382af4 MK |
120 | structure is obsolete; the |
121 | .I tz | |
7145b9a9 | 122 | argument should normally be specified as NULL. |
d5c4e197 | 123 | (See NOTES below.) |
efeece04 | 124 | .PP |
eb9a0b2f | 125 | Under Linux, there are some peculiar "warp clock" semantics associated |
d2296c22 | 126 | with the |
e511ffb6 | 127 | .BR settimeofday () |
fea681da MK |
128 | system call if on the very first call (after booting) |
129 | that has a non-NULL | |
130 | .I tz | |
131 | argument, the | |
132 | .I tv | |
133 | argument is NULL and the | |
134 | .I tz_minuteswest | |
c7094399 | 135 | field is nonzero. |
d5c4e197 MK |
136 | (The |
137 | .I tz_dsttime | |
138 | field should be zero for this case.) | |
c13182ef | 139 | In such a case it is assumed that the CMOS clock |
fea681da MK |
140 | is on local time, and that it has to be incremented by this amount |
141 | to get UTC system time. | |
142 | No doubt it is a bad idea to use this feature. | |
47297adb | 143 | .SH RETURN VALUE |
e511ffb6 | 144 | .BR gettimeofday () |
fea681da | 145 | and |
e511ffb6 | 146 | .BR settimeofday () |
fea681da MK |
147 | return 0 for success, or \-1 for failure (in which case |
148 | .I errno | |
149 | is set appropriately). | |
150 | .SH ERRORS | |
151 | .TP | |
152 | .B EFAULT | |
c13182ef | 153 | One of |
fea681da MK |
154 | .I tv |
155 | or | |
156 | .I tz | |
157 | pointed outside the accessible address space. | |
158 | .TP | |
159 | .B EINVAL | |
9a82d4d9 MK |
160 | .RB ( settimeofday ()): |
161 | .I timezone | |
162 | is invalid. | |
fea681da | 163 | .TP |
018c296c MK |
164 | .B EINVAL |
165 | .RB ( settimeofday ()): | |
166 | .I tv.tv_sec | |
167 | is negative or | |
168 | .I tv.tv_usec | |
169 | is outside the range [0..999,999]. | |
170 | .TP | |
bccacb94 MK |
171 | .BR EINVAL " (since Linux 4.3)" |
172 | .\" commit e1d7ba8735551ed79c7a0463a042353574b96da3 | |
173 | .RB ( settimeofday ()): | |
174 | An attempt was made to set the time to a value less than | |
175 | the current value of the | |
176 | .B CLOCK_MONOTONIC | |
177 | clock (see | |
178 | .BR clock_gettime (2)). | |
179 | .TP | |
fea681da | 180 | .B EPERM |
c13182ef | 181 | The calling process has insufficient privilege to call |
e511ffb6 | 182 | .BR settimeofday (); |
fea681da MK |
183 | under Linux the |
184 | .B CAP_SYS_TIME | |
185 | capability is required. | |
47297adb | 186 | .SH CONFORMING TO |
a1d5f77c MK |
187 | SVr4, 4.3BSD. |
188 | POSIX.1-2001 describes | |
189 | .BR gettimeofday () | |
190 | but not | |
191 | .BR settimeofday (). | |
f428c08a MK |
192 | POSIX.1-2008 marks |
193 | .BR gettimeofday () | |
4c9f4bc8 | 194 | as obsolete, recommending the use of |
3f372391 MK |
195 | .BR clock_gettime (2) |
196 | instead. | |
19c98696 | 197 | .SH NOTES |
5f04b948 | 198 | The time returned by |
77b28318 | 199 | .BR gettimeofday () |
5f04b948 MK |
200 | .I is |
201 | affected by discontinuous jumps in the system time | |
202 | (e.g., if the system administrator manually changes the system time). | |
203 | If you need a monotonically increasing clock, see | |
204 | .BR clock_gettime (2). | |
efeece04 | 205 | .PP |
d5c4e197 MK |
206 | Macros for operating on |
207 | .I timeval | |
208 | structures are described in | |
209 | .BR timeradd (3). | |
efeece04 | 210 | .PP |
c13182ef MK |
211 | Traditionally, the fields of |
212 | .I struct timeval | |
e3e25559 MK |
213 | were of type |
214 | .IR long . | |
53e0c293 | 215 | .\" |
5e0083d2 MK |
216 | .SS C library/kernel differences |
217 | On some architectures, an implementation of | |
218 | .BR gettimeofday () | |
219 | is provided in the | |
220 | .BR vdso (7). | |
221 | .\" | |
53e0c293 | 222 | .SS The tz_dsttime field |
43d6713e CD |
223 | On a non-Linux kernel, with glibc, the |
224 | .I tz_dsttime | |
225 | field of | |
226 | .I struct timezone | |
53e0c293 | 227 | will be set to a nonzero value by |
43d6713e CD |
228 | .BR gettimeofday () |
229 | if the current timezone has ever had or will have a daylight saving | |
53e0c293 MK |
230 | rule applied. |
231 | In this sense it exactly mirrors the meaning of | |
43d6713e CD |
232 | .BR daylight (3) |
233 | for the current zone. | |
234 | On Linux, with glibc, the setting of the | |
d5c4e197 | 235 | .I tz_dsttime |
43d6713e CD |
236 | field of |
237 | .I struct timezone | |
238 | has never been used by | |
239 | .BR settimeofday () | |
240 | or | |
241 | .BR gettimeofday (). | |
d5c4e197 MK |
242 | .\" it has not |
243 | .\" been and will not be supported by libc or glibc. | |
244 | .\" Each and every occurrence of this field in the kernel source | |
245 | .\" (other than the declaration) is a bug. | |
53e0c293 | 246 | Thus, the following is purely of historical interest. |
efeece04 | 247 | .PP |
d5c4e197 MK |
248 | On old systems, the field |
249 | .I tz_dsttime | |
250 | contains a symbolic constant (values are given below) | |
251 | that indicates in which part of the year Daylight Saving Time | |
252 | is in force. | |
253 | (Note: this value is constant throughout the year: | |
254 | it does not indicate that DST is in force, it just selects an | |
255 | algorithm.) | |
256 | The daylight saving time algorithms defined are as follows: | |
58c2a94b | 257 | .PP |
d5c4e197 | 258 | .in +4n |
58c2a94b | 259 | .EX |
d5c4e197 | 260 | \fBDST_NONE\fP /* not on DST */ |
d5c4e197 | 261 | \fBDST_USA\fP /* USA style DST */ |
d5c4e197 | 262 | \fBDST_AUST\fP /* Australian style DST */ |
d5c4e197 | 263 | \fBDST_WET\fP /* Western European DST */ |
d5c4e197 | 264 | \fBDST_MET\fP /* Middle European DST */ |
d5c4e197 | 265 | \fBDST_EET\fP /* Eastern European DST */ |
d5c4e197 | 266 | \fBDST_CAN\fP /* Canada */ |
d5c4e197 | 267 | \fBDST_GB\fP /* Great Britain and Eire */ |
d5c4e197 | 268 | \fBDST_RUM\fP /* Romania */ |
d5c4e197 | 269 | \fBDST_TUR\fP /* Turkey */ |
d5c4e197 | 270 | \fBDST_AUSTALT\fP /* Australian style with shift in 1986 */ |
58c2a94b | 271 | .EE |
d5c4e197 MK |
272 | .in |
273 | .PP | |
274 | Of course it turned out that the period in which | |
275 | Daylight Saving Time is in force cannot be given | |
276 | by a simple algorithm, one per country; indeed, | |
277 | this period is determined by unpredictable political | |
278 | decisions. | |
279 | So this method of representing timezones | |
280 | has been abandoned. | |
47297adb | 281 | .SH SEE ALSO |
fea681da MK |
282 | .BR date (1), |
283 | .BR adjtimex (2), | |
fb6fc612 | 284 | .BR clock_gettime (2), |
fea681da MK |
285 | .BR time (2), |
286 | .BR ctime (3), | |
287 | .BR ftime (3), | |
d5c4e197 | 288 | .BR timeradd (3), |
eafd5ce1 | 289 | .BR capabilities (7), |
7032b90a | 290 | .BR time (7), |
1ce611a3 MK |
291 | .BR vdso (7), |
292 | .BR hwclock (8) |