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