]>
Commit | Line | Data |
---|---|---|
fea681da MK |
1 | .\" Copyright 1993 David Metcalfe (david@prism.demon.co.uk) |
2 | .\" | |
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. | |
6 | .\" | |
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. | |
c13182ef | 11 | .\" |
fea681da MK |
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 | |
18 | .\" professionally. | |
c13182ef | 19 | .\" |
fea681da MK |
20 | .\" Formatted or processed versions of this manual, if unaccompanied by |
21 | .\" the source, must acknowledge the copyright and authors of this work. | |
22 | .\" | |
23 | .\" References consulted: | |
24 | .\" Linux libc source code | |
25 | .\" Lewine's _POSIX Programmer's Guide_ (O'Reilly & Associates, 1991) | |
26 | .\" 386BSD man pages | |
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 | |
3e53c142 | 31 | .\" Modified 2004-11-16, mtk |
fea681da | 32 | .\" |
9ef659a9 | 33 | .TH CTIME 3 2008-09-26 "" "Linux Programmer's Manual" |
fea681da MK |
34 | .SH NAME |
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 | |
37 | .SH SYNOPSIS | |
38 | .nf | |
39 | .B #include <time.h> | |
40 | .sp | |
41 | .BI "char *asctime(const struct tm *" tm ); | |
42 | .br | |
43 | .BI "char *asctime_r(const struct tm *" tm ", char *" buf ); | |
44 | .sp | |
45 | .BI "char *ctime(const time_t *" timep ); | |
46 | .br | |
47 | .BI "char *ctime_r(const time_t *" timep ", char *" buf ); | |
48 | .sp | |
49 | .BI "struct tm *gmtime(const time_t *" timep ); | |
50 | .br | |
51 | .BI "struct tm *gmtime_r(const time_t *" timep ", struct tm *" result ); | |
52 | .sp | |
53 | .BI "struct tm *localtime(const time_t *" timep ); | |
54 | .br | |
55 | .BI "struct tm *localtime_r(const time_t *" timep ", struct tm *" result ); | |
56 | .sp | |
57 | .BI "time_t mktime(struct tm *" tm ); | |
58 | .fi | |
cc4615cc MK |
59 | .sp |
60 | .in -4n | |
61 | Feature Test Macro Requirements for glibc (see | |
62 | .BR feature_test_macros (7)): | |
63 | .in | |
64 | .sp | |
65 | .BR asctime_r (), | |
66 | .BR ctime_r (), | |
67 | .BR gmtime_r (), | |
68 | .BR localtime_r (): | |
69 | .br | |
0f200f07 MK |
70 | _POSIX_C_SOURCE\ >=\ 1 || _XOPEN_SOURCE || _BSD_SOURCE || |
71 | _SVID_SOURCE || _POSIX_SOURCE | |
fea681da | 72 | .SH DESCRIPTION |
60a90ecd MK |
73 | The |
74 | .BR ctime (), | |
75 | .BR gmtime () | |
76 | and | |
77 | .BR localtime () | |
78 | functions all take | |
fea681da MK |
79 | an argument of data type \fItime_t\fP which represents calendar time. |
80 | When interpreted as an absolute time value, it represents the number of | |
81 | seconds elapsed since 00:00:00 on January 1, 1970, Coordinated Universal | |
82 | Time (UTC). | |
83 | .PP | |
60a90ecd MK |
84 | The |
85 | .BR asctime () | |
86 | and | |
87 | .BR mktime () | |
88 | functions both take an argument | |
fea681da MK |
89 | representing broken-down time which is a representation |
90 | separated into year, month, day, etc. | |
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 | .sp | |
bd191423 | 95 | .in +4n |
fea681da | 96 | .nf |
fea681da | 97 | struct tm { |
6c98e324 MK |
98 | int tm_sec; /* seconds */ |
99 | int tm_min; /* minutes */ | |
100 | int tm_hour; /* hours */ | |
101 | int tm_mday; /* day of the month */ | |
102 | int tm_mon; /* month */ | |
103 | int tm_year; /* year */ | |
104 | int tm_wday; /* day of the week */ | |
105 | int tm_yday; /* day in the year */ | |
106 | int tm_isdst; /* daylight saving time */ | |
fea681da | 107 | }; |
fea681da | 108 | .fi |
bd191423 | 109 | .in |
fea681da MK |
110 | .PP |
111 | The members of the \fItm\fP structure are: | |
8fe528b3 | 112 | .TP 10 |
fea681da | 113 | .I tm_sec |
c13182ef | 114 | The number of seconds after the minute, normally in the range 0 to 59, |
7f4f9585 | 115 | but can be up to 60 to allow for leap seconds. |
fea681da MK |
116 | .TP |
117 | .I tm_min | |
c13182ef | 118 | The number of minutes after the hour, in the range 0 to 59. |
fea681da MK |
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 | |
c13182ef MK |
140 | time described. |
141 | The value is positive if daylight saving time is in | |
fea681da MK |
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. | |
0e8fe3b4 MK |
149 | It converts the calendar time \fIt\fP into a |
150 | null-terminated string of the form | |
fea681da MK |
151 | .sp |
152 | .RS | |
153 | "Wed Jun 30 21:49:08 1993\\n" | |
154 | .RE | |
155 | .sp | |
84c517a4 MK |
156 | The abbreviations for the days of the week are "Sun", "Mon", "Tue", "Wed", |
157 | "Thu", "Fri", and "Sat". | |
158 | The abbreviations for the months are "Jan", | |
159 | "Feb", "Mar", "Apr", "May", "Jun", "Jul", "Aug", "Sep", "Oct", "Nov", and | |
160 | "Dec". | |
c13182ef | 161 | The return value points to a statically allocated string which |
fea681da | 162 | might be overwritten by subsequent calls to any of the date and time |
c13182ef MK |
163 | functions. |
164 | The function also sets the external variable \fItzname\fP (see | |
fea681da | 165 | .BR tzset (3)) |
5b0dc1ba | 166 | with information about the current timezone. |
da27f178 | 167 | The reentrant version |
60a90ecd MK |
168 | .BR ctime_r () |
169 | does the same, but stores the | |
ef38dda0 MK |
170 | string in a user-supplied buffer |
171 | which should have room for at least 26 bytes. | |
c13182ef | 172 | It need not |
fea681da MK |
173 | set \fItzname\fP. |
174 | .PP | |
60a90ecd MK |
175 | The |
176 | .BR gmtime () | |
177 | function converts the calendar time \fItimep\fP to | |
fea681da | 178 | broken-down time representation, expressed in Coordinated Universal Time |
c13182ef MK |
179 | (UTC). |
180 | It may return NULL when the year does not fit into an integer. | |
fea681da MK |
181 | The return value points to a statically allocated struct which might be |
182 | overwritten by subsequent calls to any of the date and time functions. | |
60a90ecd MK |
183 | The |
184 | .BR gmtime_r () | |
185 | function does the same, but stores the data in a | |
fea681da MK |
186 | user-supplied struct. |
187 | .PP | |
60a90ecd MK |
188 | The |
189 | .BR localtime () | |
190 | function converts the calendar time \fItimep\fP to | |
fea681da | 191 | broken-time representation, expressed relative to the user's specified |
5b0dc1ba | 192 | timezone. |
c13182ef | 193 | The function acts as if it called |
fea681da | 194 | .BR tzset (3) |
c13182ef | 195 | and sets the external variables \fItzname\fP with |
5b0dc1ba | 196 | information about the current timezone, \fItimezone\fP with the difference |
fea681da | 197 | between Coordinated Universal Time (UTC) and local standard time in |
eba72288 | 198 | seconds, and \fIdaylight\fP to a non-zero value if daylight savings |
fea681da MK |
199 | time rules apply during some part of the year. |
200 | The return value points to a statically allocated struct which might be | |
201 | overwritten by subsequent calls to any of the date and time functions. | |
60a90ecd MK |
202 | The |
203 | .BR localtime_r () | |
204 | function does the same, but stores the data in a | |
c13182ef MK |
205 | user-supplied struct. |
206 | It need not set \fItzname\fP. | |
fea681da | 207 | .PP |
60a90ecd MK |
208 | The |
209 | .BR asctime () | |
210 | function converts the broken-down time value | |
0e8fe3b4 | 211 | \fItm\fP into a null-terminated string with the same format as |
60a90ecd | 212 | .BR ctime (). |
c13182ef | 213 | The return value points to a statically allocated string which might be |
fea681da | 214 | overwritten by subsequent calls to any of the date and time functions. |
60a90ecd MK |
215 | The |
216 | .BR asctime_r () | |
217 | function does the same, but stores the string in | |
ef38dda0 | 218 | a user-supplied buffer which should have room for at least 26 bytes. |
fea681da | 219 | .PP |
60a90ecd MK |
220 | The |
221 | .BR mktime () | |
222 | function converts a broken-down time structure, expressed | |
c13182ef MK |
223 | as local time, to calendar time representation. |
224 | The function ignores | |
9ef659a9 MK |
225 | the values supplied by the caller in the |
226 | .I tm_wday | |
227 | and | |
228 | .I tm_yday | |
229 | fields. | |
f9db4400 MK |
230 | The value specified in the |
231 | .I tm_isdst | |
232 | field informs | |
233 | .BR mktime () | |
234 | whether or not daylight saving time (DST) | |
235 | is in effect for the time supplied in the | |
236 | .I tm | |
237 | structure: | |
238 | a positive value means DST is in effect; | |
239 | zero means that DST is not in effect; | |
240 | and a negative value means that | |
9ef659a9 | 241 | .BR mktime () |
f9db4400 MK |
242 | should (use timezone information and system databases to) |
243 | attempt to determine whether DST is in effect at the specified time. | |
244 | ||
245 | The | |
246 | .BR mktime () | |
247 | function modifies the fields of the | |
9ef659a9 MK |
248 | .IR tm |
249 | structure as follows: | |
250 | .I tm_wday | |
251 | and | |
252 | .I tm_yday | |
253 | are set to values determined from the contents of the other fields; | |
254 | if structure members are outside their valid interval, they will be | |
f9db4400 MK |
255 | normalized (so that, for example, 40 October is changed into 9 November); |
256 | .I tm_isdst | |
257 | is set (regardless of its initial value) | |
258 | to a positive value or to 0, respectively, | |
259 | to indicate whether DST is or is not in effect at the specified time. | |
60a90ecd MK |
260 | Calling |
261 | .BR mktime () | |
262 | also sets the external variable \fItzname\fP with | |
5b0dc1ba | 263 | information about the current timezone. |
f9db4400 | 264 | |
c13182ef | 265 | If the specified broken-down |
be9634cf | 266 | time cannot be represented as calendar time (seconds since the Epoch), |
60a90ecd | 267 | .BR mktime () |
7d2cb9d5 | 268 | returns a value of |
009df872 | 269 | .I (time_t)\ \-1 |
7d2cb9d5 | 270 | and does not alter the |
f9db4400 | 271 | members of the broken-down time structure. |
fea681da MK |
272 | .SH "RETURN VALUE" |
273 | Each of these functions returns the value described, or NULL | |
60a90ecd MK |
274 | (\-1 in case of |
275 | .BR mktime ()) | |
276 | in case an error was detected. | |
2b2581ee MK |
277 | .SH "CONFORMING TO" |
278 | POSIX.1-2001. | |
279 | C89 and C99 specify | |
280 | .BR asctime (), | |
281 | .BR ctime (), | |
282 | .BR gmtime (), | |
283 | .BR localtime (), | |
284 | and | |
44a2c328 | 285 | .BR mktime (). |
ca5711a5 MK |
286 | POSIX.1-2008 marks |
287 | .BR asctime (), | |
288 | .BR asctime_r (), | |
289 | .BR ctime (), | |
290 | and | |
291 | .BR ctime_r () | |
292 | as obsolete. | |
fea681da MK |
293 | .SH NOTES |
294 | The four functions | |
63aa9df0 MK |
295 | .BR asctime (), |
296 | .BR ctime (), | |
297 | .BR gmtime () | |
fea681da | 298 | and |
63aa9df0 | 299 | .BR localtime () |
fea681da MK |
300 | return a pointer to static data and hence are not thread-safe. |
301 | Thread-safe versions | |
63aa9df0 MK |
302 | .BR asctime_r (), |
303 | .BR ctime_r (), | |
304 | .BR gmtime_r () | |
fea681da | 305 | and |
63aa9df0 | 306 | .BR localtime_r () |
fea681da | 307 | are specified by SUSv2, and available since libc 5.2.5. |
8167059b MK |
308 | |
309 | POSIX.1-2001 says: | |
310 | "The | |
311 | .BR asctime (), | |
312 | .BR ctime (), | |
313 | .BR gmtime (), | |
314 | and | |
315 | .BR localtime () | |
316 | functions shall return values in one of two static objects: | |
317 | a broken-down time structure and an array of type | |
318 | .IR char . | |
319 | Execution of any of the functions may overwrite the information returned | |
320 | in either of these objects by any of the other functions." | |
321 | This can occur in the glibc implementation. | |
fea681da | 322 | .LP |
8167059b | 323 | In many implementations, including glibc, a 0 in |
3e53c142 MK |
324 | .I tm_mday |
325 | is interpreted as meaning the last day of the preceding month. | |
326 | .LP | |
0c2ec4f1 | 327 | The glibc version of \fIstruct tm\fP has additional fields |
fea681da MK |
328 | .sp |
329 | .RS | |
330 | .nf | |
331 | long tm_gmtoff; /* Seconds east of UTC */ | |
332 | const char *tm_zone; /* Timezone abbreviation */ | |
333 | .fi | |
334 | .RE | |
335 | .sp | |
db4e96b7 MK |
336 | defined when |
337 | .B _BSD_SOURCE | |
338 | was set before including | |
fea681da MK |
339 | .IR <time.h> . |
340 | This is a BSD extension, present in 4.3BSD-Reno. | |
7b16ff49 MK |
341 | |
342 | According to POSIX.1-2004, | |
343 | .BR localtime () | |
344 | is required to behave as though | |
345 | .BR tzset () | |
346 | was called, while | |
347 | .BR localtime_r () | |
348 | does not have this requirement. | |
349 | .\" See http://thread.gmane.org/gmane.comp.time.tz/2034/ | |
350 | For portable code | |
351 | .BR tzset () | |
352 | should be called before | |
353 | .BR localtime_r (). | |
fea681da MK |
354 | .SH "SEE ALSO" |
355 | .BR date (1), | |
356 | .BR gettimeofday (2), | |
357 | .BR time (2), | |
358 | .BR utime (2), | |
359 | .BR clock (3), | |
360 | .BR difftime (3), | |
fea681da MK |
361 | .BR strftime (3), |
362 | .BR strptime (3), | |
7877f012 | 363 | .BR timegm (3), |
eafd5ce1 MK |
364 | .BR tzset (3), |
365 | .BR time (7) |