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