Time with Time-zone Programming on Linux

1. Time format and examples

  string-time : "2001-2-3 04:05:06 +0700"

  struct-time : struct tm {
                  tm_sec      = 6,
                  tm_min      = 5,
                  tm_hour     = 4,
                  tm_mday     = 3,
                  tm_mon      = 1,
                  tm_year     = 101,
                  tm_wday     = ?,
                  tm_yday     = ?,
                  tm_isdst    = ?,
                  __tm_gmtoff = 25200,  /* = 7 * 3600 */
                  __tm_zone   = 0x??? "???"
                }

  long-time  : 12345678    /* seconds elapsed since 1970.1.1 0:0:0 */


2. For communication: string-time is best, as RFC 822 defined.
   For time comparing and save into DB, long-time is best.
 
   struct-time, used between string-time and long-time, and for time changing.


3. long-time lost the time zone info.


4. Standard-time, Remote-time and Local-time

  Standard-time: UTC time (former GMT time), offset = 0

  Local-time: Local linux time and time zone, offset = +/-xxxx

  Reomote-time: time and time-zone on remote site in communication, offset = +/-yyyy


5. Glibc (library) is weak on time functions.

  strptime()     : string-time to struct-time, with user time zone (only for 2.6.x).
  strftime()     : struct-time to string-time, with user time zone.

  timegm()       : struct-time to long-time, lost time zone.
  mktime()       : struct-time to long-time, with local time zone.

  gmtime_r()     : long-time to struct-time, no time zone.
  localtime_r()  : long-time to struct-time, with local time zone.

  time()         : long-time, lost local time zone.
  timezone       : local time zone offset

6. Principle of time programming.

6.1 Save long-time into DB. This long-time is standard time (UTC time).
    For the parameters of function, use UTC long-time as the time format.

6.2 For incoming data, containing string-time, call strptime() to convert to
    struct-time, and keep time zone in a independent variable (for Linux 2.4.x, get  
    the time zone from the string by yourself), then call timegm() to convert to
    long-time, then minus time-zone in the variable, to get UTC long-time.

6.3 For outgoing data, as a UTC long-time, if the time zone is local, call
    localtime_r() to convert to a struct-time, with time zone (local), then
    call strftime() to get a string-time, with time zone (local).

6.4 For outgoing data, as a UTC long-time, if the time zone is user, before this
    should somewhere a variable saved the offset, add the time zone offset to the
    long-time, then call gmtime_r() to get a struct-time, no time zone, then set
    the tm_gmtoff of struct time with the offset in the variable, then call
    strftime() to get a string-time, with time zone (user).
    
6.5 For local config file, containing string-time, should save the time with
    time zone, for getting correct time after time zone changed. Otherwise,
    always save UTC long-time or UTC string-time in config file.