tmx(3)

NAME

tm - time conversion support

SYNOPSIS

$1$2#include <tm.h>#include <tm.h>#include <tm.h>#include <tm.h>#include <tm.h>#include <tm.h>#include <tm.h>#include <tm.h>

DESCRIPTION

The tm library supports conversion between string date specifications, $1$2time_ttime_ttime_ttime_ttime_ttime_ttime_ttime_t clock values and $1$2struct tmstruct tmstruct tmstruct tmstruct tmstruct tmstruct tmstruct tm values. $1$2localtime()localtime()localtime()localtime()localtime()localtime()localtime()localtime() and $1$2gmtime()gmtime()gmtime()gmtime()gmtime()gmtime()gmtime()gmtime() (see ctime(3)) are used to determine local time zone information.

$1$2time_ttime_ttime_ttime_ttime_ttime_ttime_ttime_t values are the number of seconds since the epoch, Jan 1 00:00:00 GMT 1970, with leap seconds omitted.

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

$1$2TM_ADJUSTTM_ADJUSTTM_ADJUSTTM_ADJUSTTM_ADJUSTTM_ADJUSTTM_ADJUSTTM_ADJUST

Set by $1$2tminit()tminit()tminit()tminit()tminit()tminit()tminit()tminit() if $1$2localtime()localtime()localtime()localtime()localtime()localtime()localtime()localtime() and $1$2gmtime()gmtime()gmtime()gmtime()gmtime()gmtime()gmtime()gmtime() do not compensate for leap seconds.

$1$2TM_LEAPTM_LEAPTM_LEAPTM_LEAPTM_LEAPTM_LEAPTM_LEAPTM_LEAP

$1$2time_ttime_ttime_ttime_ttime_ttime_ttime_ttime_t values are interpreted as if they include leap seconds. Set by $1$2tminit()tminit()tminit()tminit()tminit()tminit()tminit()tminit() if the $1$2leapleapleapleapleapleapleapleap option is set in the $1$2TM_OPTIONSTM_OPTIONSTM_OPTIONSTM_OPTIONSTM_OPTIONSTM_OPTIONSTM_OPTIONSTM_OPTIONS environment variable.

$1$2TM_UTCTM_UTCTM_UTCTM_UTCTM_UTCTM_UTCTM_UTCTM_UTC

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

$1$2time_t tmdate(const char* date, char** end, time_t* clock)time_t tmdate(const char* date, char** end, time_t* clock)time_t tmdate(const char* date, char** end, time_t* clock)time_t tmdate(const char* date, char** end, time_t* clock)time_t tmdate(const char* date, char** end, time_t* clock)time_t tmdate(const char* date, char** end, time_t* clock)time_t tmdate(const char* date, char** end, time_t* clock)time_t tmdate(const char* date, char** end, time_t* clock)

Parses the date specification $1$2datedatedatedatedatedatedatedate using the $1$2tm_info.formattm_info.formattm_info.formattm_info.formattm_info.formattm_info.formattm_info.formattm_info.format string table (described below) and returns the equivalent $1$2time_ttime_ttime_ttime_ttime_ttime_ttime_ttime_t value. If $1$2non-non-non-non-non-non-non-non- $1$2endendendendendendendend is set to the position of the first unrecognized character in $1$2datedatedatedatedatedatedatedate $1$2clockclockclockclockclockclockclockclock is used to provide default values for omitted components in $1$2datedatedatedatedatedatedatedate If $1$2clockclockclockclockclockclockclockclock is $1$2NULLNULLNULLNULLNULLNULLNULLNULL then the current time is used.

$1$2struct tm* tmfix(struct tm* tp)struct tm* tmfix(struct tm* tp)struct tm* tmfix(struct tm* tp)struct tm* tmfix(struct tm* tp)struct tm* tmfix(struct tm* tp)struct tm* tmfix(struct tm* tp)struct tm* tmfix(struct tm* tp)struct tm* tmfix(struct tm* tp)

Corrects any out of bounds fields in $1$2tptptptptptptptp and returns $1$2tptptptptptptptp as its value. The corrections start with $1$2tp->tm_sectp->tm_sectp->tm_sectp->tm_sectp->tm_sectp->tm_sectp->tm_sectp->tm_sec and propagate down to $1$2tp->tm_yeartp->tm_yeartp->tm_yeartp->tm_yeartp->tm_yeartp->tm_yeartp->tm_yeartp->tm_year For example, if $1$2tp->tm_sectp->tm_sectp->tm_sectp->tm_sectp->tm_sectp->tm_sectp->tm_sectp->tm_sec were 61 then it would change to 1 and $1$2tp->tm_mintp->tm_mintp->tm_mintp->tm_mintp->tm_mintp->tm_mintp->tm_mintp->tm_min would be incremented by 1, and so on. $1$2tp->tm_wdaytp->tm_wdaytp->tm_wdaytp->tm_wdaytp->tm_wdaytp->tm_wdaytp->tm_wdaytp->tm_wday $1$2tp->tm_ydaytp->tm_ydaytp->tm_ydaytp->tm_ydaytp->tm_ydaytp->tm_ydaytp->tm_ydaytp->tm_yday and $1$2tp->tm_isdsttp->tm_isdsttp->tm_isdsttp->tm_isdsttp->tm_isdsttp->tm_isdsttp->tm_isdsttp->tm_isdst are not changed as these can be computed from the other fields.

