time.h design issues

[Paul Eggert]

   Date: Fri, 27 Aug 1999 19:55:35 -0700
   From: Scott Harrington <seh4 at ix.netcom.com>

   I for one would favor a portable standalone implementation of xtime,
   timezone_t, etc. a la Kuhn & Eggert.

I'd love to see one too.  :-) Unfortunately some of it would have to
be system-dependent in a tricky way.  I hope that most of it could be
portable, though.

   Date: 28 Aug 1999 00:12:07 -0000
   From: "D. J. Bernstein" <djb at cr.yp.to>

   > http://www.twinsun.com/tz/timeapi.html

   I don't understand what problems you're trying to solve here.

Kuhn and I are trying to specify an improved API for time handling.
As discussed in http://www.cl.cam.ac.uk/~mgk25/c-time/ section 2,
the ISO C API is pretty lame.  The decision about which features should
make it into a new API are a delicate judgment call, of course.  I've
tried to synthesize the best ideas of Kuhn with some of your ideas,
plus others.  Of course there's room for improvement; it's still just
a draft.

   Time libraries should be designed to support the features that real
   programs need. For example:

      * Benchmarking tools need to measure differences in real time.
	Consider the gettimeofday() function.

Unfortunately, gettimeofday doesn't measure real time, at least not on
my Solaris box.  It measures the system's notion of the current time,
and this can jump when root adjusts the clock.

Kuhn's proposal and mine both let you measure real time even if root
adjusts the clock.  It's xtime_get(TIME_MONOTONIC|TIME_NOW) in my
proposal.

      * Networking tools need to schedule events at moments in real time:
	e.g., send this packet 0.2 seconds after that one. Consider the
	select() and poll() functions.

If you want a simple delay, then xtime_delay(N) will do; if you want
some other primitive, e.g. wait for input on a file descriptor with a
time out, then I'm afraid it's out of scope for a pure time API.

      * Clock programs need to know the current time in the local time
	zone. Consider the time() and localtime() functions.

That corresponds to xt=xtime_get(TIME_SYSTEM|TIME_NOW) and
xtime_breakup(&tm, xt, tz), where tz is the output of a previous call
to tz_prep.  (Perhaps xtime_breakup should default to local time
instead of UTC; that would simplify things a bit in the common case.)

      * Mail readers, given a list of civil times from various time zones,
	need to sort the times into numerical order. Consider the mktime()
	function.

Of course mktime can't do that, since it doesn't handle time zones.
But xtime_make should be able to do it, since it accepts an object
describing the clock and time zone in question.

      * Calendar programs need to know tomorrow's date, the number of days
	until next month, etc.

I hadn't intended for the improved time API to address calendrical
issues, but if there's a demand for this it could be added.

      * Convert seconds-since-epoch to a civil time in the local time zone.
      * Convert any civil time to seconds-since-epoch.

These primitives are in both Kuhn's and my proposals.

      * Convert days-since-epoch to a calendar date.
      * Convert a calendar date to days-since-epoch.

These aren't.  Perhaps there should be an xdate_breakup and
xdate_make.  A more elegant possibility is to add a separate clock
type or option for a clock that ticks once per day; one could then use
xtime_breakup and xtime_make for calendar conversions.  (Similarly for
minutes, months, weeks, etc.)  Let me think about it a bit more.

http://www.twinsun.com/tz/timeapi.html adds the following primitives
to your list.

      * Create a time zone object from a time zone specification.
      * Interrogate clock features, e.g. their resolution.
      * Interrogate time zone features, e.g. the next DST transition.
      * Fancy formatting, e.g. to get ISO date strings.
      * Delay for a specified interval.
      * Different kinds of clocks (e.g. TAI vs UTC vis realtime).
      * Conversion among these clocks, and time_t.
      * Report errors, e.g. clock unavailable.

To some extent this spec is overkill; I'd certainly like to see a
smaller one.  (In my defense, I started from Kuhn's spec, which has
even more goodies.)  However, we must have the ability to handle
multiple time zones simultaneously (e.g. the first additional
primitive mentioned above).  Multiple time zones are what started this
thread, and many apps need them.