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