[erlang-questions] calendar:local_time_to_universal_time_dst/1 - what this is for?

[Kenji Rikitake]

I found a bug when I was playing around with mochiweb on R12B4.  It's
not mochiweb's bug, but rather the Erlang/OTP time function bug.  See

http://www.erlang.org/pipermail/erlang-bugs/2008-September/000994.html

if you don't want to read ahead. (Summary: the "universaltime" in
Erlang/OTP was not really the one if the wall clock is aware of leap
seconds.)

I am writing this to ask a set of question about the following issue I
was thinking last night.

When I tried to perform "gmake test" on one of my systems (yeah, it's
FreeBSD, so GNU make is gmake), I faced a condition (in
mochiweb_cookies:test/0) that httpd_util:rfc1123_date/1 returned a []
(null list).  I further tracked it down and found
calendar:local_time_to_universal_time_dst/1 (quoted below) was the
source of the null list.  (I found that
erlang:universaltime_to_localtime/1 and the corresponding C function
univ_to_local() in erts/emulator/beam/erl_time_sup.c caused the problem,
by NOT properly handling leap-second correction.)

I was wondering what this function
calendar:local_time_to_universal_time_dst/1 was for and how this
conversion function to be used.  I have the following questions:

* Why you need to double-check the whole time difference?

* In what situation should the results of this function really matter?

* What kind of action should an application program take if this
  function returns a list of two possible UTC values for one DST
  localtime value?

Maybe I'm perplexed just because I've never tried hard to code DST
handling programs (Japan has no DST since 1950s).

BTW I'd like to say thanks to mochiweb developers for making me aware of
these rather non-trivial issues.

Regards,
Kenji Rikitake

%% quoted from lib/stdlib-1.15.4/src/calendar.erl
%% begin

-spec local_time_to_universal_time_dst(t_datetime1970()) -> [t_datetime1970()].
local_time_to_universal_time_dst(DateTime) ->
    UtDst = erlang:localtime_to_universaltime(DateTime, true),
    Ut    = erlang:localtime_to_universaltime(DateTime, false),
    %% Reverse check the universal times
    LtDst = erlang:universaltime_to_localtime(UtDst),
    Lt    = erlang:universaltime_to_localtime(Ut),
    %% Return the valid universal times
    case {LtDst,Lt} of
	{DateTime,DateTime} when UtDst =/= Ut ->
	    [UtDst,Ut];
	{DateTime,_} ->
	    [UtDst];
	{_,DateTime} ->
	    [Ut];
	{_,_} ->
	    []
    end.

%% end