| blob | 12eb4ecf4a573a7f1e1850f9f3143549c9e16d21 |
1 .fp 5 CW
2 .de Af
3 .ds ;G \\*(;G\\f\\$1\\$3\\f\\$2
5 ..
6 .de aF
8 .el \{\
9 .ds ;G \&
10 .nr ;G \\n(.f
11 .Af "\\$1" "\\$2" "\\$3" "\\$4" "\\$5" "\\$6" "\\$7" "\\$8" "\\$9"
12 \\*(;G
13 .ft \\n(;G \}
14 ..
15 .de L
16 .aF 5 \\n(.f "\\$1" "\\$2" "\\$3" "\\$4" "\\$5" "\\$6" "\\$7"
17 ..
18 .de LR
19 .aF 5 1 "\\$1" "\\$2" "\\$3" "\\$4" "\\$5" "\\$6" "\\$7"
20 ..
21 .de RL
22 .aF 1 5 "\\$1" "\\$2" "\\$3" "\\$4" "\\$5" "\\$6" "\\$7"
23 ..
24 .de EX \" start example
25 .ta 1i 2i 3i 4i 5i 6i
26 .PP
27 .RS
28 .PD 0
29 .ft 5
30 .nf
31 ..
32 .de EE \" end example
33 .fi
34 .ft
35 .PD
36 .RE
37 .PP
38 ..
39 .TH TM 3
40 .SH NAME
41 tm \- seconds resolution time conversion support
42 .SH SYNOPSIS
43 .L "#include <tm.h>"
44 .SH DESCRIPTION
45 The
46 .I tm
47 library supports conversion between
48 string date specifications,
49 seconds reolution
50 .L time_t
51 clock values and
52 .LR Tm_t .
53 .L Tm_t
54 contains the elements of
55 .L "struct tm"
56 along with these additions:
57 .TP
58 .L "unsigned _ast_int4_t tm_nsec"
59 The subsecond portion of the time in nanoseconds.
60 .TP
61 .L "Tm_zone_t* tm_zone"
62 The time zone name.
63 .PP
64 .L localtime()
65 and
66 .L gmtime()
67 (see
68 .BR ctime (3))
69 are used to determine local time zone and savings time information.
70 .PP
71 .L time_t
72 values are the number of seconds since the epoch,
73 .BR "Jan 1 00:00:00 GMT 1970" ,
74 with leap seconds omitted.
75 .PP
76 The global variable
77 .L "int tm_info.flags"
78 contains flags that allow all programs using the library
79 to be controlled in a consistent manner.
80 .L tm_info.flags
81 is initialized by the
82 .L tminit()
83 routine described below, and may be explicitly reset after
84 .L tminit()
85 is called.
86 The flags are:
87 .TP
88 .L TM_ADJUST
89 Set by
90 .L tminit()
91 if
92 .L localtime()
93 and
94 .L gmtime()
95 do not compensate for leap seconds.
96 .TP
97 .L TM_LEAP
98 .L time_t
99 values are interpreted as if they include leap seconds.
100 Set by
101 .L tminit()
102 if the
103 .L leap
104 option is set in the
105 .L TM_OPTIONS
106 environment variable.
107 .TP
108 .L TM_UTC
109 Times are relative to
110 .B UTC
111 (universal coordinated time, i.e.,
112 .BR GMT .)
113 Otherwise times are relative to the local time zone.
114 Set by
115 .L tminit()
116 if the time zone name matches one of
117 .L tm_info.format[43]
118 through
119 .L tm_info.format[46]
120 described below.
121 If the time zone name is not determined by
122 .L localtime()
123 then the environment variables
124 .L TZNAME
125 (as described in BSD 4.3) and
126 .L TZ
127 (as described in System V)
128 are checked, in order.
129 If this fails then the time zone name is constructed using
130 the local time zone offset.
131 .PP
132 The routines are:
133 .TP
134 .L "time_t tmdate(const char* date, char** end, time_t* clock)"
135 Parses the date specification
136 .L date
137 using the
138 .L tm_info.format
139 string table (described below)
140 and returns the equivalent
141 .L time_t
142 value.
143 If
144 .RL non- NULL ,
145 .L end
146 is set to the position of the first unrecognized character in
147 .LR date .
148 .L clock
149 is used to provide default values for omitted components in
150 .LR date .
151 If
152 .L clock
153 is
154 .L NULL
155 then the current time is used.
156 .TP
157 .L "Tm_t* tmfix(Tm_t* tp)"
158 Corrects any out of bounds fields in
159 .L tp
160 and returns
161 .L tp
162 as its value.
163 The corrections start with
164 .L tp->tm_sec
165 and propagate down to
166 .LR tp->tm_year .
167 For example, if
168 .L tp->tm_sec
169 were 61 then it would change to 1 and
170 .L tp->tm_min
171 would be incremented by 1, and so on.
172 .L tp->tm_isdst
173 is not changed -- call
174 .L tmtime()
175 to determine its proper value after the
176 .L tmfix()
177 adjustments.
178 .TP
179 .L "char* tmfmt(char* buf, size_t len, const char* format, time_t* clock)"
180 Formats the date pointed to by
181 .L clock
182 into the buffer
183 .L buf
184 with size
185 .L len
186 bytes according to the format specification
187 .LR format .
188 If
189 .L format
190 is
191 .L NULL
192 or empty then the string
193 .L tm_info.format[40]
194 is used.
195 If
196 .L clock
197 is
198 .L NULL
199 then the current time is used.
200 A pointer to the end of
201 .L buf
202 (i.e., the terminating
203 .LR "'\e0'" )
204 is returned.
205 .RS
206 .PP
207 .L format
208 is in
209 .BR printf (3)
210 style, where
211 .RI % field
212 names a fixed size field, zero padded if necessary,
213 and
214 .I \ec
215 and
216 .I \ennn
217 sequences are as in C. Invalid
218 .RI % field
219 specifications and all other characters are copied
220 without change.
221 .I field
222 may be preceded by
223 .B %-
224 to turn off padding or
225 .B %_
226 to pad with space, otherwise numeric fields
227 are padded with
228 .B 0
229 and string fields are padded with space.
230 .I field
231 may also be preceded by
232 .B E
233 for alternate era representation or
234 .B O
235 for alternate digit representation (if supported by the current locale.)
236 Finally, an integral
237 .I width
238 preceding
239 .I field
240 truncates the field to
241 .I width
242 characters.
243 sequences are interpreted as in the C language.
244 String field values are taken from the
245 .L tm_info.format
246 string table.
247 The
248 .I fields
249 are:
250 .TP
251 .PD 0
252 .B %
253 .B %
254 character.
255 .TP
256 .B a
257 Abbreviated weekday name.
258 .TP
259 .B A
260 Full weekday name.
261 .TP
262 .B b
263 Abbreviated month name.
264 .TP
265 .B c
266 .BR ctime (3)
267 style date without the trailing
268 .BR newline .
269 .TP
270 .B C
271 .BR date (1)
272 style date.
273 .TP
274 .B d
275 Day of month number.
276 .TP
277 .B D
278 Date as
279 .IR mm / dd / yy .
280 .TP
281 .B e
282 Blank padded day of month number.
283 .TP
284 .B E
285 Unpadded day of month number.
286 .TP
287 .B f
288 Locale default override date format.
289 .TP
290 .B F
291 Locale default date format
292 .RL ( tm_info.format[40] .)
293 .TP
294 .B h
295 Abbreviated month name.
296 .TP
297 .B H
298 24-hour clock hour.
299 .TP
300 .B i
301 International
302 .BR date (1)
303 date that includes the time zone type name
304 .RL ( tm_info.format[107] .)
305 .TP
306 .B I
307 12-hour clock hour.
308 .TP
309 .B j
310 1-offset Julian date.
311 .TP
312 .B J
313 0-offset Julian date.
314 .TP
315 .B k
316 .BR date (1)
317 style date
318 .RL ( tm_info.format[106] .)
319 .TP
320 .B K
321 Language neutral, all numeric, no embedded space date
322 with larger to smaller time units from left to right,
323 suitable for sorting:
324 .LR '"%Y-%m-%d+%H:%M:%S"' .
325 .TP
326 .B l
327 .BR ls (1)
328 .B \-l
329 date that lists recent dates with
330 .L %g
331 and distant dates with
332 .BR %G .
333 .TP
334 .B m
335 Month number.
336 .TP
337 .B M
338 Minutes.
339 .TP
340 .B n
341 .B newline
342 character.
343 .TP
344 .B N
345 The time zone type or nation code.
346 .TP
347 .B p
348 Meridian (e.g.,
349 .B AM
350 or
351 .BR PM .)
352 .TP
353 .B q
354 The nanosecond part of the time.
355 .TP
356 \fB%Q\fP\fI<delim>recent<delim>distant<delim>\fP
357 Recent dates are formatted with
358 .I recent
359 and distand dates are formatted with
360 .IR distant ,
361 where
362 .I <delim>
363 is any character not appearing in
364 .I recent
365 or
366 .IR distant .
367 .TP
368 .B r
369 12-hour time as
370 .IR hh : mm : ss
371 .IR meridian .
372 .TP
373 .B R
374 24-hour time as
375 .IR hh : mm .
376 .TP
377 .B s
378 Seconds since the epoch.
379 .RI . prec
380 preceding
381 .B s
382 appends
383 .I prec
384 nanosecond digits,
385 .B 9
386 if
387 .I prec
388 is omitted.
389 .TP
390 .B S
391 .I seconds.subseconds
392 since the epoch.
393 .TP
394 .B t
395 .B tab
396 character.
397 .TP
398 .B T
399 24-hour time as
400 .IR hh : mm : ss .
401 .TP
402 .B u
403 Weeday number with 1 for Monday, 7 for Sunday.
404 .TP
405 .B U
406 Week number with Sunday as the first day.
407 .TP
408 .B V
409 ISO week number (i18n is \fIfun\fP.)
410 .TP
411 .B w
412 Weekday number with 0 for Sunday, 6 for Saturday.
413 .TP
414 .B W
415 Week number with Monday as the first day.
416 .TP
417 .B x
418 Local date style, using
419 .LR tm_info.format[39] ,
420 that includes the month, day and year.
421 .TP
422 .B X
423 Local time style, using
424 .LR tm_info.format[38] ,
425 that includes the hours and minutes.
426 .TP
427 .B y
428 2-digit year (you'll be sorry.)
429 .TP
430 .B Y
431 4-digit year.
432 .TP
433 .B z
434 Time zone
435 .I SHHMM
436 west of GMT offset where
437 .I S
438 is
439 .B +
440 or
441 .BR - .
442 .TP
443 .B Z
444 Time zone name.
445 .TP
446 =[=]][-+]]\fIflag\fP
447 Set (default or +) or clear (-)
448 .I flag
449 in
450 .L tm_info.flags
451 for the remainder of
452 .IR format ,
453 or for the remainder of the process if
454 .B ==
455 is specified.
456 .I flag
457 may be:
458 .RS
459 .TP
460 .B l
461 .L (TM_LEAP)
462 Enable leap second adjustments.
463 .TP
464 .B s
465 .L (TM_SUBSECOND)
466 Append nanosecond
467 .B .%N
468 to
469 .BR %S .
470 .TP
471 .B u
472 .L (TM_UTC)
473 UTC time zone.
474 .RE
475 .TP
476 .B #
477 Equivalent to
478 .BR %s .
479 .TP
480 \fP?\fP\fIalternate\fP
481 Use
482 .I alternate
483 format is a default format override has not been specified.
484 e.g.,
485 .BR ls (1)
486 uses
487 .BR %?%l .
488 Export
489 \f5TM_OPTIONS="format='\fP\fIoverride\fP\f5'"\fP
490 to override the default.
491 .PD
492 .RE
493 .TP
494 .L "void tminit(Tm_zone_t* zone)"
495 Implicitly called by the other
496 .I tm
497 library routines to initialize global data, including the
498 .L tm_info.format
499 table and the
500 .L tm_info.flags
501 global flags.
502 Global data should only be modified after an explicit call to
503 .LR tminit .
504 If
505 .L "zone != 0"
506 then it specifies a time zone other that the local time zone.
507 .TP
508 .L "void tmset(Tm_zone_t* zone);"
509 .L tmset
510 sets the reference timezoe to
511 .LR zone .
512 .L tm_info.local
513 points to the local timezone and
514 .L tm_info.zone
515 points to the current reference timezone.
516 .TP
517 .L "time_t tmleap(time_t* clock)"
518 Returns a
519 .L time_t
520 value for the time pointed to by
521 .L clock
522 with leap seconds adjusted for external
523 routines that do not handle leap seconds.
524 If
525 .L clock
526 is
527 .L NULL
528 then the current time is used.
529 Adjustments are only done if the
530 .L TM_ADJUST
531 flag is set in
532 .LR tm_info.flags .
533 .TP
534 .L "Tm_t* tmmake(time_t* clock)"
535 Returns a pointer to the
536 .L Tm_t
537 struct corresponding to the time pointed to by
538 .LR clock .
539 If
540 .L clock
541 is
542 .L NULL
543 then the current time is used.
544 .TP
545 .L "time_t tmtime(Tm_t* tp, int west)"
546 Returns the
547 .L time_t
548 value corresponding to
549 .LR tp .
550 If
551 .L west
552 is
553 .L TM_LOCALZONE
554 then
555 .L tm
556 is relative to the local time zone,
557 otherwise
558 .L west
559 is the number of minutes west of
560 .B UTC
561 with daylight savings time taken into account.
562 .LR tp->tm_wday ,
563 .LR tp->tm_yday
564 and
565 .L tp->tm_isdst
566 are ignored in the conversion.
567 .PP
568 The library routines use a table of date strings pointed to by
569 .LR "char** tm_info.format" .
570 The indices in
571 .L tm_info.format
572 are fixed by category.
573 .L tm_info.format
574 may be changed to point to other tables
575 according to local language and date conventions.
576 The contents by index (showing the USA English values) are:
577 .RS
578 .TP
579 .PD 0
580 .B 0-11
581 3-character abbreviated month names.
582 .TP
583 .B 12-23
584 Full month names.
585 .TP
586 .B 24-30
587 3-character abbreviated weekday names.
588 .TP
589 .B 31-37
590 Full weekday names.
591 .TP
592 .B 38
593 .L tmfmt()
594 local time format used by the
595 .B %X
596 field.
597 .TP
598 .B 39
599 .L tmfmt()
600 local date format used by the
601 .B %x
602 field.
603 .TP
604 .B 40
605 .L tmfmt()
606 format used if the
607 .L format
608 argument is
609 .L NULL
610 or empty.
611 .TP
612 .B 41-42
613 Meridian names: AM, PM.
614 .TP
615 .B 43-46
616 .B UTC
617 time zone names: GMT, UTC, UCT, CUT.
618 .TP
619 .B 47-50
620 Daylight savings time suffix names: DST.
621 .TP
622 .B 51-54
623 Suffixes to be ignored when matching strings in
624 .LR tmfmt() .
625 .TP
626 .B 55-61
627 Time part names: second, hour, minute, day, week, month, year.
628 .TP
629 .B 62-65
630 Hours of the day names: midnight, morning, noon, evening.
631 .TP
632 .B 66-68
633 Relative day names: yesterday, today, tomorrow.
634 .TP
635 .B 69-71
636 Past relative time references: last, ago, past.
637 .TP
638 .B 72-75
639 Current relative time references: this, now, current.
640 .TP
641 .B 75-77
642 Future relative time references: next, hence, coming.
643 .TP
644 .B 78-80
645 Exact relative time references: exactly.
646 .TP
647 .B 81-84
648 Noise words to be ignored: at, in, on.
649 .TP
650 .B 85-94
651 Ordinal suffixes: st, nd, rd, th, th, th, th, th, th, th.
652 .TP
653 .B 95-104
654 Digit names.
655 .TP
656 .B 105
657 The
658 .L tmfmt()
659 format equivalent for
660 .BR ctime (3):
661 .LR '"%a %b %e %T %Y"' .
662 .TP
663 .B 106
664 The
665 .L tmfmt()
666 .BR date (1)
667 default format:
668 .LR '"%a %b %e %T %Z %Y"' .
669 .TP
670 .B 107
671 The
672 .L tmfmt()
673 .BR date (1)
674 international format:
675 .LR '"%a %b %e %T %z %Z %Y"' .
676 .TP
677 .B 108
678 The
679 .L tmfmt()
680 .BR ls (1)
681 recent date format:
682 .LR '"%b %e %H:%M"' .
683 .TP
684 .B 109
685 The
686 .L tmfmt()
687 .BR ls (1)
688 distant date format:
689 .LR '"%b %e %Y"' .
690 .TP
691 .B 110
692 The
693 .L tmfmt()
694 .BR date (1)
695 meridian date format:
696 .LR '"%I:%M:%S %p"' .
697 .TP
698 .B 111
699 The ERA name.
700 .TP
701 .B 112
702 ERA alternative for
703 .BR 39 .
704 .TP
705 .B 113
706 ERA alternative for
707 .BR 38 .
708 .TP
709 .B 114
710 ERA alternative for
711 .BR 40 .
712 .TP
713 .B 115
714 The ERA year.
715 .TP
716 .B 116-125
717 Ordinal names: first, \fIno second!\fP, third, fourth, fifth, sixth, seventh, eighth, ninth, tenth.
718 .TP
719 .B 126-128
720 Final time references, as in \fIthe last in the list\fP: final, ending, nth.
721 .PD
722 .RE
723 .PP
724 Low level support functions and data are described in
725 .LR <tm.h> .
726 .SH EXAMPLES
727 .EX
728 #include <tm.h>
729 main() {
730 int i;
731 time_t t;
732 char buf[128];
733 struct {
734 char* date;
735 char* format;
736 } x[] = {
737 "now", "%i",
738 "2 months ago", "%C",
739 "this Wednesday noon", "%x %I:%M %p",
740 "last December 25", "%A",
741 0, 0
742 };
743 for (i = 0; x[i].date; i++) {
744 t = tmdate(x[i].date, (char*)0, (time_t*)0);
745 (void)tmfmt(buf, sizeof(buf), x[i].format, &t);
746 puts(buf);
747 }
748 }
749 .EE
750 produces
751 .EX
752 Fri Sep 30 12:10:14 USA EDT 1988
753 Fri Jul 1 00:00:00 EDT 1988
754 10/05/88 12:00 PM
755 Friday
756 .EE
757 .SH "SEE ALSO"
758 .BR date (1),
759 .BR time (2),
760 .BR ctime (3)
761 .SH BUGS
762 The C library static
763 .L "struct tm"
764 values may get clobbered by
765 .I tm
766 library routines as the
767 .BR ctime (3)
768 and
769 .BR localtime (3)
770 routines typically return pointers to a single static
771 .L "struct tm"
772 area.
773 .L tmdate()
774 uses an internal international time zone name table that will
775 probably always be incomplete.