Debian Codegraph @

upstream/debian-trixie/man3/ctime.3

raw
1 '\" t
2 .\" Copyright 1993 David Metcalfe ([email protected])
3 .\"
4 .\" SPDX-License-Identifier: Linux-man-pages-copyleft
5 .\"
6 .\" References consulted:
7 .\" Linux libc source code
8 .\" Lewine's _POSIX Programmer's Guide_ (O'Reilly & Associates, 1991)
9 .\" 386BSD man pages
10 .\" Modified Sat Jul 24 19:49:27 1993 by Rik Faith ([email protected])
11 .\" Modified Fri Apr 26 12:38:55 MET DST 1996 by Martin Schulze ([email protected])
12 .\" Modified 2001-11-13, aeb
13 .\" Modified 2001-12-13, joey, aeb
14 .\" Modified 2004-11-16, mtk
15 .\"
16 .TH ctime 3 2024-06-15 "Linux man-pages 6.9.1"
17 .SH NAME
18 asctime, ctime, gmtime, localtime, mktime, asctime_r, ctime_r, gmtime_r,
19 localtime_r \- transform date and time to broken-down time or ASCII
20 .SH LIBRARY
21 Standard C library
22 .RI ( libc ", " \-lc )
23 .SH SYNOPSIS
24 .nf
25 .B #include <time.h>
26 .P
27 .BI "char *asctime(const struct tm *" tm );
28 .BI "char *asctime_r(const struct tm *restrict " tm ,
29 .BI " char " buf "[restrict 26]);"
30 .P
31 .BI "char *ctime(const time_t *" timep );
32 .BI "char *ctime_r(const time_t *restrict " timep ,
33 .BI " char " buf "[restrict 26]);"
34 .P
35 .BI "struct tm *gmtime(const time_t *" timep );
36 .BI "struct tm *gmtime_r(const time_t *restrict " timep ,
37 .BI " struct tm *restrict " result );
38 .P
39 .BI "struct tm *localtime(const time_t *" timep );
40 .BI "struct tm *localtime_r(const time_t *restrict " timep ,
41 .BI " struct tm *restrict " result );
42 .P
43 .BI "time_t mktime(struct tm *" tm );
44 .fi
45 .P
46 .RS -4
47 Feature Test Macro Requirements for glibc (see
48 .BR feature_test_macros (7)):
49 .RE
50 .P
51 .BR asctime_r (),
52 .BR ctime_r (),
53 .BR gmtime_r (),
54 .BR localtime_r ():
55 .nf
56 _POSIX_C_SOURCE
57 || /* glibc <= 2.19: */ _BSD_SOURCE || _SVID_SOURCE
58 .fi
59 .SH DESCRIPTION
60 The
61 .BR ctime (),
62 .BR gmtime (),
63 and
64 .BR localtime ()
65 functions all take
66 an argument of data type \fItime_t\fP, which represents calendar time.
67 When interpreted as an absolute time value, it represents the number of
68 seconds elapsed since the Epoch, 1970-01-01 00:00:00 +0000 (UTC).
69 .P
70 The
71 .BR asctime ()
72 and
73 .BR mktime ()
74 functions both take an argument
75 representing broken-down time, which is a representation
76 separated into year, month, day, and so on.
77 .P
78 Broken-down time is stored in the structure
79 .IR tm ,
80 described in
81 .BR tm (3type).
82 .P
83 The call
84 .BI ctime( t )
85 is equivalent to
86 .BI asctime(localtime( t )) \fR.
87 It converts the calendar time \fIt\fP into a
88 null-terminated string of the form
89 .P
90 .in +4n
91 .EX
92 "Wed Jun 30 21:49:08 1993\[rs]n"
93 .EE
94 .in
95 .P
96 The abbreviations for the days of the week are "Sun", "Mon", "Tue", "Wed",
97 "Thu", "Fri", and "Sat".
98 The abbreviations for the months are "Jan",
99 "Feb", "Mar", "Apr", "May", "Jun", "Jul", "Aug", "Sep", "Oct", "Nov", and
100 "Dec".
101 The return value points to a statically allocated string which
102 might be overwritten by subsequent calls to any of the date and time
103 functions.
104 The function also sets the external variables \fItzname\fP,
105 \fItimezone\fP, and \fIdaylight\fP as if it called
106 .BR tzset (3).
107 The reentrant version
108 .BR ctime_r ()
109 does the same, but stores the
110 string in a user-supplied buffer
111 which should have room for at least 26 bytes.
112 It need not
113 set \fItzname\fP, \fItimezone\fP, and \fIdaylight\fP.
114 .P
115 The
116 .BR gmtime ()
117 function converts the calendar time \fItimep\fP to
118 broken-down time representation, expressed in Coordinated Universal Time
119 (UTC).
120 It may return NULL when the year does not fit into an integer.
121 The return value points to a statically allocated struct which might be
122 overwritten by subsequent calls to any of the date and time functions.
123 The
124 .BR gmtime_r ()
125 function does the same, but stores the data in a
126 user-supplied struct.
127 .P
128 The
129 .BR localtime ()
130 function converts the calendar time \fItimep\fP to
131 broken-down time representation,
132 expressed relative to the user's specified timezone.
133 The function also sets the external variables \fItzname\fP,
134 \fItimezone\fP, and \fIdaylight\fP as if it called
135 .BR tzset (3).
136 The return value points to a statically allocated struct which might be
137 overwritten by subsequent calls to any of the date and time functions.
138 The
139 .BR localtime_r ()
140 function does the same, but stores the data in a
141 user-supplied struct.
142 It need not set \fItzname\fP, \fItimezone\fP, and \fIdaylight\fP.
143 .P
144 The
145 .BR asctime ()
146 function converts the broken-down time value
147 \fItm\fP into a null-terminated string with the same format as
148 .BR ctime ().
149 The return value points to a statically allocated string which might be
150 overwritten by subsequent calls to any of the date and time functions.
151 The
152 .BR asctime_r ()
153 function does the same, but stores the string in
154 a user-supplied buffer which should have room for at least 26 bytes.
155 .P
156 The
157 .BR mktime ()
158 function converts a broken-down time structure, expressed
159 as local time, to calendar time representation.
160 The function ignores
161 the values supplied by the caller in the
162 .I tm_wday
163 and
164 .I tm_yday
165 fields.
166 The value specified in the
167 .I tm_isdst
168 field informs
169 .BR mktime ()
170 whether or not daylight saving time (DST)
171 is in effect for the time supplied in the
172 .I tm
173 structure:
174 a positive value means DST is in effect;
175 zero means that DST is not in effect;
176 and a negative value means that
177 .BR mktime ()
178 should (use timezone information and system databases to)
179 attempt to determine whether DST is in effect at the specified time.
180 .P
181 The
182 .BR mktime ()
183 function modifies the fields of the
184 .I tm
185 structure as follows:
186 .I tm_wday
187 and
188 .I tm_yday
189 are set to values determined from the contents of the other fields;
190 if structure members are outside their valid interval, they will be
191 normalized (so that, for example, 40 October is changed into 9 November);
192 .I tm_isdst
193 is set (regardless of its initial value)
194 to a positive value or to 0, respectively,
195 to indicate whether DST is or is not in effect at the specified time.
196 The function also sets the external variables \fItzname\fP,
197 \fItimezone\fP, and \fIdaylight\fP as if it called
198 .BR tzset (3).
199 .P
200 If the specified broken-down
201 time cannot be represented as calendar time (seconds since the Epoch),
202 .BR mktime ()
203 returns
204 .I (time_t)\ \-1
205 and does not alter the
206 members of the broken-down time structure.
207 .SH RETURN VALUE
208 On success,
209 .BR gmtime ()
210 and
211 .BR localtime ()
212 return a pointer to a
213 .IR "struct\ tm" .
214 .P
215 On success,
216 .BR gmtime_r ()
217 and
218 .BR localtime_r ()
219 return the address of the structure pointed to by
220 .IR result .
221 .P
222 On success,
223 .BR asctime ()
224 and
225 .BR ctime ()
226 return a pointer to a string.
227 .P
228 On success,
229 .BR asctime_r ()
230 and
231 .BR ctime_r ()
232 return a pointer to the string pointed to by
233 .IR buf .
234 .P
235 On success,
236 .BR mktime ()
237 returns the calendar time (seconds since the Epoch),
238 expressed as a value of type
239 .IR time_t .
240 .P
241 On error,
242 .BR mktime ()
243 returns the value
244 .IR "(time_t)\ \-1" .
245 The remaining functions return NULL on error.
246 On error,
247 .I errno
248 is set to indicate the error.
249 .SH ERRORS
250 .TP
251 .B EOVERFLOW
252 The result cannot be represented.
253 .SH ATTRIBUTES
254 For an explanation of the terms used in this section, see
255 .BR attributes (7).
256 .TS
257 allbox;
258 lb lb lbx
259 l l l.
260 Interface Attribute Value
261 T{
262 .na
263 .nh
264 .BR asctime ()
265 T} Thread safety T{
266 .na
267 .nh
268 MT-Unsafe race:asctime locale
269 T}
270 T{
271 .na
272 .nh
273 .BR asctime_r ()
274 T} Thread safety T{
275 .na
276 .nh
277 MT-Safe locale
278 T}
279 T{
280 .na
281 .nh
282 .BR ctime ()
283 T} Thread safety T{
284 .na
285 .nh
286 MT-Unsafe race:tmbuf
287 race:asctime env locale
288 T}
289 T{
290 .na
291 .nh
292 .BR ctime_r (),
293 .BR gmtime_r (),
294 .BR localtime_r (),
295 .BR mktime ()
296 T} Thread safety T{
297 .na
298 .nh
299 MT-Safe env locale
300 T}
301 T{
302 .na
303 .nh
304 .BR gmtime (),
305 .BR localtime ()
306 T} Thread safety T{
307 .na
308 .nh
309 MT-Unsafe race:tmbuf env locale
310 T}
311 .TE
312 .SH VERSIONS
313 POSIX doesn't specify the parameters of
314 .BR ctime_r ()
315 to be
316 .IR restrict ;
317 that is specific to glibc.
318 .P
319 In many implementations, including glibc, a 0 in
320 .I tm_mday
321 is interpreted as meaning the last day of the preceding month.
322 .P
323 According to POSIX.1,
324 .BR localtime ()
325 is required to behave as though
326 .BR tzset (3)
327 was called, while
328 .BR localtime_r ()
329 does not have this requirement.
330 .\" See http://thread.gmane.org/gmane.comp.time.tz/2034/
331 For portable code,
332 .BR tzset (3)
333 should be called before
334 .BR localtime_r ().
335 .SH STANDARDS
336 .TP
337 .BR asctime ()
338 .TQ
339 .BR ctime ()
340 .TQ
341 .BR gmtime ()
342 .TQ
343 .BR localtime ()
344 .TQ
345 .BR mktime ()
346 C23, POSIX.1-2024.
347 .TP
348 .BR gmtime_r ()
349 .TQ
350 .BR localtime_r ()
351 POSIX.1-2024.
352 .TP
353 .BR asctime_r ()
354 .TQ
355 .BR ctime_r ()
356 None.
357 .SH HISTORY
358 .TP
359 .BR gmtime ()
360 .TQ
361 .BR localtime ()
362 .TQ
363 .BR mktime ()
364 C89, POSIX.1-1988.
365 .TP
366 .BR asctime ()
367 .TQ
368 .BR ctime ()
369 C89, POSIX.1-1988.
370 Marked obsolescent in C23 and in POSIX.1-2008 (recommending
371 .BR strftime (3)).
372 .TP
373 .BR gmtime_r ()
374 .TQ
375 .BR localtime_r ()
376 POSIX.1-1996.
377 .TP
378 .BR asctime_r ()
379 .TQ
380 .BR ctime_r ()
381 POSIX.1-1996.
382 Marked obsolescent in POSIX.1-2008.
383 Removed in POSIX.1-2024 (recommending
384 .BR strftime (3)).
385 .SH NOTES
386 The four functions
387 .BR asctime (),
388 .BR ctime (),
389 .BR gmtime (),
390 and
391 .BR localtime ()
392 return a pointer to static data and hence are not thread-safe.
393 The thread-safe versions,
394 .BR asctime_r (),
395 .BR ctime_r (),
396 .BR gmtime_r (),
397 and
398 .BR localtime_r (),
399 are specified by SUSv2.
400 .P
401 POSIX.1 says:
402 "The
403 .BR asctime (),
404 .BR ctime (),
405 .BR gmtime (),
406 and
407 .BR localtime ()
408 functions shall return values in one of two static objects:
409 a broken-down time structure and an array of type
410 .IR char .
411 Execution of any of the functions that return a pointer to one of these
412 object types may overwrite the information in any object of the same type
413 pointed to by the value returned from any previous call to any of them."
414 This can occur in the glibc implementation.
415 .SH SEE ALSO
416 .BR date (1),
417 .BR gettimeofday (2),
418 .BR time (2),
419 .BR utime (2),
420 .BR clock (3),
421 .BR difftime (3),
422 .BR strftime (3),
423 .BR strptime (3),
424 .BR timegm (3),
425 .BR tzset (3),
426 .BR time (7)