Commit | Line | Data |
---|---|---|
637a994b KB |
1 | .\" Copyright (c) 1989 The Regents of the University of California. |
2 | .\" All rights reserved. | |
463d6749 | 3 | .\" |
637a994b KB |
4 | .\" This code is derived from software contributed to Berkeley by |
5 | .\" Arthur Olson. | |
463d6749 | 6 | .\" |
637a994b KB |
7 | .\" Redistribution and use in source and binary forms are permitted |
8 | .\" provided that the above copyright notice and this paragraph are | |
9 | .\" duplicated in all such forms and that any documentation, | |
10 | .\" advertising materials, and other materials related to such | |
11 | .\" distribution and use acknowledge that the software was developed | |
12 | .\" by the University of California, Berkeley. The name of the | |
13 | .\" University may not be used to endorse or promote products derived | |
14 | .\" from this software without specific prior written permission. | |
15 | .\" THIS SOFTWARE IS PROVIDED ``AS IS'' AND WITHOUT ANY EXPRESS OR | |
16 | .\" IMPLIED WARRANTIES, INCLUDING, WITHOUT LIMITATION, THE IMPLIED | |
17 | .\" WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. | |
18 | .\" | |
de716a99 | 19 | .\" @(#)ctime.3 6.11 (Berkeley) %G% |
637a994b KB |
20 | .\" |
21 | .TH CTIME 3 "" | |
463d6749 | 22 | .SH NAME |
637a994b | 23 | asctime, ctime, difftime, gmtime, localtime, mktime, tzset, tzsetwall \- convert date and time to ASCII |
463d6749 KM |
24 | .SH SYNOPSIS |
25 | .nf | |
637a994b KB |
26 | .B extern char *tzname[2]; |
27 | .PP | |
94c2eda1 KB |
28 | .B void tzset() |
29 | .PP | |
637a994b KB |
30 | .B void tzsetwall() |
31 | .PP | |
32 | .B #include <sys/types.h> | |
33 | .PP | |
463d6749 | 34 | .B char *ctime(clock) |
94c2eda1 | 35 | .B time_t *clock; |
463d6749 | 36 | .PP |
637a994b KB |
37 | .B double difftime(time1, time0) |
38 | .B time_t time1; | |
39 | .B time_t time0; | |
40 | .PP | |
2ad48aae | 41 | .B #include <time.h> |
463d6749 | 42 | .PP |
94c2eda1 KB |
43 | .B char *asctime(tm) |
44 | .B struct tm *tm; | |
45 | .PP | |
463d6749 | 46 | .B struct tm *localtime(clock) |
637a994b | 47 | .B long *clock; |
463d6749 KM |
48 | .PP |
49 | .B struct tm *gmtime(clock) | |
637a994b | 50 | .B long *clock; |
463d6749 | 51 | .PP |
637a994b KB |
52 | .B time_t mktime(tm) |
53 | .B struct tm *tm; | |
94c2eda1 | 54 | .fi |
463d6749 | 55 | .SH DESCRIPTION |
637a994b KB |
56 | .I Tzset |
57 | uses the value of the environment variable | |
58 | .B TZ | |
59 | to set time conversion information used by | |
60 | .IR localtime . | |
61 | If | |
62 | .B TZ | |
63 | does not appear in the environment, | |
64 | the best available approximation to local wall clock time, as specified | |
65 | by the | |
66 | .IR tzfile (5)-format | |
67 | file | |
68 | .B localtime | |
69 | in the system time conversion information directory, is used by | |
70 | .IR localtime . | |
71 | If | |
72 | .B TZ | |
73 | appears in the environment but its value is a null string, | |
74 | Coordinated Universal Time (UTC) is used (without leap second | |
75 | correction). If | |
76 | .B TZ | |
77 | appears in the environment and its value is not a null string: | |
78 | .IP | |
79 | if the value begins with a colon, it is used as a pathname of a file | |
80 | from which to read the time conversion information; | |
81 | .IP | |
82 | if the value does not begin with a colon, it is first used as the | |
83 | pathname of a file from which to read the time conversion information, | |
84 | and, if that file cannot be read, is used directly as a specification of | |
85 | the time conversion information. | |
86 | .PP | |
87 | When | |
88 | .B TZ | |
89 | is used as a pathname, if it begins with a slash, | |
90 | it is used as an absolute pathname; otherwise, | |
91 | it is used as a pathname relative to a system time conversion information | |
92 | directory. | |
93 | The file must be in the format specified in | |
94 | .IR tzfile (5). | |
95 | .PP | |
96 | When | |
97 | .B TZ | |
98 | is used directly as a specification of the time conversion information, | |
99 | it must have the following syntax (spaces inserted for clarity): | |
100 | .IP | |
101 | \fIstd\|offset\fR[\fIdst\fR[\fIoffset\fR][\fB,\fIrule\fR]] | |
102 | .PP | |
103 | Where: | |
104 | .RS | |
105 | .TP 15 | |
106 | .IR std " and " dst | |
107 | Three or more bytes that are the designation for the standard | |
108 | .RI ( std ) | |
109 | or summer | |
110 | .RI ( dst ) | |
111 | time zone. Only | |
112 | .I std | |
113 | is required; if | |
114 | .I dst | |
115 | is missing, then summer time does not apply in this locale. | |
116 | Upper- and lowercase letters are explicitly allowed. Any characters | |
117 | except a leading colon | |
118 | .RB ( : ), | |
119 | digits, comma | |
120 | .RB ( , ), | |
121 | minus | |
122 | .RB ( \(mi ), | |
123 | plus | |
124 | .RB ( \(pl ), | |
125 | and ASCII NUL are allowed. | |
126 | .TP | |
127 | .I offset | |
128 | Indicates the value one must add to the local time to arrive at | |
129 | Coordinated Universal Time. The | |
130 | .I offset | |
131 | has the form: | |
132 | .RS | |
133 | .IP | |
134 | \fIhh\fR[\fB:\fImm\fR[\fB:\fIss\fR]] | |
135 | .RE | |
136 | .IP | |
137 | The minutes | |
138 | .RI ( mm ) | |
139 | and seconds | |
140 | .RI ( ss ) | |
141 | are optional. The hour | |
142 | .RI ( hh ) | |
143 | is required and may be a single digit. The | |
144 | .I offset | |
145 | following | |
146 | .I std | |
147 | is required. If no | |
148 | .I offset | |
149 | follows | |
150 | .IR dst , | |
151 | summer time is assumed to be one hour ahead of standard time. One or | |
152 | more digits may be used; the value is always interpreted as a decimal | |
153 | number. The hour must be between zero and 24, and the minutes (and | |
154 | seconds) \(em if present \(em between zero and 59. If preceded by a | |
155 | .RB `` \(mi '', | |
156 | the time zone shall be east of the Prime Meridian; otherwise it shall be | |
157 | west (which may be indicated by an optional preceding | |
158 | .RB `` \(pl ''). | |
159 | .TP | |
160 | .I rule | |
161 | Indicates when to change to and back from summer time. The | |
162 | .I rule | |
163 | has the form: | |
164 | .RS | |
165 | .IP | |
166 | \fIdate\fB/\fItime\fB,\fIdate\fB/\fItime\fR | |
167 | .RE | |
168 | .IP | |
169 | where the first | |
170 | .I date | |
171 | describes when the change from standard to summer time occurs and the | |
172 | second | |
173 | .I date | |
174 | describes when the change back happens. Each | |
175 | .I time | |
176 | field describes when, in current local time, the change to the other | |
177 | time is made. | |
178 | .IP | |
179 | The format of | |
180 | .I date | |
181 | is one of the following: | |
182 | .RS | |
183 | .TP 10 | |
184 | .BI J n | |
185 | The Julian day | |
186 | .I n | |
187 | .RI "(1\ \(<=" "\ n\ " "\(<=\ 365). | |
188 | Leap days are not counted; that is, in all years \(em including leap | |
189 | years \(em February 28 is day 59 and March 1 is day 60. It is | |
190 | impossible to explicitly refer to the occasional February 29. | |
191 | .TP | |
192 | .I n | |
193 | The zero-based Julian day | |
194 | .RI "(0\ \(<=" "\ n\ " "\(<=\ 365). | |
195 | Leap days are counted, and it is possible to refer to February 29. | |
196 | .TP | |
197 | .BI M m . n . d | |
198 | The | |
199 | .IR d' th | |
200 | day | |
201 | .RI "(0\ \(<=" "\ d\ " "\(<=\ 6) | |
202 | of week | |
203 | .I n | |
204 | of month | |
205 | .I m | |
206 | of the year | |
207 | .RI "(1\ \(<=" "\ n\ " "\(<=\ 5, | |
208 | .RI "1\ \(<=" "\ m\ " "\(<=\ 12, | |
209 | where week 5 means ``the last | |
210 | .I d | |
211 | day in month | |
212 | .IR m '' | |
213 | which may occur in either the fourth or the fifth week). Week 1 is the | |
214 | first week in which the | |
215 | .IR d' th | |
216 | day occurs. Day zero is Sunday. | |
217 | .RE | |
218 | .IP "" 15 | |
219 | The | |
220 | .I time | |
221 | has the same format as | |
222 | .I offset | |
223 | except that no leading sign | |
224 | .RB (`` \(mi '' | |
225 | or | |
226 | .RB `` \(pl '') | |
227 | is allowed. The default, if | |
228 | .I time | |
229 | is not given, is | |
230 | .BR 02:00:00 . | |
231 | .RE | |
232 | .LP | |
233 | If no | |
234 | .I rule | |
235 | is present in | |
236 | .BR TZ , | |
237 | the rules specified | |
238 | by the | |
239 | .IR tzfile (5)-format | |
240 | file | |
241 | .B posixrules | |
242 | in the system time conversion information directory are used, with the | |
243 | standard and summer time offsets from UTC replaced by those specified by | |
244 | the | |
245 | .I offset | |
246 | values in | |
247 | .BR TZ . | |
248 | .PP | |
249 | For compatibility with System V Release 3.1, a semicolon | |
250 | .RB ( ; ) | |
251 | may be used to separate the | |
252 | .I rule | |
253 | from the rest of the specification. | |
254 | .PP | |
255 | If the | |
256 | .B TZ | |
257 | environment variable does not specify a | |
258 | .IR tzfile (5)-format | |
259 | and cannot be interpreted as a direct specification, | |
de716a99 | 260 | UTC is used. |
637a994b KB |
261 | .PP |
262 | .I Tzsetwall | |
263 | sets things up so that | |
264 | .I localtime | |
265 | returns the best available approximation of local wall clock time. | |
266 | .PP | |
267 | .I Ctime\^ | |
268 | converts a long integer, pointed to by | |
269 | .IR clock , | |
270 | representing the time in seconds since | |
271 | 00:00:00 UTC, January 1, 1970, | |
272 | and returns a pointer to a | |
273 | 26-character string | |
274 | of the form | |
275 | .br | |
276 | .ce | |
277 | .eo | |
278 | Thu Nov 24 18:22:48 1986\n\0 | |
279 | .ec | |
280 | .br | |
281 | All the fields have constant width. | |
282 | .PP | |
283 | .IR Localtime\^ | |
463d6749 | 284 | and |
637a994b KB |
285 | .I gmtime\^ |
286 | return pointers to ``tm'' structures, described below. | |
287 | .I Localtime\^ | |
288 | corrects for the time zone and any time zone adjustments | |
289 | (such as Daylight Saving Time in the U.S.A.). | |
290 | Before doing so, | |
291 | .I localtime\^ | |
292 | calls | |
293 | .I tzset\^ | |
294 | (if | |
295 | .I tzset\^ | |
296 | has not been called in the current process). | |
297 | After filling in the ``tm'' structure, | |
298 | .I localtime | |
299 | sets the | |
300 | .BR tm_isdst 'th | |
301 | element of | |
302 | .B tzname | |
303 | to a pointer to an | |
304 | ASCII string that's the time zone abbreviation to be used with | |
305 | .IR localtime 's | |
306 | return value. | |
307 | .PP | |
308 | .I Gmtime\^ | |
309 | converts to Coordinated Universal Time. | |
310 | .PP | |
311 | .I Asctime\^ | |
312 | converts a time value contained in a | |
313 | ``tm'' structure to a 26-character string, | |
314 | as shown in the above example, | |
315 | and returns a pointer | |
316 | to the string. | |
463d6749 | 317 | .PP |
637a994b KB |
318 | .I Mktime\^ |
319 | converts the broken-down time, | |
320 | expressed as local time, | |
321 | in the structure pointed to by | |
322 | .I tm | |
323 | into a calendar time value with the same encoding as that of the values | |
324 | returned by the | |
325 | .I time | |
326 | function. | |
327 | The original values of the | |
328 | .B tm_wday | |
329 | and | |
330 | .B tm_yday | |
331 | components of the structure are ignored, | |
332 | and the original values of the other components are not restricted | |
333 | to their normal ranges. | |
334 | (A positive or zero value for | |
335 | .B tm_isdst | |
336 | causes | |
337 | .I mktime | |
338 | to presume initially that summer time (for example, Daylight Saving Time | |
339 | in the U.S.A.) | |
340 | respectively, | |
341 | is or is not in effect for the specified time. | |
342 | A negative value for | |
343 | .B tm_isdst | |
344 | causes the | |
345 | .I mktime | |
346 | function to attempt to divine whether summer time is in effect | |
347 | for the specified time.) | |
348 | On successful completion, the values of the | |
349 | .B tm_wday | |
350 | and | |
351 | .B tm_yday | |
352 | components of the structure are set appropriately, | |
353 | and the other components are set to represent the specified calendar time, | |
354 | but with their values forced to their normal ranges; the final value of | |
355 | .B tm_mday | |
356 | is not set until | |
357 | .B tm_mon | |
358 | and | |
359 | .B tm_year | |
360 | are determined. | |
361 | .I Mktime\^ | |
362 | returns the specified calendar time; | |
363 | If the calendar time cannot be represented, | |
364 | it returns | |
365 | .BR -1 . | |
366 | .PP | |
367 | .I Difftime\^ | |
368 | returns the difference between two calendar times, | |
369 | .I time1 | |
370 | - | |
371 | .IR time0, | |
372 | expressed in seconds. | |
373 | .PP | |
374 | Declarations of all the functions and externals, and the ``tm'' structure, | |
375 | are in the | |
376 | .B <time.h>\^ | |
377 | header file. | |
378 | The structure (of type) | |
379 | .B struct tm | |
380 | includes the following fields: | |
8eafd288 | 381 | .RS |
637a994b | 382 | .PP |
463d6749 | 383 | .nf |
637a994b KB |
384 | .ta .5i +\w'long tm_gmtoff;\0\0'u |
385 | int tm_sec; /\(** seconds (0 - 60) \(**/ | |
386 | int tm_min; /\(** minutes (0 - 59) \(**/ | |
387 | int tm_hour; /\(** hours (0 - 23) \(**/ | |
388 | int tm_mday; /\(** day of month (1 - 31) \(**/ | |
389 | int tm_mon; /\(** month of year (0 - 11) \(**/ | |
390 | int tm_year; /\(** year \- 1900 \(**/ | |
391 | int tm_wday; /\(** day of week (Sunday = 0) \(**/ | |
392 | int tm_yday; /\(** day of year (0 - 365) \(**/ | |
393 | int tm_isdst; /\(** is summer time in effect? \(**/ | |
394 | char \(**tm_zone; /\(** abbreviation of timezone name \(**/ | |
395 | long tm_gmtoff; /\(** offset from UTC in seconds \(**/ | |
463d6749 KM |
396 | .fi |
397 | .RE | |
398 | .PP | |
637a994b KB |
399 | The |
400 | .I tm_zone | |
401 | and | |
402 | .I tm_gmtoff | |
403 | fields exist, and are filled in, only if arrangements to do | |
404 | so were made when the library containing these functions was | |
405 | created. | |
406 | There is no guarantee that these fields will continue to exist | |
407 | in this form in future releases of this code. | |
408 | .PP | |
409 | .I Tm_isdst\^ | |
410 | is non-zero if summer time is in effect. | |
411 | .PP | |
412 | .I Tm_gmtoff | |
413 | is the offset (in seconds) of the time represented | |
414 | from UTC, with positive values indicating east | |
415 | of the Prime Meridian. | |
94c2eda1 | 416 | .SH FILES |
637a994b | 417 | .ta \w'/etc/zoneinfo/posixrules\0\0'u |
94c2eda1 KB |
418 | /etc/zoneinfo time zone information directory |
419 | .br | |
420 | /etc/zoneinfo/localtime local time zone file | |
637a994b KB |
421 | .br |
422 | /etc/zoneinfo/posixrules used in converting POSIX-style TZ's | |
423 | .br | |
424 | /etc/zoneinfo/GMT for UTC leap seconds | |
425 | .sp | |
426 | If | |
427 | .I /etc/zoneinfo/GMT | |
428 | is absent, | |
429 | UTC leap seconds are loaded from | |
430 | .IR /etc/zoneinfo/posixrules . | |
94c2eda1 | 431 | .SH SEE ALSO |
637a994b KB |
432 | time(2), getenv(3), tzfile(5) |
433 | .SH NOTES | |
434 | The return values point to static data | |
435 | whose content is overwritten by each call. | |
436 | The | |
437 | .B tm_zone | |
438 | field of a returned | |
439 | .B "struct tm" | |
440 | points to a static array of characters, which | |
441 | will also be overwritten at the next call | |
442 | (and by calls to | |
443 | .I tzset | |
444 | or | |
445 | .IR tzsetwall ). | |
446 | .PP | |
447 | Avoid using out-of-range values with | |
448 | .I mktime | |
449 | when setting up lunch with promptness sticklers in Riyadh. |