| blob | d7f1dbe2b9f6f023aa6500f1c551d054680c9990 |
1 .\" Copyright (c) 1992 Drew Eckhardt (drew@cs.colorado.edu), March 28, 1992
2 .\"
3 .\" SPDX-License-Identifier: Linux-man-pages-copyleft
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.
17 .\" Modified, 2004-05-27 by Michael Kerrisk <mtk.manpages@gmail.com>
18 .\" Added notes on capability requirement.
19 .\"
20 .TH gettimeofday 2 (date) "Linux man-pages (unreleased)"
21 .SH NAME
22 gettimeofday, settimeofday \- get / set time
23 .SH LIBRARY
24 Standard C library
25 .RI ( libc ", " \-lc )
26 .SH SYNOPSIS
27 .nf
28 .B #include <sys/time.h>
29 .PP
30 .BI "int gettimeofday(struct timeval *restrict " tv ,
31 .BI " struct timezone *_Nullable restrict " tz );
32 .BI "int settimeofday(const struct timeval *" tv ,
33 .BI " const struct timezone *_Nullable " tz );
34 .fi
35 .PP
36 .RS -4
37 Feature Test Macro Requirements for glibc (see
38 .BR feature_test_macros (7)):
39 .RE
40 .PP
41 .BR settimeofday ():
42 .nf
43 Since glibc 2.19:
44 _DEFAULT_SOURCE
45 glibc 2.19 and earlier:
46 _BSD_SOURCE
47 .fi
48 .SH DESCRIPTION
49 The functions
50 .BR gettimeofday ()
51 and
52 .BR settimeofday ()
53 can get and set the time as well as a timezone.
54 .PP
55 The
56 .I tv
57 argument is a
58 .I struct timeval
59 (as specified in
60 .IR <sys/time.h> ):
61 .PP
62 .in +4n
63 .EX
64 struct timeval {
65 time_t tv_sec; /* seconds */
66 suseconds_t tv_usec; /* microseconds */
67 };
68 .EE
69 .in
70 .PP
71 and gives the number of seconds and microseconds since the Epoch (see
72 .BR time (2)).
73 .PP
74 The
75 .I tz
76 argument is a
77 .IR "struct timezone" :
78 .PP
79 .in +4n
80 .EX
81 struct timezone {
82 int tz_minuteswest; /* minutes west of Greenwich */
83 int tz_dsttime; /* type of DST correction */
84 };
85 .EE
86 .in
87 .PP
88 If either
89 .I tv
90 or
91 .I tz
92 is NULL, the corresponding structure is not set or returned.
93 .\" FIXME . The compilation warning looks to be going away in glibc 2.17
94 .\" see glibc commit 4b7634a5e03b0da6f8875de9d3f74c1cf6f2a6e8
95 (However, compilation warnings will result if
96 .I tv
97 is NULL.)
98 .\" The following is covered under EPERM below:
99 .\" .PP
100 .\" Only the superuser may use
101 .\" .BR settimeofday ().
102 .PP
103 The use of the
104 .I timezone
105 structure is obsolete; the
106 .I tz
107 argument should normally be specified as NULL.
108 (See NOTES below.)
109 .PP
110 Under Linux, there are some peculiar "warp clock" semantics associated
111 with the
112 .BR settimeofday ()
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
120 field is nonzero.
121 (The
122 .I tz_dsttime
123 field should be zero for this case.)
124 In such a case it is assumed that the CMOS clock
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.
128 .SH RETURN VALUE
129 .BR gettimeofday ()
130 and
131 .BR settimeofday ()
132 return 0 for success.
133 On error, \-1 is returned and
134 .I errno
135 is set to indicate the error.
136 .SH ERRORS
137 .TP
138 .B EFAULT
139 One of
140 .I tv
141 or
142 .I tz
143 pointed outside the accessible address space.
144 .TP
145 .B EINVAL
146 .RB ( settimeofday ()):
147 .I timezone
148 is invalid.
149 .TP
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
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
166 .B EPERM
167 The calling process has insufficient privilege to call
168 .BR settimeofday ();
169 under Linux the
170 .B CAP_SYS_TIME
171 capability is required.
172 .SH STANDARDS
173 SVr4, 4.3BSD.
174 POSIX.1-2001 describes
175 .BR gettimeofday ()
176 but not
177 .BR settimeofday ().
178 POSIX.1-2008 marks
179 .BR gettimeofday ()
180 as obsolete, recommending the use of
181 .BR clock_gettime (2)
182 instead.
183 .SH NOTES
184 The time returned by
185 .BR gettimeofday ()
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).
191 .PP
192 Macros for operating on
193 .I timeval
194 structures are described in
195 .BR timeradd (3).
196 .PP
197 Traditionally, the fields of
198 .I struct timeval
199 were of type
200 .IR long .
201 .\"
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 .\"
208 .SS The tz_dsttime field
209 On a non-Linux kernel, with glibc, the
210 .I tz_dsttime
211 field of
212 .I struct timezone
213 will be set to a nonzero value by
214 .BR gettimeofday ()
215 if the current timezone has ever had or will have a daylight saving
216 rule applied.
217 In this sense it exactly mirrors the meaning of
218 .BR daylight (3)
219 for the current zone.
220 On Linux, with glibc, the setting of the
221 .I tz_dsttime
222 field of
223 .I struct timezone
224 has never been used by
225 .BR settimeofday ()
226 or
227 .BR gettimeofday ().
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.
232 Thus, the following is purely of historical interest.
233 .PP
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:
243 .PP
244 .in +4n
245 .EX
246 \fBDST_NONE\fP /* not on DST */
247 \fBDST_USA\fP /* USA style DST */
248 \fBDST_AUST\fP /* Australian style DST */
249 \fBDST_WET\fP /* Western European DST */
250 \fBDST_MET\fP /* Middle European DST */
251 \fBDST_EET\fP /* Eastern European DST */
252 \fBDST_CAN\fP /* Canada */
253 \fBDST_GB\fP /* Great Britain and Eire */
254 \fBDST_RUM\fP /* Romania */
255 \fBDST_TUR\fP /* Turkey */
256 \fBDST_AUSTALT\fP /* Australian style with shift in 1986 */
257 .EE
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.
267 .SH SEE ALSO
268 .BR date (1),
269 .BR adjtimex (2),
270 .BR clock_gettime (2),
271 .BR time (2),
272 .BR ctime (3),
273 .BR ftime (3),
274 .BR timeradd (3),
275 .BR capabilities (7),
276 .BR time (7),
277 .BR vdso (7),
278 .BR hwclock (8)