Proposal for new ISO C 9x time API

[Markus Kuhn]

Ken Pizzini wrote on 1998-10-07 07:09 UTC:
> When I read the proposal I presumed that only TIME_UTC values
> should be passed to strfxtime() (whether the result of the
> appropriate xtime_get() or xtime_conv() call).

That is correct if you want strfxtime() to convert to some local time,
because the timezone_t objects convert from UTC to a local time and
therefore have to be fed with UTC and not with TAI if you want correct
local times. The same applies to xtime_breakup().

There is however one exception: If you have a TAI timestamp and what to
print it as a TAI timestamp, then you just pass to strfxtime the TAI
timestamp and specify NULL as the time zone. NULL means that the output
shall be a "UTC time", but since the relationship between xtime and
broken-down time is identical for both TAI and UTC, you will get the
correct TAI output as well with NULL. Therefore, strfxtime can also be
passed TAI timestamps with a NULL timezone_t in order to print correct
TAI timestamps and strftime() does not even have to know about that this
is a TAI timestamp. Note that the semantics of (timezone_t *) NULL is
the only timezone whose semantics is precisely specified in the proposal
by providing example xtime_make() C code (not yet completed). The
semantics of the other time zones is only specified indirectly in that
they should be handled in analogy to how UTC broken-down time is
handled, plus some (still to be added) remarks about the purpose of
tm_isdst. This will allow for all sorts of bizarre timezone definitions,
including (of course hypothetical) timezones based on UT1 (if an
internal UT1 table is available), or even timezones on other planets,
just to document the flexibility of the API.

Example:

if (xtime_get(&t, TIME_UTC) & TIME_UTC)
  strfxtime(..., "%H:%M:%S UTC", &t, NULL);

if (xtime_get(&t, TIME_TAI) & TIME_TAI)
  strfxtime(..., "%H:%M:%S TAI", &t, NULL);

I think this is a much nicer embedding of both UTC and TAI into the
scheme of things than having to pass on to xtime_breakup(),
xtime_make(), and strfxtime() a separate parameter that tells whether we
are using a UTC or a TAI timestamp.

> I now feel
> that the failure to explictly state that strfxtime()'s xtime
> argument should be a TIME_UTC value is a bug in the documentation
> of the strfxtime() function.

I thought it is very clearly stated in the definition of what a
timezone_t object is doing that it converts between UTC xtime timestamps
and some broken-down local time, and the xtime_breakup(), xtime_make(),
and strfxtime() use the timezone_t objects exactly this way. I will add
an informal note to strfxtime() to remind the reader about this
definition.

Just explicitely stating "that strfxtime()'s xtime argument should be a
TIME_UTC value" would not be accurate, because as you see above, with
a (timezone_t *) NULL parameter, passing TIME_TAI values also makes
a lot sense.

Markus

-- 
Markus G. Kuhn, Security Group, Computer Lab, Cambridge University, UK
email: mkuhn at acm.org,  home page: <http://www.cl.cam.ac.uk/~mgk25/>