1 .\" Copyright 1993 David Metcalfe (david@prism.demon.co.uk)
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.
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.
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
21 .\" Formatted or processed versions of this manual, if unaccompanied by
22 .\" the source, must acknowledge the copyright and authors of this work.
25 .\" References consulted:
26 .\" Linux libc source code
27 .\" Lewine's _POSIX Programmer's Guide_ (O'Reilly & Associates, 1991)
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
35 .TH CTIME 3 2016-12-12 "" "Linux Programmer's Manual"
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
43 .BI "char *asctime(const struct tm *" tm );
45 .BI "char *asctime_r(const struct tm *" tm ", char *" buf );
47 .BI "char *ctime(const time_t *" timep );
49 .BI "char *ctime_r(const time_t *" timep ", char *" buf );
51 .BI "struct tm *gmtime(const time_t *" timep );
53 .BI "struct tm *gmtime_r(const time_t *" timep ", struct tm *" result );
55 .BI "struct tm *localtime(const time_t *" timep );
57 .BI "struct tm *localtime_r(const time_t *" timep ", struct tm *" result );
59 .BI "time_t mktime(struct tm *" tm );
63 Feature Test Macro Requirements for glibc (see
64 .BR feature_test_macros (7)):
74 || /* Glibc versions <= 2.19: */ _BSD_SOURCE || _SVID_SOURCE
84 an argument of data type \fItime_t\fP, which represents calendar time.
85 When interpreted as an absolute time value, it represents the number of
86 seconds elapsed since the Epoch, 1970-01-01 00:00:00 +0000 (UTC).
92 functions both take an argument
93 representing broken-down time, which is a representation
94 separated into year, month, day, and so on.
96 Broken-down time is stored
97 in the structure \fItm\fP, which is defined in \fI<time.h>\fP as follows:
102 int tm_sec; /* Seconds (0-60) */
103 int tm_min; /* Minutes (0-59) */
104 int tm_hour; /* Hours (0-23) */
105 int tm_mday; /* Day of the month (1-31) */
106 int tm_mon; /* Month (0-11) */
107 int tm_year; /* Year - 1900 */
108 int tm_wday; /* Day of the week (0-6, Sunday = 0) */
109 int tm_yday; /* Day in the year (0-365, 1 Jan = 0) */
110 int tm_isdst; /* Daylight saving time */
115 The members of the \fItm\fP structure are:
118 The number of seconds after the minute, normally in the range 0 to 59,
119 but can be up to 60 to allow for leap seconds.
122 The number of minutes after the hour, in the range 0 to 59.
125 The number of hours past midnight, in the range 0 to 23.
128 The day of the month, in the range 1 to 31.
131 The number of months since January, in the range 0 to 11.
134 The number of years since 1900.
137 The number of days since Sunday, in the range 0 to 6.
140 The number of days since January 1, in the range 0 to 365.
143 A flag that indicates whether daylight saving time is in effect at the
145 The value is positive if daylight saving time is in
146 effect, zero if it is not, and negative if the information is not
152 .BI asctime(localtime( t )) \fR.
153 It converts the calendar time \fIt\fP into a
154 null-terminated string of the form
159 "Wed Jun 30 21:49:08 1993\\n"
163 The abbreviations for the days of the week are "Sun", "Mon", "Tue", "Wed",
164 "Thu", "Fri", and "Sat".
165 The abbreviations for the months are "Jan",
166 "Feb", "Mar", "Apr", "May", "Jun", "Jul", "Aug", "Sep", "Oct", "Nov", and
168 The return value points to a statically allocated string which
169 might be overwritten by subsequent calls to any of the date and time
171 The function also sets the external
172 variables \fItzname\fP, \fItimezone\fP, and \fIdaylight\fP (see
174 with information about the current timezone.
175 The reentrant version
177 does the same, but stores the
178 string in a user-supplied buffer
179 which should have room for at least 26 bytes.
181 set \fItzname\fP, \fItimezone\fP, and \fIdaylight\fP.
185 function converts the calendar time \fItimep\fP to
186 broken-down time representation, expressed in Coordinated Universal Time
188 It may return NULL when the year does not fit into an integer.
189 The return value points to a statically allocated struct which might be
190 overwritten by subsequent calls to any of the date and time functions.
193 function does the same, but stores the data in a
194 user-supplied struct.
198 function converts the calendar time \fItimep\fP to
199 broken-down time representation,
200 expressed relative to the user's specified timezone.
201 The function acts as if it called
203 and sets the external variables \fItzname\fP with
204 information about the current timezone, \fItimezone\fP with the difference
205 between Coordinated Universal Time (UTC) and local standard time in
206 seconds, and \fIdaylight\fP to a nonzero value if daylight savings
207 time rules apply during some part of the year.
208 The return value points to a statically allocated struct which might be
209 overwritten by subsequent calls to any of the date and time functions.
212 function does the same, but stores the data in a
213 user-supplied struct.
214 It need not set \fItzname\fP, \fItimezone\fP, and \fIdaylight\fP.
218 function converts the broken-down time value
219 \fItm\fP into a null-terminated string with the same format as
221 The return value points to a statically allocated string which might be
222 overwritten by subsequent calls to any of the date and time functions.
225 function does the same, but stores the string in
226 a user-supplied buffer which should have room for at least 26 bytes.
230 function converts a broken-down time structure, expressed
231 as local time, to calendar time representation.
233 the values supplied by the caller in the
238 The value specified in the
242 whether or not daylight saving time (DST)
243 is in effect for the time supplied in the
246 a positive value means DST is in effect;
247 zero means that DST is not in effect;
248 and a negative value means that
250 should (use timezone information and system databases to)
251 attempt to determine whether DST is in effect at the specified time.
255 function modifies the fields of the
257 structure as follows:
261 are set to values determined from the contents of the other fields;
262 if structure members are outside their valid interval, they will be
263 normalized (so that, for example, 40 October is changed into 9 November);
265 is set (regardless of its initial value)
266 to a positive value or to 0, respectively,
267 to indicate whether DST is or is not in effect at the specified time.
270 also sets the external variable \fItzname\fP with
271 information about the current timezone.
273 If the specified broken-down
274 time cannot be represented as calendar time (seconds since the Epoch),
278 and does not alter the
279 members of the broken-down time structure.
285 return a pointer to a
292 return the address of the structure pointed to by
299 return a pointer to a string.
305 return a pointer to the string pointed to by
310 returns the calendar time (seconds since the Epoch),
311 expressed as a value of type
318 The remaining functions return NULL on error.
321 is set to indicate the cause of the error.
325 The result cannot be represented.
327 For an explanation of the terms used in this section, see
334 Interface Attribute Value
337 T} Thread safety MT-Unsafe race:asctime locale
340 T} Thread safety MT-Safe locale
346 race:asctime env locale
353 T} Thread safety MT-Safe env locale
357 T} Thread safety MT-Unsafe race:tmbuf env locale
376 recommending the use of
386 return a pointer to static data and hence are not thread-safe.
387 The thread-safe versions,
393 are specified by SUSv2.
402 functions shall return values in one of two static objects:
403 a broken-down time structure and an array of type
405 Execution of any of the functions may overwrite the information returned
406 in either of these objects by any of the other functions."
407 This can occur in the glibc implementation.
409 In many implementations, including glibc, a 0 in
411 is interpreted as meaning the last day of the preceding month.
413 The glibc version of \fIstruct tm\fP has additional fields
417 const char *tm_zone; /* Timezone abbreviation */
423 was set before including
425 This is a BSD extension, present in 4.3BSD-Reno.
427 According to POSIX.1-2004,
429 is required to behave as though
433 does not have this requirement.
434 .\" See http://thread.gmane.org/gmane.comp.time.tz/2034/
437 should be called before
441 .BR gettimeofday (2),