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