--- name: "tmx" section: "3" platform: "macos" package: "ksh" version: "42" release: "macOS 26.5" platforms: ["macos"] url: "https://new.carta.tech/tmx" --- # tmx(3) time conversion support ## NAME tm - time conversion support ## SYNOPSIS $1$2#include \#include \#include \#include \#include \#include \#include \#include \ ## 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)](/ctime/3.md)) 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)](/printf/3.md), 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)](/ctime/3.md) style date without the trailing **newline**. - **C** [*date*(1)](/date/1.md) 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/1.md) 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)](/ls/1.md) **-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: - **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** $1$2tmform()tmform()tmform()tmform()tmform()tmform()tmform()tmform() local time format used by the **%X** field. - **39** $1$2tmform()tmform()tmform()tmform()tmform()tmform()tmform()tmform() local date format used by the **%x** field. - **40** $1$2tmform()tmform()tmform()tmform()tmform()tmform()tmform()tmform() format used if the $1$2formatformatformatformatformatformatformatformat argument is $1$2NULLNULLNULLNULLNULLNULLNULLNULL or empty. - **41-42** Meridian names: AM, PM. - **43-46** **UTC** time zone names: GMT, UTC, UCT, CUT. - **47-50** Daylight savings time suffix names: DST. - **51-54** Suffixes to be ignored when matching strings in $1$2tmform()tmform()tmform()tmform()tmform()tmform()tmform()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 $1$2\\\\\\\\ ## EXAMPLES ``` #include 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)](/date/1.md), [time(2)](/time/2.md), [ctime(3)](/ctime/3.md) ## BUGS $1$2struct tmstruct tmstruct tmstruct tmstruct tmstruct tmstruct tmstruct tm values may get clobbered by the *tm* library routines as the [*ctime*(3)](/ctime/3.md) 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.