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