Return to tm.3 CVS log

Up to [Research Unix] / researchv10dc / cmd / odist / pax / man / man3

Annotation of researchv10dc/cmd/odist/pax/man/man3/tm.3, revision 1.1

1.1     ! root        1: .de L          \" literal font
        !             2: .ft 5
        !             3: .it 1 }N
        !             4: .if !\\$1 \&\\$1 \\$2 \\$3 \\$4 \\$5 \\$6
        !             5: ..
        !             6: .de LR
        !             7: .}S 5 1 \& "\\$1" "\\$2" "\\$3" "\\$4" "\\$5" "\\$6"
        !             8: ..
        !             9: .de RL
        !            10: .}S 1 5 \& "\\$1" "\\$2" "\\$3" "\\$4" "\\$5" "\\$6"
        !            11: ..
        !            12: .de EX         \" start example
        !            13: .ta 1i 2i 3i 4i 5i 6i
        !            14: .PP
        !            15: .RS 
        !            16: .PD 0
        !            17: .ft 5
        !            18: .nf
        !            19: ..
        !            20: .de EE         \" end example
        !            21: .fi
        !            22: .ft
        !            23: .PD
        !            24: .RE
        !            25: .PP
        !            26: ..
        !            27: .TH TM 3
        !            28: .SH NAME
        !            29: tm \- time conversion support
        !            30: .SH SYNOPSIS
        !            31: .L "#include <tm.h>"
        !            32: .SH DESCRIPTION
        !            33: The
        !            34: .I tm
        !            35: library supports conversion between
        !            36: string date specifications,
        !            37: .L time_t
        !            38: clock values and
        !            39: .L "struct tm"
        !            40: values.
        !            41: .L localtime()
        !            42: and
        !            43: .L gmtime()
        !            44: (see
        !            45: .IR ctime (3))
        !            46: are used to determine local time zone information.
        !            47: .PP
        !            48: .L time_t
        !            49: values are the number of seconds since the epoch,
        !            50: .BR "Jan 1 00:00:00 GMT 1970" ,
        !            51: with leap seconds omitted.
        !            52: .PP
        !            53: The global variable
        !            54: .L "int tm_info.flags"
        !            55: contains flags that allow all programs using the library
        !            56: to be controlled in a consistent manner.
        !            57: .L tm_info.flags
        !            58: is initialized by the
        !            59: .L tminit()
        !            60: routine described below, and may be explicitly reset after
        !            61: .L tminit()
        !            62: is called.
        !            63: The flags are:
        !            64: .TP
        !            65: .L TM_ADJUST
        !            66: Set by
        !            67: .L tminit()
        !            68: if
        !            69: .L localtime()
        !            70: and
        !            71: .L gmtime()
        !            72: do not compensate for leap seconds.
        !            73: .TP
        !            74: .L TM_LEAP
        !            75: .L time_t
        !            76: values are interpreted as if they include leap seconds.
        !            77: Set by
        !            78: .L tminit()
        !            79: if the
        !            80: .L leap
        !            81: option is set in the
        !            82: .L TM_OPTIONS
        !            83: environment variable.
        !            84: .TP
        !            85: .L TM_UTC
        !            86: Times are relative to
        !            87: .B UTC
        !            88: (universal coordinated time, i.e.,
        !            89: .BR GMT ).
        !            90: Otherwise times are relative to the local time zone.
        !            91: Set by
        !            92: .L tminit()
        !            93: if the time zone name matches one of
        !            94: .L tm_info.format[43]
        !            95: through
        !            96: .L tm_info.format[46]
        !            97: described below.
        !            98: If the time zone name is not determined by
        !            99: .L localtime()
        !           100: then the environment variables
        !           101: .L TZNAME
        !           102: (as described in BSD 4.3) and
        !           103: .L TZ
        !           104: (as described in System V)
        !           105: are checked, in order.
        !           106: If this fails then the time zone name is constructed using
        !           107: the local time zone offset.
        !           108: .PP
        !           109: The routines are:
        !           110: .TP
        !           111: .L "time_t tmdate(char* date, char** end, time_t* clock)"
        !           112: Parses the date specification
        !           113: .L date
        !           114: using the
        !           115: .L tm_info.format
        !           116: string table (described below)
        !           117: and returns the equivalent
        !           118: .L time_t
        !           119: value.
        !           120: If
        !           121: .RL non- NULL ,
        !           122: .L end
        !           123: is set to the position of the first unrecognized character in
        !           124: .LR date .
        !           125: .L clock
        !           126: is used to provide default values for omitted components in
        !           127: .LR date .
        !           128: If
        !           129: .L clock
        !           130: is
        !           131: .L NULL
        !           132: then the current time is used.
        !           133: .TP
        !           134: .L "struct tm* tmfix(struct tm* tp)"
        !           135: Corrects any out of bounds fields in
        !           136: .L tp
        !           137: and returns
        !           138: .L tp
        !           139: as its value.
        !           140: The corrections start with
        !           141: .L tp->tm_sec
        !           142: and propagate down to
        !           143: .LR tp->tm_year .
        !           144: For example, if
        !           145: .L tp->tm_sec
        !           146: were 61 then it would change to 1 and
        !           147: .L tp->tm_min
        !           148: would be incremented by 1, and so on.
        !           149: .LR tp->tm_wday ,
        !           150: .LR tp->tm_yday
        !           151: and
        !           152: .L tp->tm_isdst
        !           153: are not changed as these can be computed from the other fields.
        !           154: .TP
        !           155: .L "char* tmform(char* buf, char* format, time_t* clock)"
        !           156: Formats the date pointed to by
        !           157: .L clock
        !           158: into the buffer
        !           159: .L buf
        !           160: according to the format specification
        !           161: .LR format .
        !           162: If
        !           163: .L format
        !           164: is
        !           165: .L NULL
        !           166: or empty then the string
        !           167: .L tm_info.format[40]
        !           168: is used.
        !           169: If
        !           170: .L clock
        !           171: is
        !           172: .L NULL
        !           173: then the current time is used.
        !           174: A pointer to the end of
        !           175: .L buf
        !           176: (i.e., the terminating
        !           177: .LR "'\e0'" )
        !           178: is returned.
        !           179: .RS
        !           180: .PP
        !           181: .L format
        !           182: is in the style of
        !           183: .IR printf (3),
        !           184: where
        !           185: .BI % field
        !           186: causes the corresponding fixed size field to be placed in
        !           187: .LR buf ,
        !           188: zero padded if necessary, and \e\fIc\fP and \e\fInnn\fP
        !           189: sequences are interpreted as in the C language.
        !           190: Otherwise invalid
        !           191: .BI % field
        !           192: specifications and all other characters in
        !           193: .L format
        !           194: are copied into
        !           195: .L buf
        !           196: without change.
        !           197: String field values are taken from the
        !           198: .L tm_info.format
        !           199: string table.
        !           200: The
        !           201: .I fields
        !           202: are:
        !           203: .TP
        !           204: .PD 0
        !           205: .B %
        !           206: .B %
        !           207: character.
        !           208: .TP
        !           209: .B a
        !           210: Abbreviated weekday name.
        !           211: .TP
        !           212: .B A
        !           213: Full weekday name.
        !           214: .TP
        !           215: .B b
        !           216: Abbreviated month name.
        !           217: .TP
        !           218: .B c
        !           219: .IR ctime (3)
        !           220: style date without the trailing
        !           221: .BR newline .
        !           222: .TP
        !           223: .B C
        !           224: .IR date (1)
        !           225: style date.
        !           226: .TP
        !           227: .B d
        !           228: Day of month number.
        !           229: .TP
        !           230: .B D
        !           231: Date as
        !           232: .IR mm / dd / yy .
        !           233: .TP
        !           234: .B e
        !           235: Blank padded day of month number.
        !           236: .TP
        !           237: .B E
        !           238: Unpadded day of month number.
        !           239: .TP
        !           240: .B h
        !           241: Abbreviated month name.
        !           242: .TP
        !           243: .B H
        !           244: 24-hour clock hour.
        !           245: .TP
        !           246: .B i
        !           247: International
        !           248: .IR date (1)
        !           249: date that includes the time zone type name.
        !           250: .TP
        !           251: .B I
        !           252: 12-hour clock hour.
        !           253: .TP
        !           254: .B j
        !           255: 1-offset Julian date.
        !           256: .TP
        !           257: .B J
        !           258: 0-offset Julian date.
        !           259: .TP
        !           260: .B l
        !           261: .IR ls (1)
        !           262: .B \-l
        !           263: date that lists recent dates with
        !           264: .IR hh : mm
        !           265: and distant dates with
        !           266: .IR yyyy .
        !           267: .TP
        !           268: .B m
        !           269: Month number.
        !           270: .TP
        !           271: .B M
        !           272: Minutes.
        !           273: .TP
        !           274: .B n
        !           275: .B newline
        !           276: character.
        !           277: .TP
        !           278: .B p
        !           279: Meridian (e.g.,
        !           280: .B AM
        !           281: or
        !           282: .BR PM ).
        !           283: .TP
        !           284: .B r
        !           285: 12-hour time as
        !           286: .IR hh : mm : ss
        !           287: .IR meridian .
        !           288: .TP
        !           289: .B R
        !           290: 24-hour time as
        !           291: .IR hh : mm .
        !           292: .TP
        !           293: .B S
        !           294: Seconds.
        !           295: .TP
        !           296: .B t
        !           297: .B tab
        !           298: character.
        !           299: .TP
        !           300: .B T
        !           301: 24-hour time as
        !           302: .IR hh : mm : ss .
        !           303: .TP
        !           304: .B U
        !           305: Week number with Sunday as the first day.
        !           306: .TP
        !           307: .B w
        !           308: Weekday number.
        !           309: .TP
        !           310: .B W
        !           311: Week number with Monday as the first day.
        !           312: .TP
        !           313: .B x
        !           314: Local date style, using
        !           315: .LR tm_info.format[39] ,
        !           316: that includes the month, day and year.
        !           317: .TP
        !           318: .B X
        !           319: Local time style, using
        !           320: .LR tm_info.format[38] ,
        !           321: that includes the hours and minutes.
        !           322: .TP
        !           323: .B y
        !           324: 2-digit year.
        !           325: .TP
        !           326: .B Y
        !           327: 4-digit year.
        !           328: .TP
        !           329: .B z
        !           330: Time zone type name.
        !           331: .TP
        !           332: .B Z
        !           333: Time zone name.
        !           334: .TP
        !           335: .BI + flag
        !           336: .TP
        !           337: .BI \- flag
        !           338: Temporarily (until
        !           339: .L tmform()
        !           340: returns) sets (+) or clears (\-) the
        !           341: .L tm_info.flags
        !           342: flags specified by
        !           343: .IR flag :
        !           344: .RS
        !           345: .TP
        !           346: .B l
        !           347: .L TM_LEAP
        !           348: .TP
        !           349: .B u
        !           350: .L TM_UTC
        !           351: .RE
        !           352: .TP
        !           353: .B #
        !           354: Number of seconds since the epoch.
        !           355: .PD
        !           356: .RE
        !           357: .TP
        !           358: .L "void tminit()"
        !           359: Implicitly called by the other
        !           360: .I tm
        !           361: library routines to initialize global data, including the
        !           362: .L tm_info.format
        !           363: table and the
        !           364: .L tm_info.flags
        !           365: global flags.
        !           366: Global data should only be modified after an explicit call to
        !           367: .LR tminit() .
        !           368: .TP
        !           369: .L "time_t tmleap(time_t* clock)"
        !           370: Returns a
        !           371: .L time_t
        !           372: value for the time pointed to by
        !           373: .L clock
        !           374: with leap seconds adjusted for external
        !           375: routines that do not handle leap seconds.
        !           376: If
        !           377: .L clock
        !           378: is
        !           379: .L NULL
        !           380: then the current time is used.
        !           381: Adjustments are only done if the
        !           382: .L TM_ADJUST
        !           383: flag is set in
        !           384: .LR tm_info.flags .
        !           385: .TP
        !           386: .L "struct tm* tmmake(time_t* clock)"
        !           387: Returns a pointer to the
        !           388: .L tm
        !           389: struct corresponding to the time pointed to by
        !           390: .LR clock .
        !           391: If
        !           392: .L clock
        !           393: is
        !           394: .L NULL
        !           395: then the current time is used.
        !           396: .TP
        !           397: .L "time_t tmtime(struct tm* tp, int west)"
        !           398: Returns the
        !           399: .L time_t
        !           400: value corresponding to
        !           401: .LR tp .
        !           402: If
        !           403: .L west
        !           404: is
        !           405: .L TM_LOCALZONE
        !           406: then
        !           407: .L tm
        !           408: is relative to the local time zone,
        !           409: otherwise
        !           410: .L west
        !           411: is the number of minutes west of
        !           412: .B UTC
        !           413: with daylight savings time taken into account.
        !           414: .LR tp->tm_wday ,
        !           415: .LR tp->tm_yday
        !           416: and
        !           417: .L tp->tm_isdst
        !           418: are ignored in the conversion.
        !           419: .PP
        !           420: The library routines use a table of date strings pointed to by
        !           421: .LR "char** tm_info.format" .
        !           422: The indices in
        !           423: .L tm_info.format
        !           424: are fixed by category.
        !           425: .L tm_info.format
        !           426: may be changed to point to other tables
        !           427: according to local language and date conventions.
        !           428: The contents by index (showing the USA English values) are:
        !           429: .RS
        !           430: .TP
        !           431: .PD 0
        !           432: .B 0-11
        !           433: 3-character abbreviated month names.
        !           434: .TP
        !           435: .B 12-23
        !           436: Full month names.
        !           437: .TP
        !           438: .B 24-30
        !           439: 3-character abbreviated weekday names.
        !           440: .TP
        !           441: .B 31-37
        !           442: Full weekday names.
        !           443: .TP
        !           444: .B 38
        !           445: .L tmform()
        !           446: local time format used by the
        !           447: .B %X
        !           448: field.
        !           449: .TP
        !           450: .B 39
        !           451: .L tmform()
        !           452: local date format used by the
        !           453: .B %x
        !           454: field.
        !           455: .TP
        !           456: .B 40
        !           457: .L tmform()
        !           458: format used if the
        !           459: .L format
        !           460: argument is
        !           461: .L NULL
        !           462: or empty.
        !           463: .TP
        !           464: .B 41-42
        !           465: Meridian names: AM, PM.
        !           466: .TP
        !           467: .B 43-46
        !           468: .B UTC
        !           469: time zone names: GMT, UTC, UCT, CUT.
        !           470: .TP
        !           471: .B 47-50
        !           472: Daylight savings time suffix names: DST.
        !           473: .TP
        !           474: .B 51-54
        !           475: Suffixes to be ignored when matching strings in
        !           476: .LR tmform() .
        !           477: .TP
        !           478: .B 55-61
        !           479: Time part names: second, hour, minute, day, week, month, year.
        !           480: .TP
        !           481: .B 62-65
        !           482: Hours of the day names: midnight, morning, noon, evening.
        !           483: .TP
        !           484: .B 66-68
        !           485: Relative day names: yesterday, today, tomorrow.
        !           486: .TP
        !           487: .B 69-71
        !           488: Past relative time references: last, ago, past.
        !           489: .TP
        !           490: .B 72-75
        !           491: Current relative time references: this, now, current.
        !           492: .TP
        !           493: .B 75-77
        !           494: Future relative time references: next, hence, coming.
        !           495: .TP
        !           496: .B 78-80
        !           497: Exact relative time references: exactly.
        !           498: .TP
        !           499: .B 81-85
        !           500: Noise words to be ignored: at, in, on.
        !           501: .PD
        !           502: .RE
        !           503: .PP
        !           504: Low level support functions and data are described in
        !           505: .LR <tm.h> .
        !           506: .SH EXAMPLES
        !           507: .EX
        !           508: #include <tm.h>
        !           509: main() {
        !           510:     int       i;
        !           511:     time_t    t;
        !           512:     char      buf[128];
        !           513:     struct {
        !           514:         char* date;
        !           515:         char* format;
        !           516:     }         x[] = {
        !           517:         "now",                 "%i",
        !           518:         "2 months ago",        "%C",
        !           519:         "this Wednesday noon", "%x %I:%M %p",
        !           520:         "last December 25",    "%A",
        !           521:         0,                     0
        !           522:     };
        !           523:     for (i = 0; x[i].date; i++) {
        !           524:         t = tmdate(x[i].date, (char*)0, (time_t*)0);
        !           525:         (void)tmform(buf, x[i].format, &t);
        !           526:         puts(buf);
        !           527:     }
        !           528: }
        !           529: .EE
        !           530: produces
        !           531: .EX
        !           532: Fri Sep 30 12:10:14 USA EDT 1988
        !           533: Fri Jul  1 00:00:00 EDT 1988
        !           534: 10/05/88 12:00 PM
        !           535: Friday
        !           536: .EE
        !           537: .SH "SEE ALSO"
        !           538: date(1), time(2), ctime(3)
        !           539: .SH BUGS
        !           540: .L "struct tm"
        !           541: values may get clobbered by the
        !           542: .I tm
        !           543: library routines as the
        !           544: .IR ctime (3)
        !           545: routines typically return pointers to a single static
        !           546: .L "struct tm"
        !           547: area.
        !           548: .L tmdate()
        !           549: uses an internal international time zone name table that will
        !           550: probably always be incomplete.

This archive runs on limited infrastructure. Preserving old code on modern bandwidth. Automated agents are requested to crawl responsibly.