tmx(3ast)

ksh-devel

Korn Shell development environment

NAME

tm - time conversion support

SYNOPSIS

#include <tm.h>

DESCRIPTION

The tm library supports conversion between string date specifications, time_tclock values and struct tmvalues. localtime()and gmtime()(see ctime(3)) are used to determine local time zone information.

time_tvalues are the number of seconds since the epoch, Jan 1 00:00:00 UTC 1970, with leap seconds omitted.

The global variable int tm_info.flagscontains flags that allow all programs using the library to be controlled in a consistent manner. tm_info.flagsis initialized by the tminit()routine described below, and may be explicitly reset after tminit()is called. The flags are:

TM_ADJUSTSet by tminit()if localtime()and gmtime()do not compensate for leap seconds.

TM_LEAPtime_tvalues are interpreted as if they include leap seconds. Set by tminit()if the leapoption is set in the TM_OPTIONSenvironment variable.

TM_UTCTimes are relative to UTC (universal coordinated time, i.e., GMT). Otherwise times are relative to the local time zone. Set by tminit()if the time zone name matches one of tm_info.format[43]through tm_info.format[46]described below. If the time zone name is not determined by localtime()then the environment variables TZNAME(as described in BSD 4.3) and 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.

The routines are:

time_t tmdate(const char* date, char** end, time_t* clock)Parses the date specification dateusing the tm_info.formatstring table (described below) and returns the equivalent time_tvalue. If non-endis set to the position of the first unrecognized character in date clockis used to provide default values for omitted components in date If clockis NULLthen the current time is used.

struct tm* tmfix(struct tm* tp)Corrects any out of bounds fields in tpand returns tpas its value. The corrections start with tp->tm_secand propagate down to tp->tm_year For example, if tp->tm_secwere 61 then it would change to 1 and tp->tm_minwould be incremented by 1, and so on. tp->tm_wday tp->tm_yday and tp->tm_isdstare not changed as these can be computed from the other fields.

char* tmfmt(char* buf, size_t len, const char* format, time_t* clock)Formats the date pointed to by clockinto the buffer bufwith size lenbytes according to the format specification format If formatis NULLor empty then the string tm_info.format[40]is used. If clockis NULLthen the current time is used. A pointer to the end of buf(i.e., the terminating ’\0’ is returned.

formatis in the style of printf(3), where %field causes the corresponding fixed size field to be placed in buf zero padded if necessary, and \c and \nnn sequences are interpreted as in the C language. Otherwise invalid %field specifications and all other characters in formatare copied into bufwithout change. String field values are taken from the tm_info.formatstring table. The fields are:

% % character.

a Abbreviated weekday name.

A Full weekday name.

b Abbreviated month name.

c ctime(3) style date without the trailing newline.

C date(1) style date.

d Day of month number.

D Date as mm/dd/yy.

e Blank padded day of month number.

E Unpadded day of month number.

h Abbreviated month name.

H 24-hour clock hour.

i International date(1) date that includes the time zone type name.

I 12-hour clock hour.

j 1-offset Julian date.

J 0-offset Julian date.

l ls(1) -l date that lists recent dates with hh:mm and distant dates with yyyy.

m Month number.

M Minutes.

n newline character.

p Meridian (e.g., AM or PM).

r 12-hour time as hh:mm:ss meridian.

R 24-hour time as hh:mm.

S Seconds.

t tab character.

T 24-hour time as hh:mm:ss.

U Week number with Sunday as the first day.

w Weekday number.

W Week number with Monday as the first day.

x Local date style, using tm_info.format[39] that includes the month, day and year.

X Local time style, using tm_info.format[38] that includes the hours and minutes.

y 2-digit year.

Y 4-digit year.

z Time zone type name.

Z Time zone name.

+flag
-flag

Temporarily (until tmform()returns) sets (+) or clears (-) the tm_info.flagsflags specified by flag:

l	`TM_LEAP`
u	`TM_UTC`

# Number of seconds since the epoch.

void tminit(Tm_zone_t* zone)Implicitly called by the other tm library routines to initialize global data, including the tm_info.formattable and the tm_info.flagsglobal flags. Global data should only be modified after an explicit call to tminit If zone != 0then it specifies a time zone other that the local time zone.

void tmset(Tm_zone_t* zone);tmsetsets the reference timezoe to zone tm_info.localpoints to the local timezone and tm_info.zonepoints to the current reference timezone.

time_t tmleap(time_t* clock)Returns a time_tvalue for the time pointed to by clockwith leap seconds adjusted for external routines that do not handle leap seconds. If clockis NULLthen the current time is used. Adjustments are only done if the TM_ADJUSTflag is set in tm_info.flags

struct tm* tmmake(time_t* clock)Returns a pointer to the tmstruct corresponding to the time pointed to by clock If clockis NULLthen the current time is used.

time_t tmtime(struct tm* tp, int west)Returns the time_tvalue corresponding to tp If westis TM_LOCALZONEthen tmis relative to the local time zone, otherwise westis the number of minutes west of UTC with daylight savings time taken into account. tp->tm_wday tp->tm_yday and tp->tm_isdstare ignored in the conversion.

The library routines use a table of date strings pointed to by char** tm_info.format The indices in tm_info.formatare fixed by category. 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:

0-11	3-character abbreviated month names.
12-23	Full month names.
24-30	3-character abbreviated weekday names.
31-37	Full weekday names.
38	`tmform()local time format used by the` %X field.
39	`tmform()local date format used by the` %x field.
40	`tmform()format used if the` `formatargument is` `NULLor empty.`
41-42	Meridian names: AM, PM.
43-46	UTC time zone names: UTC, GMT, UCT, CUT.
47-50	Daylight savings time suffix names: DST.
51-54	Suffixes to be ignored when matching strings in `tmform()`
55-61	Time part names: second, hour, minute, day, week, month, year.
62-65	Hours of the day names: midnight, morning, noon, evening.
66-68	Relative day names: yesterday, today, tomorrow.
69-71	Past relative time references: last, ago, past.
72-75	Current relative time references: this, now, current.
75-77	Future relative time references: next, hence, coming.
78-80	Exact relative time references: exactly.
81-85	Noise words to be ignored: at, in, on.

Low level support functions and data are described in <tm.h>

EXAMPLES

#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)tmform(buf, x[i].format, &t);
        puts(buf);
    }
}

produces

Fri Sep 30 12:10:14 USA EDT 1988
Fri Jul  1 00:00:00 EDT 1988
10/05/88 12:00 PM
Friday

BUGS

struct tmvalues may get clobbered by the tm library routines as the ctime(3) routines typically return pointers to a single static struct tmarea. tmdate()uses an internal international time zone name table that will probably always be incomplete.