$1$2char* tmfmt(char* buf, size_t len, const char* format, time_t* clock)char* tmfmt(char* buf, size_t len, const char* format, time_t* clock)char* tmfmt(char* buf, size_t len, const char* format, time_t* clock)char* tmfmt(char* buf, size_t len, const char* format, time_t* clock)char* tmfmt(char* buf, size_t len, const char* format, time_t* clock)char* tmfmt(char* buf, size_t len, const char* format, time_t* clock)char* tmfmt(char* buf, size_t len, const char* format, time_t* clock)char* tmfmt(char* buf, size_t len, const char* format, time_t* clock)

Formats the date pointed to by $1$2clockclockclockclockclockclockclockclock into the buffer $1$2bufbufbufbufbufbufbufbuf with size $1$2lenlenlenlenlenlenlenlen bytes according to the format specification $1$2formatformatformatformatformatformatformatformat If $1$2formatformatformatformatformatformatformatformat is $1$2NULLNULLNULLNULLNULLNULLNULLNULL or empty then the string $1$2tm_info.format[40]tm_info.format[40]tm_info.format[40]tm_info.format[40]tm_info.format[40]tm_info.format[40]tm_info.format[40]tm_info.format[40] is used. If $1$2clockclockclockclockclockclockclockclock is $1$2NULLNULLNULLNULLNULLNULLNULLNULL then the current time is used. A pointer to the end of $1$2bufbufbufbufbufbufbufbuf (i.e., the terminating $1$2'\0''\0''\0''\0''\0''\0''\0''\0' is returned.

$1$2formatformatformatformatformatformatformatformat is in the style of printf(3), where %field causes the corresponding fixed size field to be placed in $1$2bufbufbufbufbufbufbufbuf 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 $1$2formatformatformatformatformatformatformatformat are copied into $1$2bufbufbufbufbufbufbufbuf without change. String field values are taken from the $1$2tm_info.formattm_info.formattm_info.formattm_info.formattm_info.formattm_info.formattm_info.formattm_info.format string 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 $1$2tm_info.format[39]tm_info.format[39]tm_info.format[39]tm_info.format[39]tm_info.format[39]tm_info.format[39]tm_info.format[39]tm_info.format[39] that includes the month, day and year.

X

Local time style, using $1$2tm_info.format[38]tm_info.format[38]tm_info.format[38]tm_info.format[38]tm_info.format[38]tm_info.format[38]tm_info.format[38]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 $1$2tmform()tmform()tmform()tmform()tmform()tmform()tmform()tmform() returns) sets (+) or clears (-) the $1$2tm_info.flagstm_info.flagstm_info.flagstm_info.flagstm_info.flagstm_info.flagstm_info.flagstm_info.flags flags specified by flag:

l

$1$2TM_LEAPTM_LEAPTM_LEAPTM_LEAPTM_LEAPTM_LEAPTM_LEAPTM_LEAP

u

$1$2TM_UTCTM_UTCTM_UTCTM_UTCTM_UTCTM_UTCTM_UTCTM_UTC

#

Number of seconds since the epoch.

$1$2void tminit(Tm_zone_t* zone)void tminit(Tm_zone_t* zone)void tminit(Tm_zone_t* zone)void tminit(Tm_zone_t* zone)void tminit(Tm_zone_t* zone)void tminit(Tm_zone_t* zone)void tminit(Tm_zone_t* zone)void tminit(Tm_zone_t* zone)

Implicitly called by the other tm library routines to initialize global data, including the $1$2tm_info.formattm_info.formattm_info.formattm_info.formattm_info.formattm_info.formattm_info.formattm_info.format table and the $1$2tm_info.flagstm_info.flagstm_info.flagstm_info.flagstm_info.flagstm_info.flagstm_info.flagstm_info.flags global flags. Global data should only be modified after an explicit call to $1$2tminittminittminittminittminittminittminittminit If $1$2zone != 0zone != 0zone != 0zone != 0zone != 0zone != 0zone != 0zone != 0 then it specifies a time zone other that the local time zone.

