1 .\" Copyright 1993 David Metcalfe (david@prism.demon.co.uk)
3 .\" Permission is granted to make and distribute verbatim copies of this
4 .\" manual provided the copyright notice and this permission notice are
5 .\" preserved on all copies.
7 .\" Permission is granted to copy and distribute modified versions of this
8 .\" manual under the conditions for verbatim copying, provided that the
9 .\" entire resulting derived work is distributed under the terms of a
10 .\" permission notice identical to this one.
12 .\" Since the Linux kernel and libraries are constantly changing, this
13 .\" manual page may be incorrect or out-of-date. The author(s) assume no
14 .\" responsibility for errors or omissions, or for damages resulting from
15 .\" the use of the information contained herein. The author(s) may not
16 .\" have taken the same level of care in the production of this manual,
17 .\" which is licensed free of charge, as they might when working
20 .\" Formatted or processed versions of this manual, if unaccompanied by
21 .\" the source, must acknowledge the copyright and authors of this work.
23 .\" References consulted:
24 .\" Linux libc source code
25 .\" Lewine's _POSIX Programmer's Guide_ (O'Reilly & Associates, 1991)
27 .\" Modified Sat Jul 24 19:49:27 1993 by Rik Faith (faith@cs.unc.edu)
28 .\" Modified Fri Apr 26 12:38:55 MET DST 1996 by Martin Schulze (joey@linux.de)
29 .\" Modified 2001-11-13, aeb
30 .\" Modified 2001-12-13, joey, aeb
31 .\" Modified 2004-11-16, mtk
33 .TH CTIME 3 2004-11-16 "" "Linux Programmer's Manual"
35 asctime, ctime, gmtime, localtime, mktime, asctime_r, ctime_r, gmtime_r,
36 localtime_r \- transform date and time to broken-down time or ASCII
41 .BI "char *asctime(const struct tm *" tm );
43 .BI "char *asctime_r(const struct tm *" tm ", char *" buf );
45 .BI "char *ctime(const time_t *" timep );
47 .BI "char *ctime_r(const time_t *" timep ", char *" buf );
49 .BI "struct tm *gmtime(const time_t *" timep );
51 .BI "struct tm *gmtime_r(const time_t *" timep ", struct tm *" result );
53 .BI "struct tm *localtime(const time_t *" timep );
55 .BI "struct tm *localtime_r(const time_t *" timep ", struct tm *" result );
57 .BI "time_t mktime(struct tm *" tm );
60 The \fBctime\fP(), \fBgmtime\fP() and \fBlocaltime\fP() functions all take
61 an argument of data type \fItime_t\fP which represents calendar time.
62 When interpreted as an absolute time value, it represents the number of
63 seconds elapsed since 00:00:00 on January 1, 1970, Coordinated Universal
66 The \fBasctime\fP() and \fBmktime\fP() functions both take an argument
67 representing broken-down time which is a representation
68 separated into year, month, day, etc.
70 Broken-down time is stored
71 in the structure \fItm\fP which is defined in \fI<time.h>\fP as follows:
76 int tm_sec; /* seconds */
77 int tm_min; /* minutes */
78 int tm_hour; /* hours */
79 int tm_mday; /* day of the month */
80 int tm_mon; /* month */
81 int tm_year; /* year */
82 int tm_wday; /* day of the week */
83 int tm_yday; /* day in the year */
84 int tm_isdst; /* daylight saving time */
89 The members of the \fItm\fP structure are:
92 The number of seconds after the minute, normally in the range 0 to 59,
93 but can be up to 60 to allow for leap seconds.
96 The number of minutes after the hour, in the range 0 to 59.
99 The number of hours past midnight, in the range 0 to 23.
102 The day of the month, in the range 1 to 31.
105 The number of months since January, in the range 0 to 11.
108 The number of years since 1900.
111 The number of days since Sunday, in the range 0 to 6.
114 The number of days since January 1, in the range 0 to 365.
117 A flag that indicates whether daylight saving time is in effect at the
118 time described. The value is positive if daylight saving time is in
119 effect, zero if it is not, and negative if the information is not
125 .BI asctime(localtime( t )) \fR.
126 It converts the calendar time \fIt\fP into a string of the form
129 "Wed Jun 30 21:49:08 1993\\n"
132 The abbreviations for the days of the week are `Sun', `Mon', `Tue', `Wed',
133 `Thu', `Fri', and `Sat'. The abbreviations for the months are `Jan',
134 `Feb', `Mar', `Apr', `May', `Jun', `Jul', `Aug', `Sep', `Oct', `Nov', and
135 `Dec'. The return value points to a statically allocated string which
136 might be overwritten by subsequent calls to any of the date and time
137 functions. The function also sets the external variable \fItzname\fP (see
139 with information about the current time zone.
140 The re-entrant version \fBctime_r\fP() does the same, but stores the
141 string in a user-supplied buffer of length at least 26. It need not
144 The \fBgmtime\fP() function converts the calendar time \fItimep\fP to
145 broken-down time representation, expressed in Coordinated Universal Time
146 (UTC). It may return NULL when the year does not fit into an integer.
147 The return value points to a statically allocated struct which might be
148 overwritten by subsequent calls to any of the date and time functions.
149 The \fBgmtime_r\fP() function does the same, but stores the data in a
150 user-supplied struct.
152 The \fBlocaltime\fP() function converts the calendar time \fItimep\fP to
153 broken-time representation, expressed relative to the user's specified
154 time zone. The function acts as if it called
156 and sets the external variables \fItzname\fP with
157 information about the current time zone, \fItimezone\fP with the difference
158 between Coordinated Universal Time (UTC) and local standard time in
159 seconds, and \fIdaylight\fP to a non-zero value if daylight savings
160 time rules apply during some part of the year.
161 The return value points to a statically allocated struct which might be
162 overwritten by subsequent calls to any of the date and time functions.
163 The \fBlocaltime_r\fP() function does the same, but stores the data in a
164 user-supplied struct. It need not set \fItzname\fP.
166 The \fBasctime\fP() function converts the broken-down time value
167 \fItm\fP into a string with the same format as \fBctime\fP().
168 The return value points to a statically allocated string which might be
169 overwritten by subsequent calls to any of the date and time functions.
170 The \fBasctime_r\fP() function does the same, but stores the string in
171 a user-supplied buffer of length at least 26.
173 The \fBmktime\fP() function converts a broken-down time structure, expressed
174 as local time, to calendar time representation. The function ignores
175 the specified contents of the structure members \fItm_wday\fP and \fItm_yday\fP
176 and recomputes them from the other information in the broken-down time
178 If structure members are outside their legal interval, they will be
179 normalized (so that, e.g., 40 October is changed into 9 November).
180 Calling \fBmktime\fP() also sets the external variable \fItzname\fP with
181 information about the current time zone. If the specified broken-down
182 time cannot be represented as calendar time (seconds since the epoch),
183 \fBmktime\fP() returns a value of (time_t)(\-1) and does not alter the
184 \fItm_wday\fP and \fItm_yday\fP members of the broken-down time structure.
186 Each of these functions returns the value described, or NULL
187 (\-1 in case of \fBmktime\fP()) in case an error was detected.
195 return a pointer to static data and hence are not thread-safe.
202 are specified by SUSv2, and available since libc 5.2.5.
204 In many implementations, including
208 is interpreted as meaning the last day of the preceding month.
210 The glibc version of struct tm has additional fields
214 long tm_gmtoff; /* Seconds east of UTC */
215 const char *tm_zone; /* Timezone abbreviation */
219 defined when _BSD_SOURCE was set before including
221 This is a BSD extension, present in 4.3BSD-Reno.
223 SVID 3, POSIX, 4.3BSD, ISO 9899
226 .BR gettimeofday (2),