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,
Low level support functions and data are described in
time_t
clock values and
struct tm
values.
localtime()
and
gmtime()
(see ctime(3)) are used to determine local time zone information.
time_t
values 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.flags
contains flags that allow all programs using the library to be controlled in a consistent manner.
tm_info.flags
is initialized by the
tminit()
routine described below, and may be explicitly reset after
tminit()
is called. The flags are:
TM_ADJUST Set by tminit() if localtime() and gmtime() do not compensate for leap seconds. |
|||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
TM_LEAP time_t values are interpreted as if they include leap seconds. Set by tminit() if the leap option is set in the TM_OPTIONS environment variable. |
|||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
TM_UTC Times 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 date using the tm_info.format string table (described below) and returns the equivalent time_t value. If non-end is set to the position of the first unrecognized character in date clock is used to provide default values for omitted components in date If clock is NULL then the current time is used. |
|||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
struct tm* tmfix(struct tm* tp) Corrects any out of bounds fields in tp and returns tp as its value. The corrections start with tp->tm_sec and propagate down to tp->tm_year For example, if tp->tm_sec were 61 then it would change to 1 and tp->tm_min would be incremented by 1, and so on. tp->tm_wday tp->tm_yday and tp->tm_isdst are 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 clock into the buffer buf with size len bytes according to the format specification format If format is NULL or empty then the string tm_info.format[40] is used. If clock is NULL then the current time is used. A pointer to the end of buf (i.e., the terminating ’\0’ is returned.
format is 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 format are copied into buf without change. String field values are taken from the tm_info.format string table. The fields are:
|
|||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
void tminit(Tm_zone_t* zone) Implicitly called by the other tm library routines to initialize global data, including the tm_info.format table and the tm_info.flags global flags. Global data should only be modified after an explicit call to tminit If zone != 0 then it specifies a time zone other that the local time zone. |
|||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
void tmset(Tm_zone_t* zone); tmset sets the reference timezoe to zone tm_info.local points to the local timezone and tm_info.zone points to the current reference timezone. |
|||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
time_t tmleap(time_t* clock) Returns a time_t value for the time pointed to by clock with leap seconds adjusted for external routines that do not handle leap seconds. If clock is NULL then the current time is used. Adjustments are only done if the TM_ADJUST flag is set in tm_info.flags |
|||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
struct tm* tmmake(time_t* clock) Returns a pointer to the tm struct corresponding to the time pointed to by clock If clock is NULL then the current time is used. |
|||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
time_t tmtime(struct tm* tp, int west) Returns the time_t value corresponding to tp If west is TM_LOCALZONE then tm is relative to the local time zone, otherwise west is the number of minutes west of UTC with daylight savings time taken into account. tp->tm_wday tp->tm_yday and tp->tm_isdst are 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.format are 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: |
|||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|
<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 tm
values may get clobbered by the
tm library routines as the ctime(3) routines typically return pointers to a single static struct tm
area.
tmdate()
uses an internal international time zone name table that will probably always be incomplete.