]>
Commit | Line | Data |
---|---|---|
1 | .\" Copyright (c) 1992 Drew Eckhardt (drew@cs.colorado.edu), March 28, 1992 | |
2 | .\" | |
3 | .\" %%%LICENSE_START(VERBATIM) | |
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. | |
12 | .\" | |
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. | |
20 | .\" | |
21 | .\" Formatted or processed versions of this manual, if unaccompanied by | |
22 | .\" the source, must acknowledge the copyright and authors of this work. | |
23 | .\" %%%LICENSE_END | |
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. | |
37 | .\" Modified, 2004-05-27 by Michael Kerrisk <mtk.manpages@gmail.com> | |
38 | .\" Added notes on capability requirement. | |
39 | .\" | |
40 | .TH GETTIMEOFDAY 2 2019-03-06 "Linux" "Linux Programmer's Manual" | |
41 | .SH NAME | |
42 | gettimeofday, settimeofday \- get / set time | |
43 | .SH SYNOPSIS | |
44 | .nf | |
45 | .B #include <sys/time.h> | |
46 | .PP | |
47 | .BI "int gettimeofday(struct timeval *" tv ", struct timezone *" tz ); | |
48 | .PP | |
49 | .BI "int settimeofday(const struct timeval *" tv \ | |
50 | ", const struct timezone *" tz ); | |
51 | .fi | |
52 | .PP | |
53 | .in -4n | |
54 | Feature Test Macro Requirements for glibc (see | |
55 | .BR feature_test_macros (7)): | |
56 | .in | |
57 | .PP | |
58 | .BR settimeofday (): | |
59 | Since glibc 2.19: | |
60 | _DEFAULT_SOURCE | |
61 | Glibc 2.19 and earlier: | |
62 | _BSD_SOURCE | |
63 | .SH DESCRIPTION | |
64 | The functions | |
65 | .BR gettimeofday () | |
66 | and | |
67 | .BR settimeofday () | |
68 | can get and set the time as well as a timezone. | |
69 | .PP | |
70 | The | |
71 | .I tv | |
72 | argument is a | |
73 | .I struct timeval | |
74 | (as specified in | |
75 | .IR <sys/time.h> ): | |
76 | .PP | |
77 | .in +4n | |
78 | .EX | |
79 | struct timeval { | |
80 | time_t tv_sec; /* seconds */ | |
81 | suseconds_t tv_usec; /* microseconds */ | |
82 | }; | |
83 | .EE | |
84 | .in | |
85 | .PP | |
86 | and gives the number of seconds and microseconds since the Epoch (see | |
87 | .BR time (2)). | |
88 | .PP | |
89 | The | |
90 | .I tz | |
91 | argument is a | |
92 | .IR "struct timezone" : | |
93 | .PP | |
94 | .in +4n | |
95 | .EX | |
96 | struct timezone { | |
97 | int tz_minuteswest; /* minutes west of Greenwich */ | |
98 | int tz_dsttime; /* type of DST correction */ | |
99 | }; | |
100 | .EE | |
101 | .in | |
102 | .PP | |
103 | If either | |
104 | .I tv | |
105 | or | |
106 | .I tz | |
107 | is NULL, the corresponding structure is not set or returned. | |
108 | .\" FIXME . The compilation warning looks to be going away in 2.17 | |
109 | .\" see glibc commit 4b7634a5e03b0da6f8875de9d3f74c1cf6f2a6e8 | |
110 | (However, compilation warnings will result if | |
111 | .I tv | |
112 | is NULL.) | |
113 | .\" The following is covered under EPERM below: | |
114 | .\" .PP | |
115 | .\" Only the superuser may use | |
116 | .\" .BR settimeofday (). | |
117 | .PP | |
118 | The use of the | |
119 | .I timezone | |
120 | structure is obsolete; the | |
121 | .I tz | |
122 | argument should normally be specified as NULL. | |
123 | (See NOTES below.) | |
124 | .PP | |
125 | Under Linux, there are some peculiar "warp clock" semantics associated | |
126 | with the | |
127 | .BR settimeofday () | |
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 | |
135 | field is nonzero. | |
136 | (The | |
137 | .I tz_dsttime | |
138 | field should be zero for this case.) | |
139 | In such a case it is assumed that the CMOS clock | |
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. | |
143 | .SH RETURN VALUE | |
144 | .BR gettimeofday () | |
145 | and | |
146 | .BR settimeofday () | |
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 | |
153 | One of | |
154 | .I tv | |
155 | or | |
156 | .I tz | |
157 | pointed outside the accessible address space. | |
158 | .TP | |
159 | .B EINVAL | |
160 | .RB ( settimeofday ()): | |
161 | .I timezone | |
162 | is invalid. | |
163 | .TP | |
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 | |
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 | |
180 | .B EPERM | |
181 | The calling process has insufficient privilege to call | |
182 | .BR settimeofday (); | |
183 | under Linux the | |
184 | .B CAP_SYS_TIME | |
185 | capability is required. | |
186 | .SH CONFORMING TO | |
187 | SVr4, 4.3BSD. | |
188 | POSIX.1-2001 describes | |
189 | .BR gettimeofday () | |
190 | but not | |
191 | .BR settimeofday (). | |
192 | POSIX.1-2008 marks | |
193 | .BR gettimeofday () | |
194 | as obsolete, recommending the use of | |
195 | .BR clock_gettime (2) | |
196 | instead. | |
197 | .SH NOTES | |
198 | The time returned by | |
199 | .BR gettimeofday () | |
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). | |
205 | .PP | |
206 | Macros for operating on | |
207 | .I timeval | |
208 | structures are described in | |
209 | .BR timeradd (3). | |
210 | .PP | |
211 | Traditionally, the fields of | |
212 | .I struct timeval | |
213 | were of type | |
214 | .IR long . | |
215 | .\" | |
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 | .\" | |
222 | .SS The tz_dsttime field | |
223 | On a non-Linux kernel, with glibc, the | |
224 | .I tz_dsttime | |
225 | field of | |
226 | .I struct timezone | |
227 | will be set to a nonzero value by | |
228 | .BR gettimeofday () | |
229 | if the current timezone has ever had or will have a daylight saving | |
230 | rule applied. | |
231 | In this sense it exactly mirrors the meaning of | |
232 | .BR daylight (3) | |
233 | for the current zone. | |
234 | On Linux, with glibc, the setting of the | |
235 | .I tz_dsttime | |
236 | field of | |
237 | .I struct timezone | |
238 | has never been used by | |
239 | .BR settimeofday () | |
240 | or | |
241 | .BR gettimeofday (). | |
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. | |
246 | Thus, the following is purely of historical interest. | |
247 | .PP | |
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: | |
257 | .PP | |
258 | .in +4n | |
259 | .EX | |
260 | \fBDST_NONE\fP /* not on DST */ | |
261 | \fBDST_USA\fP /* USA style DST */ | |
262 | \fBDST_AUST\fP /* Australian style DST */ | |
263 | \fBDST_WET\fP /* Western European DST */ | |
264 | \fBDST_MET\fP /* Middle European DST */ | |
265 | \fBDST_EET\fP /* Eastern European DST */ | |
266 | \fBDST_CAN\fP /* Canada */ | |
267 | \fBDST_GB\fP /* Great Britain and Eire */ | |
268 | \fBDST_RUM\fP /* Romania */ | |
269 | \fBDST_TUR\fP /* Turkey */ | |
270 | \fBDST_AUSTALT\fP /* Australian style with shift in 1986 */ | |
271 | .EE | |
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. | |
281 | .SH SEE ALSO | |
282 | .BR date (1), | |
283 | .BR adjtimex (2), | |
284 | .BR clock_gettime (2), | |
285 | .BR time (2), | |
286 | .BR ctime (3), | |
287 | .BR ftime (3), | |
288 | .BR timeradd (3), | |
289 | .BR capabilities (7), | |
290 | .BR time (7), | |
291 | .BR vdso (7), | |
292 | .BR hwclock (8) |