TM(3)

NAME
tm - seconds resolution time conversion support

SYNOPSIS

DESCRIPTION
The tm library supports conversion between string date specifications, seconds resolution clock values and contains the elements of along with these additions:

The subsecond portion of the time in nanoseconds.

The time zone name.

and (see ctime(3)) are used to determine local time zone and savings time information.

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

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

Set by
    if and do not compensate for leap seconds.

values are interpreted as if they include leap seconds.
    Set by if the option is set in the environment variable.

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

Parses the date specification
    using the string table (described below) and returns the equivalent value. If is set to the position of the first unrecognized character in is used to provide default values for omitted components in If is then the current time is used.

Corrects any out of bounds fields in
    and returns as its value. The corrections start with and propagate down to For example, if were 61 then it would change to 1 and would be incremented by 1, and so on. is not changed -- call to determine its proper value after the adjustments.

Formats the date pointed to by
    into the buffer with size bytes according to the format specification If is or empty then the string is used. If is then the current time is used. A pointer to the end of (i.e., the terminating is returned.

    is in printf(3) style, where %field names a fixed size field, zero padded if necessary, and \c and \nnn sequences are as in C. Invalid %field specifications and all other characters are copied without change. field may be preceded by %- to turn off padding or %_ to pad with space, otherwise numeric fields are padded with 0 and string fields are padded with space. field may also be preceded by E for alternate era representation or O for alternate digit representation (if supported by the current locale). Finally, an integral width preceding field truncates the field to width characters. sequences are interpreted as in the C language. String field values are taken from the string table. The fields are:

    %   % character.
    a   Abbreviated weekday name.
    A   Full weekday name.
    b   Abbreviated month name.
    B   Full 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.
    f   Date as %Y.%m.%d-%H:%M:%S.
    F   ISO 8601:2000 standard date format; equivalent to %Y-%m-%d.
    h   Abbreviated month name.
    H   24-hour clock hour, zero-padded.
    i   International date(1) date that includes the time zone type name
    I   12-hour clock hour, zero-padded.
    j   1-offset Julian date.
    J   0-offset Julian date.
    k   24-hour clock hour, blank-padded.
    K   Language neutral, all numeric, no embedded space date with larger to smaller time units from left to right, suitable for sorting:
    l   12-hour clock hour, blank-padded.
    m   Month number.
    M   Minutes.
    n   newline character.
    N   Nanoseconds 000000000-999999999.
    p   Meridian (e.g., AM or PM).
    P   Lowercase meridian (e.g., am or pm).
    q   The quarter of the year.
    %Q<delim>recent<delim>distant<delim>
        Recent dates are formatted with recent and distant dates are formatted with distant, where <delim> is any character not appearing in recent or distant.
    r   12-hour time as hh:mm:ss meridian.
    R   24-hour time as hh:mm.
    s   Seconds since the epoch. .prec preceding s appends prec nanosecond digits, 9 if prec is omitted.
    S   seconds.subseconds since the epoch.
    t   tab character.
    T   24-hour time as hh:mm:ss.
    u   Weekday number with 1 for Monday, 7 for Sunday.
    U   Week number with Sunday as the first day.
    V   ISO week number (i18n is fun).
    w   Weekday number with 0 for Sunday, 6 for Saturday.
    W   Week number with Monday as the first day.
    x   Local date style, using that includes the month, day and year.
    X   Local time style, using that includes the hours and minutes.
    y   2-digit year (you'll be sorry).
    Y   4-digit year.
    z   Time zone SHHMM west of UTC offset where S is + or -.
    Z   Time zone name.
    =[=]][-+]]flag
        Set (default or +) or clear (-) flag in for the remainder of format, or for the remainder of the process if == is specified. flag may be:
        l   Enable leap second adjustments.
        s   Append nanosecond .%N to %S.
        u   UTC time zone.
    #   Equivalent to %s.
    ?alternate
        The alternate format is a default format override has not been specified. e.g., ls(1) uses %?%l. Export TM_OPTIONS="format='override'" to override the default.

Implicitly called by the other
    tm library routines to initialize global data, including the table and the global flags. Global data should only be modified after an explicit call to If then it specifies a time zone other that the local time zone.

sets the reference timezone to
    points to the local timezone and points to the current reference timezone.

Returns a
    value for the time pointed to by with leap seconds adjusted for external routines that do not handle leap seconds. If is then the current time is used. Adjustments are only done if the flag is set in

Returns a pointer to the
    struct corresponding to the time pointed to by If is then the current time is used.

Returns the
    value corresponding to If is then is relative to the local time zone, otherwise is the number of minutes west of UTC with daylight savings time taken into account. and are ignored in the conversion.

The library routines use a table of date strings pointed to by The indices in are fixed by category. 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  local time format used by the %X field.
    39  local date format used by the %x field.
    40  format used if the argument is or empty.
    41-42
        Meridian names: AM, PM.
    43-46
        UTC time zone names: UTC, UCT, CUT, GMT.
    47-50
        Daylight savings time suffix names: DST.
    51-54
        Suffixes to be ignored when matching strings in
    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-84
        Noise words to be ignored: at, in, on.
    85-94
        Ordinal suffixes: st, nd, rd, th, th, th, th, th, th, th.
    95-104
        Digit names.
    105 The format equivalent for ctime(3):
    106 The date(1) default format:
    107 The date(1) international format:
    108 The ls(1) recent date format:
    109 The ls(1) distant date format:
    110 The date(1) meridian date format:
    111 The ERA name.
    112 ERA alternative for 39.
    113 ERA alternative for 38.
    114 ERA alternative for 40.
    115 The ERA year.
    116-125
        Ordinal names: first, no second!, third, fourth, fifth, sixth, seventh, eighth, ninth, tenth.
    126-128
        Final time references, as in the last in the list: final, ending, nth.

Low level support functions and data are described in

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)tmfmt(buf, sizeof(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

SEE ALSO
date(1), time(2), ctime(3)

BUGS
The C library static values may get clobbered by tm library routines as the ctime(3) and localtime(3) routines typically return pointers to a single static area. uses an internal international time zone name table that will probably always be incomplete.