$1$2void tmset(Tm_zone_t* zone);void tmset(Tm_zone_t* zone);void tmset(Tm_zone_t* zone);void tmset(Tm_zone_t* zone);void tmset(Tm_zone_t* zone);void tmset(Tm_zone_t* zone);void tmset(Tm_zone_t* zone);void tmset(Tm_zone_t* zone);

$1$2tmsettmsettmsettmsettmsettmsettmsettmset sets the reference timezoe to $1$2zonezonezonezonezonezonezonezone $1$2tm_info.localtm_info.localtm_info.localtm_info.localtm_info.localtm_info.localtm_info.localtm_info.local points to the local timezone and $1$2tm_info.zonetm_info.zonetm_info.zonetm_info.zonetm_info.zonetm_info.zonetm_info.zonetm_info.zone points to the current reference timezone.

$1$2time_t tmleap(time_t* clock)time_t tmleap(time_t* clock)time_t tmleap(time_t* clock)time_t tmleap(time_t* clock)time_t tmleap(time_t* clock)time_t tmleap(time_t* clock)time_t tmleap(time_t* clock)time_t tmleap(time_t* clock)

Returns a $1$2time_ttime_ttime_ttime_ttime_ttime_ttime_ttime_t value for the time pointed to by $1$2clockclockclockclockclockclockclockclock with leap seconds adjusted for external routines that do not handle leap seconds. If $1$2clockclockclockclockclockclockclockclock is $1$2NULLNULLNULLNULLNULLNULLNULLNULL then the current time is used. Adjustments are only done if the $1$2TM_ADJUSTTM_ADJUSTTM_ADJUSTTM_ADJUSTTM_ADJUSTTM_ADJUSTTM_ADJUSTTM_ADJUST flag is set in $1$2tm_info.flagstm_info.flagstm_info.flagstm_info.flagstm_info.flagstm_info.flagstm_info.flagstm_info.flags

$1$2struct tm* tmmake(time_t* clock)struct tm* tmmake(time_t* clock)struct tm* tmmake(time_t* clock)struct tm* tmmake(time_t* clock)struct tm* tmmake(time_t* clock)struct tm* tmmake(time_t* clock)struct tm* tmmake(time_t* clock)struct tm* tmmake(time_t* clock)

Returns a pointer to the $1$2tmtmtmtmtmtmtmtm struct corresponding to the time pointed to by $1$2clockclockclockclockclockclockclockclock If $1$2clockclockclockclockclockclockclockclock is $1$2NULLNULLNULLNULLNULLNULLNULLNULL then the current time is used.

$1$2time_t tmtime(struct tm* tp, int west)time_t tmtime(struct tm* tp, int west)time_t tmtime(struct tm* tp, int west)time_t tmtime(struct tm* tp, int west)time_t tmtime(struct tm* tp, int west)time_t tmtime(struct tm* tp, int west)time_t tmtime(struct tm* tp, int west)time_t tmtime(struct tm* tp, int west)

Returns the $1$2time_ttime_ttime_ttime_ttime_ttime_ttime_ttime_t value corresponding to $1$2tptptptptptptptp If $1$2westwestwestwestwestwestwestwest is $1$2TM_LOCALZONETM_LOCALZONETM_LOCALZONETM_LOCALZONETM_LOCALZONETM_LOCALZONETM_LOCALZONETM_LOCALZONE then $1$2tmtmtmtmtmtmtmtm is relative to the local time zone, otherwise $1$2westwestwestwestwestwestwestwest is the number of minutes west of UTC with daylight savings time taken into account. $1$2tp->tm_wdaytp->tm_wdaytp->tm_wdaytp->tm_wdaytp->tm_wdaytp->tm_wdaytp->tm_wdaytp->tm_wday $1$2tp->tm_ydaytp->tm_ydaytp->tm_ydaytp->tm_ydaytp->tm_ydaytp->tm_ydaytp->tm_ydaytp->tm_yday and $1$2tp->tm_isdsttp->tm_isdsttp->tm_isdsttp->tm_isdsttp->tm_isdsttp->tm_isdsttp->tm_isdsttp->tm_isdst are ignored in the conversion.

The library routines use a table of date strings pointed to by $1$2char** tm_info.formatchar** tm_info.formatchar** tm_info.formatchar** tm_info.formatchar** tm_info.formatchar** tm_info.formatchar** tm_info.formatchar** tm_info.format The indices in $1$2tm_info.formattm_info.formattm_info.formattm_info.formattm_info.formattm_info.formattm_info.formattm_info.format are fixed by category. $1$2tm_info.formattm_info.formattm_info.formattm_info.formattm_info.formattm_info.formattm_info.formattm_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:

Low level support functions and data are described in $1$2<tm.h><tm.h><tm.h><tm.h><tm.h><tm.h><tm.h><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

SEE ALSO

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

BUGS

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