tm(3)

NAME

tm - seconds resolution 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, seconds reolution $1$2time_ttime_ttime_ttime_ttime_ttime_ttime_ttime_t clock values and $1$2Tm_tTm_tTm_tTm_tTm_tTm_tTm_tTm_t $1$2Tm_tTm_tTm_tTm_tTm_tTm_tTm_tTm_t contains the elements of $1$2struct tmstruct tmstruct tmstruct tmstruct tmstruct tmstruct tmstruct tm along with these additions:

$1$2unsigned _ast_int4_t tm_nsecunsigned _ast_int4_t tm_nsecunsigned _ast_int4_t tm_nsecunsigned _ast_int4_t tm_nsecunsigned _ast_int4_t tm_nsecunsigned _ast_int4_t tm_nsecunsigned _ast_int4_t tm_nsecunsigned _ast_int4_t tm_nsec

The subsecond portion of the time in nanoseconds.

$1$2Tm_zone_t* tm_zoneTm_zone_t* tm_zoneTm_zone_t* tm_zoneTm_zone_t* tm_zoneTm_zone_t* tm_zoneTm_zone_t* tm_zoneTm_zone_t* tm_zoneTm_zone_t* tm_zone

The time zone name.

$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 and savings time 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$2Tm_t* tmfix(Tm_t* tp)Tm_t* tmfix(Tm_t* tp)Tm_t* tmfix(Tm_t* tp)Tm_t* tmfix(Tm_t* tp)Tm_t* tmfix(Tm_t* tp)Tm_t* tmfix(Tm_t* tp)Tm_t* tmfix(Tm_t* tp)Tm_t* tmfix(Tm_t* 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_isdsttp->tm_isdsttp->tm_isdsttp->tm_isdsttp->tm_isdsttp->tm_isdsttp->tm_isdsttp->tm_isdst is not changed -- call $1$2tmtime()tmtime()tmtime()tmtime()tmtime()tmtime()tmtime()tmtime() to determine its proper value after the $1$2tmfix()tmfix()tmfix()tmfix()tmfix()tmfix()tmfix()tmfix() adjustments.

$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 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 $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.

f

Locale default override date format.

F

Locale default date format $1$2((((((((

h

Abbreviated month name.

H

24-hour clock hour.

i

International date(1) date that includes the time zone type name $1$2((((((((

I

12-hour clock hour.

j

1-offset Julian date.

J

0-offset Julian date.

k

date(1) style date $1$2((((((((

K

Language neutral, all numeric, no embedded space date with larger to smaller time units from left to right, suitable for sorting: $1$2''''''''

l

ls(1) -l date that lists recent dates with $1$2%g%g%g%g%g%g%g%g and distant dates with %G.

m

Month number.

M

Minutes.

n

newline character.

N

The time zone type or nation code.

p

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

q

The nanosecond part of the time.

%Q<delim>recent<delim>distant<delim>

Recent dates are formatted with recent and distand 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

Weeday 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 $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 (you'll be sorry.)

Y

4-digit year.

z

Time zone SHHMM west of GMT offset where S is + or -.

Z

Time zone name.

=[=]][-+]]flag

Set (default or +) or clear (-) flag in $1$2tm_info.flagstm_info.flagstm_info.flagstm_info.flagstm_info.flagstm_info.flagstm_info.flagstm_info.flags for the remainder of format, or for the remainder of the process if == is specified. flag may be:

l

$1$2(TM_LEAP)(TM_LEAP)(TM_LEAP)(TM_LEAP)(TM_LEAP)(TM_LEAP)(TM_LEAP)(TM_LEAP) Enable leap second adjustments.

s

$1$2(TM_SUBSECOND)(TM_SUBSECOND)(TM_SUBSECOND)(TM_SUBSECOND)(TM_SUBSECOND)(TM_SUBSECOND)(TM_SUBSECOND)(TM_SUBSECOND) Append nanosecond .%N to %S.

u

$1$2(TM_UTC)(TM_UTC)(TM_UTC)(TM_UTC)(TM_UTC)(TM_UTC)(TM_UTC)(TM_UTC) UTC time zone.

#

Equivalent to %s.

?alternate

Use 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.

$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$2Tm_t* tmmake(time_t* clock)Tm_t* tmmake(time_t* clock)Tm_t* tmmake(time_t* clock)Tm_t* tmmake(time_t* clock)Tm_t* tmmake(time_t* clock)Tm_t* tmmake(time_t* clock)Tm_t* tmmake(time_t* clock)Tm_t* tmmake(time_t* clock)

Returns a pointer to the $1$2Tm_tTm_tTm_tTm_tTm_tTm_tTm_tTm_t 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(Tm_t* tp, int west)time_t tmtime(Tm_t* tp, int west)time_t tmtime(Tm_t* tp, int west)time_t tmtime(Tm_t* tp, int west)time_t tmtime(Tm_t* tp, int west)time_t tmtime(Tm_t* tp, int west)time_t tmtime(Tm_t* tp, int west)time_t tmtime(Tm_t* 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)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 $1$2struct tmstruct tmstruct tmstruct tmstruct tmstruct tmstruct tmstruct tm values may get clobbered by tm library routines as the ctime(3) and localtime(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.