Debian Codegraph @

upstream/debian-trixie/man2/gettimeofday.2

raw
1 .\" Copyright (c) 1992 Drew Eckhardt ([email protected]), March 28, 1992
2 .\"
3 .\" SPDX-License-Identifier: Linux-man-pages-copyleft
4 .\"
5 .\" Modified by Michael Haardt ([email protected])
6 .\" Modified 1993-07-23 by Rik Faith ([email protected])
7 .\" Modified 1994-08-21 by Michael Chastain ([email protected]):
8 .\" Fixed necessary '#include' lines.
9 .\" Modified 1995-04-15 by Michael Chastain ([email protected]):
10 .\" Added reference to adjtimex.
11 .\" Removed some nonsense lines pointed out by Urs Thuermann,
12 .\" ([email protected]), aeb, 950722.
13 .\" Modified 1997-01-14 by Austin Donnelly ([email protected]):
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 <[email protected]>
18 .\" Added notes on capability requirement.
19 .\"
20 .TH gettimeofday 2 2024-05-02 "Linux man-pages 6.9.1"
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 .P
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 .P
36 .RS -4
37 Feature Test Macro Requirements for glibc (see
38 .BR feature_test_macros (7)):
39 .RE
40 .P
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 .P
55 The
56 .I tv
57 argument is a
58 .I struct timeval
59 (as specified in
60 .IR <sys/time.h> ):
61 .P
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 .P
71 and gives the number of seconds and microseconds since the Epoch (see
72 .BR time (2)).
73 .P
74 The
75 .I tz
76 argument is a
77 .IR "struct timezone" :
78 .P
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 .P
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 .\" .P
100 .\" Only the superuser may use
101 .\" .BR settimeofday ().
102 .P
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 .P
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 VERSIONS
173 .SS C library/kernel differences
174 On some architectures, an implementation of
175 .BR gettimeofday ()
176 is provided in the
177 .BR vdso (7).
178 .P
179 The kernel accepts NULL for both
180 .I tv
181 and
182 .IR tz .
183 The timezone argument is ignored by glibc and musl,
184 and not passed to/from the kernel.
185 Android's bionic passes the timezone argument to/from the kernel,
186 but Android does not update the kernel timezone
187 based on the device timezone in Settings,
188 so the kernel's timezone is typically UTC.
189 .SH STANDARDS
190 .TP
191 .BR gettimeofday ()
192 POSIX.1-2008 (obsolete).
193 .TP
194 .BR settimeofday ()
195 None.
196 .SH HISTORY
197 SVr4, 4.3BSD.
198 POSIX.1-2001 describes
199 .BR gettimeofday ()
200 but not
201 .BR settimeofday ().
202 POSIX.1-2008 marks
203 .BR gettimeofday ()
204 as obsolete, recommending the use of
205 .BR clock_gettime (2)
206 instead.
207 .P
208 Traditionally, the fields of
209 .I struct timeval
210 were of type
211 .IR long .
212 .\"
213 .SS The tz_dsttime field
214 On a non-Linux kernel, with glibc, the
215 .I tz_dsttime
216 field of
217 .I struct timezone
218 will be set to a nonzero value by
219 .BR gettimeofday ()
220 if the current timezone has ever had or will have a daylight saving
221 rule applied.
222 In this sense it exactly mirrors the meaning of
223 .BR daylight (3)
224 for the current zone.
225 On Linux, with glibc, the setting of the
226 .I tz_dsttime
227 field of
228 .I struct timezone
229 has never been used by
230 .BR settimeofday ()
231 or
232 .BR gettimeofday ().
233 .\" it has not
234 .\" been and will not be supported by libc or glibc.
235 .\" Each and every occurrence of this field in the kernel source
236 .\" (other than the declaration) is a bug.
237 Thus, the following is purely of historical interest.
238 .P
239 On old systems, the field
240 .I tz_dsttime
241 contains a symbolic constant (values are given below)
242 that indicates in which part of the year Daylight Saving Time
243 is in force.
244 (Note: this value is constant throughout the year:
245 it does not indicate that DST is in force, it just selects an
246 algorithm.)
247 The daylight saving time algorithms defined are as follows:
248 .P
249 .in +4n
250 .EX
251 \fBDST_NONE\fP /* not on DST */
252 \fBDST_USA\fP /* USA style DST */
253 \fBDST_AUST\fP /* Australian style DST */
254 \fBDST_WET\fP /* Western European DST */
255 \fBDST_MET\fP /* Middle European DST */
256 \fBDST_EET\fP /* Eastern European DST */
257 \fBDST_CAN\fP /* Canada */
258 \fBDST_GB\fP /* Great Britain and Eire */
259 \fBDST_RUM\fP /* Romania */
260 \fBDST_TUR\fP /* Turkey */
261 \fBDST_AUSTALT\fP /* Australian style with shift in 1986 */
262 .EE
263 .in
264 .P
265 Of course it turned out that the period in which
266 Daylight Saving Time is in force cannot be given
267 by a simple algorithm, one per country; indeed,
268 this period is determined by unpredictable political
269 decisions.
270 So this method of representing timezones
271 has been abandoned.
272 .SH NOTES
273 The time returned by
274 .BR gettimeofday ()
275 .I is
276 affected by discontinuous jumps in the system time
277 (e.g., if the system administrator manually changes the system time).
278 If you need a monotonically increasing clock, see
279 .BR clock_gettime (2).
280 .P
281 Macros for operating on
282 .I timeval
283 structures are described in
284 .BR timeradd (3).
285 .SH SEE ALSO
286 .BR date (1),
287 .BR adjtimex (2),
288 .BR clock_gettime (2),
289 .BR time (2),
290 .BR ctime (3),
291 .BR ftime (3),
292 .BR timeradd (3),
293 .BR capabilities (7),
294 .BR time (7),
295 .BR vdso (7),
296 .BR hwclock (8)