tmx(3)
NAME
tm - time conversion support
SYNOPSIS
#include <tm.h>
DESCRIPTION
The tm library supports conversion between string date specifications,
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
GMT 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.for-
mat[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-NULL, 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 ta-
ble. 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 dis-
tant 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 tm_info.format[39], that includes
the month, day and year.
X Local time style, using 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 tmform() returns) sets (+) or clears
(-) the tm_info.flags flags specified by flag:
l TM_LEAP
u TM_UTC
# Number of seconds since the epoch.
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 speci-
fies 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, other-
wise 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:
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 tmform() local time format used by the %X field.
39 tmform() local date format used by the %x field.
40 tmform() format used if the format argument is NULL 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 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 <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
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.
TM(3)
Man(1) output converted with
man2html