NAME
tmnow, tzload, tmtime, tmparse, tmfmt, tmnorm – convert date and
time |
SYNOPSIS
#include <u.h> #include <libc.h>
typedef struct Tm Tm; |
DESCRIPTION
This family of functions handles simple date and time manipulation.
Time zones are loaded by name. They can be specified as the abbreviated timezone name, the full timezone name, the path to a timezone file, or an absolute offset in the HHMM form. When given as a timezone, any instant–dependent adjustments such as leap seconds and daylight savings time will be applied to the derived fields of struct Tm, but will not affect the absolute time. The time zone name local always refers to the time in /env/timezone. The nil timezone always refers to GMT. Tzload loads a timezone by name. The returned timezone is cached for the lifetime of the program, and should not be freed. Loading a timezone repeatedly by name loads from the cache, and does not leak. Tmnow gets the current time of day in the requested time zone. Tmtime converts the second resolution timestamp 'abs' into a Tm struct in the requested timezone. Tmtimens does the same, but with a nanosecond accuracy. Tmtimens is identical to tmtime, but accepts a nanosecond argument. Tmparse parses a time from a string according to the format argument. Leading whitespace is ignored. The point at which the parsing stopped is returned in ep. If ep is nil, trailing garbage is ignored. The result is returned in the timezone requested. If there is a timezone in the date, and a timezone is provided when parsing, then the zone is shifted to the provided timezone. Parsing is case–insensitive
The format argument contains zero or more of the following components:
o Ordinal day of month suffix specifier. [...]
? When parsing, all formats of the following argument are tried from most to least specific. For example, ?M will match January, Jan, 01, and 1, in that order. When formatting, ? is ignored. ~ When parsing a date, this slackens range enforcement, accepting out of range values such as January 32, which would get normalized to February 1st.
Any characters not specified above are copied directly to output,
without modification.
Tmfmt produces a format description structure suitable for passing
to fmtprint(2). If fmt is nil, we default to the format used in
ctime(2). The format of the format string is identical to tmparse.
When parsing, any amount of whitespace is treated as a single
token. All string matches are case insensitive, and zero padding
is optional. Tmnorm takes a manually adjusted Tm structure, and normalizes it, returning the absolute timestamp that the date represents. Normalizing recomputes the year, mon, mday, hr, min, sec and tzoff fields. If tz is non–nil, then tzoff will be recomputed, taking into account daylight savings for the absolute time. The values not used in the computation are recomputed for the resulting absolute time. All out of range values are wrapped. For example, December 32 will roll over to Jan 1 of the following year.
Tmfmtinstall installs a time format specifier %τ. The time format
behaves as in tmfmt |
EXAMPLES
All examples assume tmfmtinstall has been called.
Get the current date in the local timezone, UTC, and US_Pacific
time. Print it using the default format.
|
BUGS
Checking the timezone name against the local timezone is a dirty
hack. The same date string may parse differently for people in
different timezones. Tmparse and ctime don't mix. Tmparse preserves timezone names, including names like '+0200'. Ctime expects timezone names to be exactly three characters. Use the %τ format character instead of ctime. The timezone information that we ship is out of date. The Plan 9 timezone format has no way to express leap seconds.
We provide no way to manipulate timezones. |