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