]>
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 | .\" | |
35deeb87 | 40 | .TH GETTIMEOFDAY 2 2016-12-12 "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. |
c13182ef | 69 | The |
fea681da | 70 | .I tv |
c13182ef MK |
71 | argument is a |
72 | .I struct timeval | |
0425de01 | 73 | (as specified in |
8478ee02 | 74 | .IR <sys/time.h> ): |
fea681da | 75 | .sp |
a08ea57c | 76 | .in +4n |
58c2a94b | 77 | .EX |
fea681da | 78 | struct timeval { |
1c382af4 MK |
79 | time_t tv_sec; /* seconds */ |
80 | suseconds_t tv_usec; /* microseconds */ | |
fea681da | 81 | }; |
58c2a94b | 82 | .EE |
a08ea57c | 83 | .in |
fea681da MK |
84 | .sp |
85 | and gives the number of seconds and microseconds since the Epoch (see | |
86 | .BR time (2)). | |
c13182ef | 87 | The |
fea681da | 88 | .I tz |
c13182ef | 89 | argument is a |
8478ee02 | 90 | .IR "struct timezone" : |
fea681da | 91 | .sp |
a08ea57c | 92 | .in +4n |
58c2a94b | 93 | .EX |
fea681da | 94 | struct timezone { |
79893ac3 MK |
95 | int tz_minuteswest; /* minutes west of Greenwich */ |
96 | int tz_dsttime; /* type of DST correction */ | |
fea681da | 97 | }; |
58c2a94b | 98 | .EE |
a08ea57c | 99 | .in |
1c382af4 MK |
100 | .PP |
101 | If either | |
102 | .I tv | |
c13182ef | 103 | or |
1c382af4 MK |
104 | .I tz |
105 | is NULL, the corresponding structure is not set or returned. | |
bea08fec | 106 | .\" FIXME . The compilation warning looks to be going away in 2.17 |
f70f94e8 | 107 | .\" see glibc commit 4b7634a5e03b0da6f8875de9d3f74c1cf6f2a6e8 |
f1e90ec4 MK |
108 | (However, compilation warnings will result if |
109 | .I tv | |
110 | is NULL.) | |
1c382af4 MK |
111 | .\" The following is covered under EPERM below: |
112 | .\" .PP | |
113 | .\" Only the superuser may use | |
114 | .\" .BR settimeofday (). | |
fea681da | 115 | .PP |
c13182ef MK |
116 | The use of the |
117 | .I timezone | |
1c382af4 MK |
118 | structure is obsolete; the |
119 | .I tz | |
7145b9a9 | 120 | argument should normally be specified as NULL. |
d5c4e197 | 121 | (See NOTES below.) |
efeece04 | 122 | .PP |
eb9a0b2f | 123 | Under Linux, there are some peculiar "warp clock" semantics associated |
d2296c22 | 124 | with the |
e511ffb6 | 125 | .BR settimeofday () |
fea681da MK |
126 | system call if on the very first call (after booting) |
127 | that has a non-NULL | |
128 | .I tz | |
129 | argument, the | |
130 | .I tv | |
131 | argument is NULL and the | |
132 | .I tz_minuteswest | |
c7094399 | 133 | field is nonzero. |
d5c4e197 MK |
134 | (The |
135 | .I tz_dsttime | |
136 | field should be zero for this case.) | |
c13182ef | 137 | In such a case it is assumed that the CMOS clock |
fea681da MK |
138 | is on local time, and that it has to be incremented by this amount |
139 | to get UTC system time. | |
140 | No doubt it is a bad idea to use this feature. | |
47297adb | 141 | .SH RETURN VALUE |
e511ffb6 | 142 | .BR gettimeofday () |
fea681da | 143 | and |
e511ffb6 | 144 | .BR settimeofday () |
fea681da MK |
145 | return 0 for success, or \-1 for failure (in which case |
146 | .I errno | |
147 | is set appropriately). | |
148 | .SH ERRORS | |
149 | .TP | |
150 | .B EFAULT | |
c13182ef | 151 | One of |
fea681da MK |
152 | .I tv |
153 | or | |
154 | .I tz | |
155 | pointed outside the accessible address space. | |
156 | .TP | |
157 | .B EINVAL | |
158 | Timezone (or something else) is invalid. | |
159 | .TP | |
160 | .B EPERM | |
c13182ef | 161 | The calling process has insufficient privilege to call |
e511ffb6 | 162 | .BR settimeofday (); |
fea681da MK |
163 | under Linux the |
164 | .B CAP_SYS_TIME | |
165 | capability is required. | |
47297adb | 166 | .SH CONFORMING TO |
a1d5f77c MK |
167 | SVr4, 4.3BSD. |
168 | POSIX.1-2001 describes | |
169 | .BR gettimeofday () | |
170 | but not | |
171 | .BR settimeofday (). | |
f428c08a MK |
172 | POSIX.1-2008 marks |
173 | .BR gettimeofday () | |
4c9f4bc8 | 174 | as obsolete, recommending the use of |
3f372391 MK |
175 | .BR clock_gettime (2) |
176 | instead. | |
19c98696 | 177 | .SH NOTES |
5f04b948 | 178 | The time returned by |
77b28318 | 179 | .BR gettimeofday () |
5f04b948 MK |
180 | .I is |
181 | affected by discontinuous jumps in the system time | |
182 | (e.g., if the system administrator manually changes the system time). | |
183 | If you need a monotonically increasing clock, see | |
184 | .BR clock_gettime (2). | |
efeece04 | 185 | .PP |
d5c4e197 MK |
186 | Macros for operating on |
187 | .I timeval | |
188 | structures are described in | |
189 | .BR timeradd (3). | |
efeece04 | 190 | .PP |
c13182ef MK |
191 | Traditionally, the fields of |
192 | .I struct timeval | |
e3e25559 MK |
193 | were of type |
194 | .IR long . | |
53e0c293 MK |
195 | .\" |
196 | .SS The tz_dsttime field | |
43d6713e CD |
197 | On a non-Linux kernel, with glibc, the |
198 | .I tz_dsttime | |
199 | field of | |
200 | .I struct timezone | |
53e0c293 | 201 | will be set to a nonzero value by |
43d6713e CD |
202 | .BR gettimeofday () |
203 | if the current timezone has ever had or will have a daylight saving | |
53e0c293 MK |
204 | rule applied. |
205 | In this sense it exactly mirrors the meaning of | |
43d6713e CD |
206 | .BR daylight (3) |
207 | for the current zone. | |
208 | On Linux, with glibc, the setting of the | |
d5c4e197 | 209 | .I tz_dsttime |
43d6713e CD |
210 | field of |
211 | .I struct timezone | |
212 | has never been used by | |
213 | .BR settimeofday () | |
214 | or | |
215 | .BR gettimeofday (). | |
d5c4e197 MK |
216 | .\" it has not |
217 | .\" been and will not be supported by libc or glibc. | |
218 | .\" Each and every occurrence of this field in the kernel source | |
219 | .\" (other than the declaration) is a bug. | |
53e0c293 | 220 | Thus, the following is purely of historical interest. |
efeece04 | 221 | .PP |
d5c4e197 MK |
222 | On old systems, the field |
223 | .I tz_dsttime | |
224 | contains a symbolic constant (values are given below) | |
225 | that indicates in which part of the year Daylight Saving Time | |
226 | is in force. | |
227 | (Note: this value is constant throughout the year: | |
228 | it does not indicate that DST is in force, it just selects an | |
229 | algorithm.) | |
230 | The daylight saving time algorithms defined are as follows: | |
58c2a94b | 231 | .PP |
d5c4e197 | 232 | .in +4n |
58c2a94b | 233 | .EX |
d5c4e197 | 234 | \fBDST_NONE\fP /* not on DST */ |
d5c4e197 | 235 | \fBDST_USA\fP /* USA style DST */ |
d5c4e197 | 236 | \fBDST_AUST\fP /* Australian style DST */ |
d5c4e197 | 237 | \fBDST_WET\fP /* Western European DST */ |
d5c4e197 | 238 | \fBDST_MET\fP /* Middle European DST */ |
d5c4e197 | 239 | \fBDST_EET\fP /* Eastern European DST */ |
d5c4e197 | 240 | \fBDST_CAN\fP /* Canada */ |
d5c4e197 | 241 | \fBDST_GB\fP /* Great Britain and Eire */ |
d5c4e197 | 242 | \fBDST_RUM\fP /* Romania */ |
d5c4e197 | 243 | \fBDST_TUR\fP /* Turkey */ |
d5c4e197 | 244 | \fBDST_AUSTALT\fP /* Australian style with shift in 1986 */ |
58c2a94b | 245 | .EE |
d5c4e197 MK |
246 | .in |
247 | .PP | |
248 | Of course it turned out that the period in which | |
249 | Daylight Saving Time is in force cannot be given | |
250 | by a simple algorithm, one per country; indeed, | |
251 | this period is determined by unpredictable political | |
252 | decisions. | |
253 | So this method of representing timezones | |
254 | has been abandoned. | |
47297adb | 255 | .SH SEE ALSO |
fea681da MK |
256 | .BR date (1), |
257 | .BR adjtimex (2), | |
fb6fc612 | 258 | .BR clock_gettime (2), |
fea681da MK |
259 | .BR time (2), |
260 | .BR ctime (3), | |
261 | .BR ftime (3), | |
d5c4e197 | 262 | .BR timeradd (3), |
eafd5ce1 | 263 | .BR capabilities (7), |
7032b90a | 264 | .BR time (7), |
1ce611a3 MK |
265 | .BR vdso (7), |
266 | .BR hwclock (8) |