Imported Upstream version 93u+upstream

1 files changed, 775 insertions, 0 deletions

diff --git a/src/lib/libast/man/tm.3 b/src/lib/libast/man/tm.3
new file mode 100644
index 0000000..12eb4ec
--- /dev/null
+++ b/src/lib/libast/man/tm.3
@@ -0,0 +1,775 @@
+.fp 5 CW
+.de Af
+.ds ;G \\*(;G\\f\\$1\\$3\\f\\$2
+.if !\\$4 .Af \\$2 \\$1 "\\$4" "\\$5" "\\$6" "\\$7" "\\$8" "\\$9"
+..
+.de aF
+.ie \\$3 .ft \\$1
+.el \{\
+.ds ;G \&
+.nr ;G \\n(.f
+.Af "\\$1" "\\$2" "\\$3" "\\$4" "\\$5" "\\$6" "\\$7" "\\$8" "\\$9"
+\\*(;G
+.ft \\n(;G \}
+..
+.de L
+.aF 5 \\n(.f "\\$1" "\\$2" "\\$3" "\\$4" "\\$5" "\\$6" "\\$7"
+..
+.de LR
+.aF 5 1 "\\$1" "\\$2" "\\$3" "\\$4" "\\$5" "\\$6" "\\$7"
+..
+.de RL
+.aF 1 5 "\\$1" "\\$2" "\\$3" "\\$4" "\\$5" "\\$6" "\\$7"
+..
+.de EX		\" start example
+.ta 1i 2i 3i 4i 5i 6i
+.PP
+.RS 
+.PD 0
+.ft 5
+.nf
+..
+.de EE		\" end example
+.fi
+.ft
+.PD
+.RE
+.PP
+..
+.TH TM 3
+.SH NAME
+tm \- seconds resolution time conversion support
+.SH SYNOPSIS
+.L "#include <tm.h>"
+.SH DESCRIPTION
+The
+.I tm
+library supports conversion between
+string date specifications,
+seconds reolution
+.L time_t
+clock values and
+.LR Tm_t .
+.L Tm_t
+contains the elements of
+.L "struct tm"
+along with these additions:
+.TP
+.L "unsigned _ast_int4_t tm_nsec"
+The subsecond portion of the time in nanoseconds.
+.TP
+.L "Tm_zone_t* tm_zone"
+The time zone name.
+.PP
+.L localtime()
+and
+.L gmtime()
+(see
+.BR ctime (3))
+are used to determine local time zone and savings time information.
+.PP
+.L time_t
+values are the number of seconds since the epoch,
+.BR "Jan 1 00:00:00 GMT 1970" ,
+with leap seconds omitted.
+.PP
+The global variable
+.L "int tm_info.flags"
+contains flags that allow all programs using the library
+to be controlled in a consistent manner.
+.L tm_info.flags
+is initialized by the
+.L tminit()
+routine described below, and may be explicitly reset after
+.L tminit()
+is called.
+The flags are:
+.TP
+.L TM_ADJUST
+Set by
+.L tminit()
+if
+.L localtime()
+and
+.L gmtime()
+do not compensate for leap seconds.
+.TP
+.L TM_LEAP
+.L time_t
+values are interpreted as if they include leap seconds.
+Set by
+.L tminit()
+if the
+.L leap
+option is set in the
+.L TM_OPTIONS
+environment variable.
+.TP
+.L TM_UTC
+Times are relative to
+.B UTC
+(universal coordinated time, i.e.,
+.BR GMT .)
+Otherwise times are relative to the local time zone.
+Set by
+.L tminit()
+if the time zone name matches one of
+.L tm_info.format[43]
+through
+.L tm_info.format[46]
+described below.
+If the time zone name is not determined by
+.L localtime()
+then the environment variables
+.L TZNAME
+(as described in BSD 4.3) and
+.L TZ
+(as described in System V)
+are checked, in order.
+If this fails then the time zone name is constructed using
+the local time zone offset.
+.PP
+The routines are:
+.TP
+.L "time_t tmdate(const char* date, char** end, time_t* clock)"
+Parses the date specification
+.L date
+using the
+.L tm_info.format
+string table (described below)
+and returns the equivalent
+.L time_t
+value.
+If
+.RL non- NULL ,
+.L end
+is set to the position of the first unrecognized character in
+.LR date .
+.L clock
+is used to provide default values for omitted components in
+.LR date .
+If
+.L clock
+is
+.L NULL
+then the current time is used.
+.TP
+.L "Tm_t* tmfix(Tm_t* tp)"
+Corrects any out of bounds fields in
+.L tp
+and returns
+.L tp
+as its value.
+The corrections start with
+.L tp->tm_sec
+and propagate down to
+.LR tp->tm_year .
+For example, if
+.L tp->tm_sec
+were 61 then it would change to 1 and
+.L tp->tm_min
+would be incremented by 1, and so on.
+.L tp->tm_isdst
+is not changed -- call
+.L tmtime()
+to determine its proper value after the
+.L tmfix()
+adjustments.
+.TP
+.L "char* tmfmt(char* buf, size_t len, const char* format, time_t* clock)"
+Formats the date pointed to by
+.L clock
+into the buffer
+.L buf
+with size
+.L len
+bytes according to the format specification
+.LR format .
+If
+.L format
+is
+.L NULL
+or empty then the string
+.L tm_info.format[40]
+is used.
+If
+.L clock
+is
+.L NULL
+then the current time is used.
+A pointer to the end of
+.L buf
+(i.e., the terminating
+.LR "'\e0'" )
+is returned.
+.RS
+.PP
+.L format
+is in
+.BR printf (3)
+style, where
+.RI % field
+names a fixed size field, zero padded if necessary,
+and
+.I \ec
+and
+.I \ennn
+sequences are as in C. Invalid
+.RI % field
+specifications and all other characters are copied
+without change.
+.I field
+may be preceded by
+.B %-
+to turn off padding or
+.B %_
+to pad with space, otherwise numeric fields
+are padded with
+.B 0
+and string fields are padded with space.
+.I field
+may also be preceded by
+.B E
+for alternate era representation or
+.B O
+for alternate digit representation (if supported by the current locale.)
+Finally, an integral
+.I width
+preceding
+.I field
+truncates the field to
+.I width
+characters.
+sequences are interpreted as in the C language.
+String field values are taken from the
+.L tm_info.format
+string table.
+The
+.I fields
+are:
+.TP
+.PD 0
+.B %
+.B %
+character.
+.TP
+.B a
+Abbreviated weekday name.
+.TP
+.B A
+Full weekday name.
+.TP
+.B b
+Abbreviated month name.
+.TP
+.B c
+.BR ctime (3)
+style date without the trailing
+.BR newline .
+.TP
+.B C
+.BR date (1)
+style date.
+.TP
+.B d
+Day of month number.
+.TP
+.B D
+Date as
+.IR mm / dd / yy .
+.TP
+.B e
+Blank padded day of month number.
+.TP
+.B E
+Unpadded day of month number.
+.TP
+.B f
+Locale default override date format.
+.TP
+.B F
+Locale default date format
+.RL ( tm_info.format[40] .)
+.TP
+.B h
+Abbreviated month name.
+.TP
+.B H
+24-hour clock hour.
+.TP
+.B i
+International
+.BR date (1)
+date that includes the time zone type name
+.RL ( tm_info.format[107] .)
+.TP
+.B I
+12-hour clock hour.
+.TP
+.B j
+1-offset Julian date.
+.TP
+.B J
+0-offset Julian date.
+.TP
+.B k
+.BR date (1)
+style date
+.RL ( tm_info.format[106] .)
+.TP
+.B K
+Language neutral, all numeric, no embedded space date
+with larger to smaller time units from left to right,
+suitable for sorting:
+.LR '"%Y-%m-%d+%H:%M:%S"' .
+.TP
+.B l
+.BR ls (1)
+.B \-l
+date that lists recent dates with
+.L %g
+and distant dates with
+.BR %G .
+.TP
+.B m
+Month number.
+.TP
+.B M
+Minutes.
+.TP
+.B n
+.B newline
+character.
+.TP
+.B N
+The time zone type or nation code.
+.TP
+.B p
+Meridian (e.g.,
+.B AM
+or
+.BR PM .)
+.TP
+.B q
+The nanosecond part of the time.
+.TP
+\fB%Q\fP\fI<delim>recent<delim>distant<delim>\fP
+Recent dates are formatted with
+.I recent
+and distand dates are formatted with
+.IR distant ,
+where
+.I <delim>
+is any character not appearing in
+.I recent
+or
+.IR distant .
+.TP
+.B r
+12-hour time as
+.IR hh : mm : ss
+.IR meridian .
+.TP
+.B R
+24-hour time as
+.IR hh : mm .
+.TP
+.B s
+Seconds since the epoch.
+.RI . prec
+preceding
+.B s
+appends
+.I prec
+nanosecond digits,
+.B 9
+if
+.I prec
+is omitted.
+.TP
+.B S
+.I seconds.subseconds
+since the epoch.
+.TP
+.B t
+.B tab
+character.
+.TP
+.B T
+24-hour time as
+.IR hh : mm : ss .
+.TP
+.B u
+Weeday number with 1 for Monday, 7 for Sunday.
+.TP
+.B U
+Week number with Sunday as the first day.
+.TP
+.B V
+ISO week number (i18n is \fIfun\fP.)
+.TP
+.B w
+Weekday number with 0 for Sunday, 6 for Saturday.
+.TP
+.B W
+Week number with Monday as the first day.
+.TP
+.B x
+Local date style, using
+.LR tm_info.format[39] ,
+that includes the month, day and year.
+.TP
+.B X
+Local time style, using
+.LR tm_info.format[38] ,
+that includes the hours and minutes.
+.TP
+.B y
+2-digit year (you'll be sorry.)
+.TP
+.B Y
+4-digit year.
+.TP
+.B z
+Time zone
+.I SHHMM
+west of GMT offset where
+.I S
+is
+.B +
+or
+.BR - .
+.TP
+.B Z
+Time zone name.
+.TP
+=[=]][-+]]\fIflag\fP
+Set (default or +) or clear (-)
+.I flag
+in
+.L tm_info.flags
+for the remainder of
+.IR format ,
+or for the remainder of the process if
+.B ==
+is specified.
+.I flag
+may be:
+.RS
+.TP
+.B l
+.L (TM_LEAP)
+Enable leap second adjustments.
+.TP
+.B s
+.L (TM_SUBSECOND)
+Append nanosecond
+.B .%N
+to
+.BR %S .
+.TP
+.B u
+.L (TM_UTC)
+UTC time zone.
+.RE
+.TP
+.B #
+Equivalent to
+.BR %s .
+.TP
+\fP?\fP\fIalternate\fP
+Use
+.I alternate
+format is a default format override has not been specified.
+e.g.,
+.BR ls (1)
+uses
+.BR %?%l .
+Export
+\f5TM_OPTIONS="format='\fP\fIoverride\fP\f5'"\fP
+to override the default.
+.PD
+.RE
+.TP
+.L "void tminit(Tm_zone_t* zone)"
+Implicitly called by the other
+.I tm
+library routines to initialize global data, including the
+.L tm_info.format
+table and the
+.L tm_info.flags
+global flags.
+Global data should only be modified after an explicit call to
+.LR tminit .
+If
+.L "zone != 0"
+then it specifies a time zone other that the local time zone.
+.TP
+.L "void tmset(Tm_zone_t* zone);"
+.L tmset
+sets the reference timezoe to
+.LR zone .
+.L tm_info.local 
+points to the local timezone and
+.L tm_info.zone
+points to the current reference timezone.
+.TP
+.L "time_t tmleap(time_t* clock)"
+Returns a
+.L time_t
+value for the time pointed to by
+.L clock
+with leap seconds adjusted for external
+routines that do not handle leap seconds.
+If
+.L clock
+is
+.L NULL
+then the current time is used.
+Adjustments are only done if the
+.L TM_ADJUST
+flag is set in
+.LR tm_info.flags .
+.TP
+.L "Tm_t* tmmake(time_t* clock)"
+Returns a pointer to the
+.L Tm_t
+struct corresponding to the time pointed to by
+.LR clock .
+If
+.L clock
+is
+.L NULL
+then the current time is used.
+.TP
+.L "time_t tmtime(Tm_t* tp, int west)"
+Returns the
+.L time_t
+value corresponding to
+.LR tp .
+If
+.L west
+is
+.L TM_LOCALZONE
+then
+.L tm
+is relative to the local time zone,
+otherwise
+.L west
+is the number of minutes west of
+.B UTC
+with daylight savings time taken into account.
+.LR tp->tm_wday ,
+.LR tp->tm_yday
+and
+.L tp->tm_isdst
+are ignored in the conversion.
+.PP
+The library routines use a table of date strings pointed to by
+.LR "char** tm_info.format" .
+The indices in
+.L tm_info.format
+are fixed by category.
+.L tm_info.format
+may be changed to point to other tables
+according to local language and date conventions.
+The contents by index (showing the USA English values) are:
+.RS
+.TP
+.PD 0
+.B 0-11
+3-character abbreviated month names.
+.TP
+.B 12-23
+Full month names.
+.TP
+.B 24-30
+3-character abbreviated weekday names.
+.TP
+.B 31-37
+Full weekday names.
+.TP
+.B 38
+.L tmfmt()
+local time format used by the
+.B %X
+field.
+.TP
+.B 39
+.L tmfmt()
+local date format used by the
+.B %x
+field.
+.TP
+.B 40
+.L tmfmt()
+format used if the
+.L format
+argument is
+.L NULL
+or empty.
+.TP
+.B 41-42
+Meridian names: AM, PM.
+.TP
+.B 43-46
+.B UTC
+time zone names: GMT, UTC, UCT, CUT.
+.TP
+.B 47-50
+Daylight savings time suffix names: DST.
+.TP
+.B 51-54
+Suffixes to be ignored when matching strings in
+.LR tmfmt() .
+.TP
+.B 55-61
+Time part names: second, hour, minute, day, week, month, year.
+.TP
+.B 62-65
+Hours of the day names: midnight, morning, noon, evening.
+.TP
+.B 66-68
+Relative day names: yesterday, today, tomorrow.
+.TP
+.B 69-71
+Past relative time references: last, ago, past.
+.TP
+.B 72-75
+Current relative time references: this, now, current.
+.TP
+.B 75-77
+Future relative time references: next, hence, coming.
+.TP
+.B 78-80
+Exact relative time references: exactly.
+.TP
+.B 81-84
+Noise words to be ignored: at, in, on.
+.TP
+.B 85-94
+Ordinal suffixes: st, nd, rd, th, th, th, th, th, th, th.
+.TP
+.B 95-104
+Digit names.
+.TP
+.B 105
+The
+.L tmfmt()
+format equivalent for
+.BR ctime (3):
+.LR '"%a %b %e %T %Y"' .
+.TP
+.B 106
+The
+.L tmfmt()
+.BR date (1)
+default format:
+.LR '"%a %b %e %T %Z %Y"' .
+.TP
+.B 107
+The
+.L tmfmt()
+.BR date (1)
+international format:
+.LR '"%a %b %e %T %z %Z %Y"' .
+.TP
+.B 108
+The
+.L tmfmt()
+.BR ls (1)
+recent date format:
+.LR '"%b %e %H:%M"' .
+.TP
+.B 109
+The
+.L tmfmt()
+.BR ls (1)
+distant date format:
+.LR '"%b %e  %Y"' .
+.TP
+.B 110
+The
+.L tmfmt()
+.BR date (1)
+meridian date format:
+.LR '"%I:%M:%S %p"' .
+.TP
+.B 111
+The ERA name.
+.TP
+.B 112
+ERA alternative for
+.BR 39 .
+.TP
+.B 113
+ERA alternative for
+.BR 38 .
+.TP
+.B 114
+ERA alternative for
+.BR 40 .
+.TP
+.B 115
+The ERA year.
+.TP
+.B 116-125
+Ordinal names: first, \fIno second!\fP, third, fourth, fifth, sixth, seventh, eighth, ninth, tenth.
+.TP
+.B 126-128
+Final time references, as in \fIthe last in the list\fP: final, ending, nth.
+.PD
+.RE
+.PP
+Low level support functions and data are described in
+.LR <tm.h> .
+.SH EXAMPLES
+.EX
+#include <tm.h>
+main() {
+    int       i;
+    time_t    t;
+    char      buf[128];
+    struct {
+        char* date;
+        char* format;
+    }         x[] = {
+        "now",                 "%i",
+        "2 months ago",        "%C",
+        "this Wednesday noon", "%x %I:%M %p",
+        "last December 25",    "%A",
+        0,                     0
+    };
+    for (i = 0; x[i].date; i++) {
+        t = tmdate(x[i].date, (char*)0, (time_t*)0);
+        (void)tmfmt(buf, sizeof(buf), x[i].format, &t);
+        puts(buf);
+    }
+}
+.EE
+produces
+.EX
+Fri Sep 30 12:10:14 USA EDT 1988
+Fri Jul  1 00:00:00 EDT 1988
+10/05/88 12:00 PM
+Friday
+.EE
+.SH "SEE ALSO"
+.BR date (1),
+.BR time (2),
+.BR ctime (3)
+.SH BUGS
+The C library static
+.L "struct tm"
+values may get clobbered by
+.I tm
+library routines as the
+.BR ctime (3)
+and
+.BR localtime (3)
+routines typically return pointers to a single static
+.L "struct tm"
+area.
+.L tmdate()
+uses an internal international time zone name table that will
+probably always be incomplete.