Debian Codegraph @

upstream/debian-unstable/man2/gettimeofday.2

raw
1 .\" Copyright 1992, Drew Eckhardt <[email protected]>
2 .\" Copyright, the authors of the Linux man-pages project
3 .\"
4 .\" SPDX-License-Identifier: Linux-man-pages-copyleft
5 .\"
6 .TH gettimeofday 2 2026-02-08 "Linux man-pages 6.18"
7 .SH NAME
8 gettimeofday, settimeofday \- get / set time
9 .SH LIBRARY
10 Standard C library
11 .RI ( libc ,\~ \-lc )
12 .SH SYNOPSIS
13 .nf
14 .B #include <sys/time.h>
15 .P
16 .B [[deprecated]]
17 .BI "int gettimeofday(struct timeval *restrict " tv ,
18 .BI " struct timezone *_Nullable restrict " tz );
19 .B [[deprecated]]
20 .BI "int settimeofday(const struct timeval *" tv ,
21 .BI " const struct timezone *_Nullable " tz );
22 .fi
23 .P
24 .RS -4
25 Feature Test Macro Requirements for glibc (see
26 .BR feature_test_macros (7)):
27 .RE
28 .P
29 .BR settimeofday ():
30 .nf
31 Since glibc 2.19:
32 _DEFAULT_SOURCE
33 glibc 2.19 and earlier:
34 _BSD_SOURCE
35 .fi
36 .SH DESCRIPTION
37 The functions
38 .BR gettimeofday ()
39 and
40 .BR settimeofday ()
41 can get and set the time as well as a timezone.
42 .P
43 The
44 .I tv
45 argument is a
46 .I struct timeval
47 (as specified in
48 .IR <sys/time.h> ):
49 .P
50 .in +4n
51 .EX
52 struct timeval {
53 time_t tv_sec; /* seconds */
54 suseconds_t tv_usec; /* microseconds */
55 };
56 .EE
57 .in
58 .P
59 and gives the number of seconds and microseconds since the Epoch (see
60 .BR time (2)).
61 .P
62 The
63 .I tz
64 argument is a
65 .IR "struct timezone" :
66 .P
67 .in +4n
68 .EX
69 struct timezone {
70 int tz_minuteswest; /* minutes west of Greenwich */
71 int tz_dsttime; /* type of DST correction */
72 };
73 .EE
74 .in
75 .P
76 If either
77 .I tv
78 or
79 .I tz
80 is NULL, the corresponding structure is not set or returned.
81 .\" FIXME . The compilation warning looks to be going away in glibc 2.17
82 .\" see glibc commit 4b7634a5e03b0da6f8875de9d3f74c1cf6f2a6e8
83 (However, compilation warnings will result if
84 .I tv
85 is NULL.)
86 .\" The following is covered under EPERM below:
87 .\" .P
88 .\" Only the superuser may use
89 .\" .BR settimeofday ().
90 .P
91 The use of the
92 .I timezone
93 structure is obsolete;
94 the
95 .I tz
96 argument should normally be specified as NULL.
97 See VERSIONS.
98 .P
99 Under Linux, there are some peculiar "warp clock" semantics associated
100 with the
101 .BR settimeofday ()
102 system call if on the very first call (after booting)
103 that has a non-NULL
104 .I tz
105 argument, the
106 .I tv
107 argument is NULL and the
108 .I tz_minuteswest
109 field is nonzero.
110 (The
111 .I tz_dsttime
112 field should be zero for this case.)
113 In such a case it is assumed that the CMOS clock
114 is on local time, and that it has to be incremented by this amount
115 to get UTC system time.
116 No doubt it is a bad idea to use this feature.
117 .SH RETURN VALUE
118 .BR gettimeofday ()
119 and
120 .BR settimeofday ()
121 return 0 for success.
122 On error, \-1 is returned and
123 .I errno
124 is set to indicate the error.
125 .SH ERRORS
126 .TP
127 .B EFAULT
128 One of
129 .I tv
130 or
131 .I tz
132 pointed outside the accessible address space.
133 .TP
134 .B EINVAL
135 .RB ( settimeofday ()):
136 .I timezone
137 is invalid.
138 .TP
139 .B EINVAL
140 .RB ( settimeofday ()):
141 .I tv.tv_sec
142 is negative or
143 .I tv.tv_usec
144 is outside the range [0, 999,999].
145 .TP
146 .BR EINVAL " (since Linux 4.3)"
147 .\" commit e1d7ba8735551ed79c7a0463a042353574b96da3
148 .RB ( settimeofday ()):
149 An attempt was made to set the time to a value less than
150 the current value of the
151 .B CLOCK_MONOTONIC
152 clock (see
153 .BR clock_gettime (2)).
154 .TP
155 .B EPERM
156 The calling process has insufficient privilege to call
157 .BR settimeofday ();
158 under Linux the
159 .B CAP_SYS_TIME
160 capability is required.
161 .SH VERSIONS
162 .SS C library/kernel differences
163 On some architectures, an implementation of
164 .BR gettimeofday ()
165 is provided in the
166 .BR vdso (7).
167 .P
168 The kernel accepts NULL for both
169 .I tv
170 and
171 .IR tz .
172 The timezone argument is ignored by glibc and musl,
173 and not passed to/from the kernel.
174 Android's bionic passes the timezone argument to/from the kernel,
175 but Android does not update the kernel timezone
176 based on the device timezone in Settings,
177 so the kernel's timezone is typically UTC.
178 .SH STANDARDS
179 None.
180 .SH HISTORY
181 4.3BSD,
182 SVr4.
183 SUSv1 and POSIX.1-2001 XSI described
184 .BR gettimeofday ()
185 but not
186 .BR settimeofday ().
187 POSIX.1-2008 XSI marked
188 .BR gettimeofday ()
189 as obsolete, recommending the use of
190 .BR clock_gettime (2)
191 instead.
192 Likewise,
193 .BR clock_settime (2)
194 should be used instead of
195 .BR settimeofday ().
196 POSIX.1-2024 removed
197 .BR gettimeofday ().
198 .P
199 Traditionally, the fields of
200 .I struct timeval
201 were of type
202 .IR long .
203 .\"
204 .SS The tz_dsttime field
205 On a non-Linux kernel, with glibc, the
206 .I tz_dsttime
207 field of
208 .I struct timezone
209 will be set to a nonzero value by
210 .BR gettimeofday ()
211 if the current timezone has ever had or will have a daylight saving
212 rule applied.
213 In this sense it exactly mirrors the meaning of
214 .BR daylight (3)
215 for the current zone.
216 On Linux, with glibc, the setting of the
217 .I tz_dsttime
218 field of
219 .I struct timezone
220 has never been used by
221 .BR settimeofday ()
222 or
223 .BR gettimeofday ().
224 .\" it has not
225 .\" been and will not be supported by libc or glibc.
226 .\" Each and every occurrence of this field in the kernel source
227 .\" (other than the declaration) is a bug.
228 Thus, the following is purely of historical interest.
229 .P
230 On old systems, the field
231 .I tz_dsttime
232 contains a symbolic constant (values are given below)
233 that indicates in which part of the year Daylight Saving Time
234 is in force.
235 (Note: this value is constant throughout the year:
236 it does not indicate that DST is in force, it just selects an
237 algorithm.)
238 The daylight saving time algorithms defined are as follows:
239 .P
240 .in +4n
241 .EX
242 \f[B]DST_NONE\f[] /* not on DST */
243 \f[B]DST_USA\f[] /* USA style DST */
244 \f[B]DST_AUST\f[] /* Australian style DST */
245 \f[B]DST_WET\f[] /* Western European DST */
246 \f[B]DST_MET\f[] /* Middle European DST */
247 \f[B]DST_EET\f[] /* Eastern European DST */
248 \f[B]DST_CAN\f[] /* Canada */
249 \f[B]DST_GB\f[] /* Great Britain and Eire */
250 \f[B]DST_RUM\f[] /* Romania */
251 \f[B]DST_TUR\f[] /* Turkey */
252 \f[B]DST_AUSTALT\f[] /* Australian style with shift in 1986 */
253 .EE
254 .in
255 .P
256 Of course,
257 it turned out that the period in which
258 Daylight Saving Time is in force
259 cannot be given by a simple algorithm,
260 one per country;
261 indeed,
262 this period is determined by unpredictable political decisions.
263 So this method of representing timezones
264 has been abandoned.
265 .SH NOTES
266 The time returned by
267 .BR gettimeofday ()
268 .I is
269 affected by discontinuous jumps in the system time
270 (e.g., if the system administrator manually changes the system time).
271 If you need a monotonically increasing clock, see
272 .BR clock_gettime (2).
273 .P
274 Macros for operating on
275 .I timeval
276 structures are described in
277 .BR timeradd (3).
278 .SH SEE ALSO
279 .BR date (1),
280 .BR adjtimex (2),
281 .BR clock_gettime (2),
282 .BR time (2),
283 .BR ctime (3),
284 .BR ftime (3),
285 .BR timeradd (3),
286 .BR capabilities (7),
287 .BR time (7),
288 .BR vdso (7),
289 .BR hwclock (8)