| Solaris |
|
|
tm.3
Introduction to Library Functions TM(3)
NAME
tm - seconds resolution time conversion support
SYNOPSIS
#include <tm.h>
DESCRIPTION
The tm library supports conversion between string date
specifications, seconds reolution time_t clock values and
Tm_t. Tm_t contains the elements of struct tm along with
these additions:
unsigned _ast_int4_t tm_nsec
The subsecond portion of the time in nanoseconds.
Tm_zone_t* tm_zone
The time zone name.
localtime() and gmtime() (see ctime(3)) are used to deter-
mine local time zone and savings time 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 com-
pensate 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 environ-
ment 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.
SunOS 5.10 Last change: 1
Introduction to Library Functions TM(3)
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 char-
acter in date. clock is used to provide default values
for omitted components in date. If clock is NULL then
the current time is used.
Tm_t* tmfix(Tm_t* 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_isdst is not changed ~-- call tmtime() to determine
its proper value after the tmfix() adjustments.
clock)
char* tmfmt(char* buf, size_t len, const char* format, time_t*
Formats the date pointed to by clock into the buffer
buf with size len bytes according to the format specif-
ication 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 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 specifica-
tions and all other characters are copied without
change. field may be preceded by %- to turn off pad-
ding 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 representa-
tion (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
tm_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.
SunOS 5.10 Last change: 2
Introduction to Library Functions TM(3)
e Blank padded day of month number.
E Unpadded day of month number.
f Locale default override date format.
F Locale default date format (tm_info.format[40].)
h Abbreviated month name.
H 24-hour clock hour.
i International date(1) date that includes the time
zone type name (tm_info.format[107].)
I 12-hour clock hour.
j 1-offset Julian date.
J 0-offset Julian date.
k date(1) style date (tm_info.format[106].)
K Language neutral, all numeric, no embedded space
date with larger to smaller time units from left
to right, suitable for sorting: '%Y-%m-
%d+%H:%M:%S'" ." " " " " "
l ls(1) -l date that lists recent dates with %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 omit-
ted.
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 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 (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
SunOS 5.10 Last change: 3
Introduction to Library Functions TM(3)
tm_info.flags for the remainder of format, or for
the remainder of the process if == is specified.
flag may be:
l (TM_LEAP) Enable leap second adjustments.
s (TM_SUBSECOND) Append nanosecond .%N to %S.
u (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.
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.
Tm_t* tmmake(time_t* clock)
Returns a pointer to the Tm_t struct corresponding to
the time pointed to by clock. If clock is NULL then
the current time is used.
time_t tmtime(Tm_t* 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 conven-
tions. The contents by index (showing the USA English
values) are:
SunOS 5.10 Last change: 4
Introduction to Library Functions TM(3)
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 tmfmt() local time format used by the %X field.
39 tmfmt() local date format used by the %x field.
40 tmfmt() 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
tmfmt().
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, com-
ing.
78-80
Exact relative time references: exactly.
81-84
Noise words to be ignored: at, in, on.
85-94
Ordinal suffixes: st, nd, rd, th, th, th, th, th,
th, th.
95-104
Digit names.
105 The tmfmt() format equivalent for ctime(3): '%a
%b" %e" %T" %Y" '" " " " " "
106 The tmfmt() date(1) default format: '%a %b" %e"
%T" %Z" %Y" " " " " "
107 The tmfmt() date(1) international format: '%a %b"
%e" %T" %z" %Z" " " " " "
108 The tmfmt() ls(1) recent date format: '%b %e"
SunOS 5.10 Last change: 5
Introduction to Library Functions TM(3)
%H:%M" '" .
109 The tmfmt() ls(1) distant date format: '%b %e"
%Y" '" .
110 The tmfmt() date(1) meridian date format:
'%I:%M:%S %p" '" .
111 The ERA name.
112 ERA alternative for 39.
113 ERA alternative for 38.
114 ERA alternative for 40.
115 The ERA year.
116-125
Ordinal names: first, no second!, third, fourth,
fifth, sixth, seventh, eighth, ninth, tenth.
126-128
Final time references, as in the last in the list:
final, ending, nth.
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)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)
SunOS 5.10 Last change: 6
Introduction to Library Functions TM(3)
BUGS
The C library static struct tm values may get clobbered by
tm library routines as the ctime(3) and localtime(3) rou-
tines 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.
SunOS 5.10 Last change: 7
Generated by GNU enscript 1.6.4.
XWiki Enterprise 2.7.1.34853 - Documentation
Terms of Use
|
Privacy
|
Trademarks
|
Copyright Policy
|
Site Guidelines
|
Site Map
|
Help
Your use of this web site or any of its content or software indicates your agreement to be bound by these Terms of Use.
© 2012, Oracle Corporation and/or its affiliates.