home *** CD-ROM | disk | FTP | other *** search
/ InfoMagic Internet Tools 1993 July / Internet Tools.iso / RockRidge / mail / mmdf / libz / Theory < prev    next >
Encoding:
Text File  |  1989-09-10  |  6.9 KB  |  131 lines
  1. @(#)Theory    3.1
  2.  
  3. These time and date functions are much like the System V Release 2.0 (SVR2)
  4. time and date functions; there are a few additions and changes to extend
  5. the usefulness of the SVR2 functions:
  6.  
  7. *    In SVR2, time display in a process is controlled by the environment
  8.     variable TZ, which "must be a three-letter time zone name, followed
  9.     by a number representing the difference between local time and
  10.     Greenwich Mean Time in hours, followed by an optional three-letter
  11.     name for a daylight time zone;" when the optional daylight time zone is
  12.     present, "standard U.S.A. Daylight Savings Time conversion is applied."
  13.     This means that SVR2 can't deal with other (for example, Australian) 
  14.     daylight savings time rules, or situations where more than two
  15.     time zone abbreviations are used in an area.
  16.  
  17. *    In SVR2, time conversion information is compiled into each program
  18.     that does time conversion.  This means that when time conversion
  19.     rules change (as in the United States in 1987), all programs that
  20.     do time conversion must be recompiled to ensure proper results.
  21.  
  22. *    In SVR2, time conversion fails for near-minimum or near-maximum
  23.     time_t values when doing conversions for places that don't use GMT.
  24.  
  25. *    In SVR2, there's no tamper-proof way for a process to learn the
  26.     system's best idea of local wall clock.  (This is important for 
  27.     applications that an administrator wants used only at certain times--
  28.     without regard to whether the user has fiddled the "TZ" environment
  29.     variable.  While an administrator can "do everything in GMT" to get
  30.     around the problem, doing so is inconvenient and precludes handling
  31.     daylight savings time shifts--as might be required to limit phone
  32.     calls to off-peak hours.)
  33.  
  34. These are the changes that have been made to the SVR2 functions:
  35.  
  36. *    The "TZ" environment variable is used in generating the name of a file
  37.     from which time zone information is read; "TZ" is no longer constrained
  38.     to be a three-letter time zone name followed by a number of hours and
  39.     an optional three-letter daylight time zone name.  The daylight saving
  40.     time rules to be used for a particular time zone are encoded in the
  41.     time zone file; the format of the file allows U.S., Australian, and
  42.     other rules to be encoded, and allows for situations where more than
  43.     two time zone abbreviations are used.
  44.  
  45.     It was recognized that allowing the "TZ" environment variable to
  46.     take on values such as "US/Eastern" might cause "old" programs
  47.     (that expect "TZ" to have a certain form) to operate incorrectly;
  48.     consideration was given to using some other environment variable
  49.     (for example, "TIMEZONE") to hold the string used to generate the
  50.     time zone information file name.  In the end, however, it was decided
  51.     to continue using "TZ":  it is widely used for time zone purposes;
  52.     separately maintaining both "TZ" and "TIMEZONE" seemed a nuisance;
  53.     and systems where "new" forms of "TZ" might cause problems can simply
  54.     give time zone files names such as "EST5EDT" which can be used both by
  55.     "new" programs (as file names) and "old" programs (as zone names and
  56.     offsets).
  57.  
  58. *    To handle places where more than two time zone abbreviations are used,
  59.     the functions "localtime" and "gmtime" set tzname[tmp->tm_isdst]
  60.     (where "tmp" is the value the function returns) to the time zone
  61.     abbreviation to be used.  This differs from SVR2, where the elements
  62.     of tzname are only changed as a result of calls to tzset.
  63.  
  64. *    Since the "TZ" environment variable can now be used to control time
  65.     conversion, the "daylight" and "timezone" variables are no longer
  66.     needed or supported.  (You can use a compile-time option to cause
  67.     these variables to be defined and to be set by "tzset"; however, their
  68.     values will not be used by "localtime.")
  69.  
  70. *    The "localtime" function has been set up to deliver correct results
  71.     for near-minimum or near-maximum time_t values.  (A comment in the
  72.     source code tells how to get compatibly wrong results).
  73.  
  74. *    A function "tzsetwall" has been added to arrange for the system's
  75.     best approximation to local wall clock time to be delivered by
  76.     subsequent calls to "localtime."  Source code for portable
  77.     applications that "must" run on local wall clock time should call
  78.     "tzsetwall();" if such code is moved to "old" systems that don't provide
  79.     tzsetwall, you won't be able to generate an executable program.
  80.     (These time zone functions also arrange for local wall clock time to be
  81.     used if tzset is called--directly or indirectly--and there's no "TZ"
  82.     environment variable; portable applications should not, however, rely
  83.     on this behavior since it's not the way SVR2 systems behave.)
  84.  
  85. Points of interest to folks with Version 7 or BSD systems:
  86.  
  87. *    The BSD "timezone" function is not present in this package;
  88.     it's impossible to reliably map timezone's arguments (a "minutes west
  89.     of GMT" value and a "daylight saving time in effect" flag) to a
  90.     time zone abbreviation, and we refuse to guess. 
  91.     Programs that in the past used the timezone function may now examine
  92.     tzname[localtime(&clock)->tm_isdst] to learn the correct time
  93.     zone abbreviation to use.  Alternatively, use localtime(&clock)->tm_zone
  94.     if this has been enabled.
  95.  
  96. *    The BSD gettimeofday function is not used in this package;
  97.     this lets users control the time zone used in doing time conversions.
  98.     Users who don't try to control things (that is, users who do not set
  99.     the environment variable TZ) get the time conversion specified in the
  100.     file "/etc/zoneinfo/localtime"; see the time zone compiler writeup for
  101.     information on how to initialize this file.
  102.  
  103. *    The BSD "dysize" function is only included if the preprocessor symbol
  104.     BSD_COMPAT is defined.  For a year y, the BSD code returns the value
  105.        ((y % 4) == 0) : 366 : 365
  106.     while this code returns the value
  107.        (((y) % 4) == 0 && ((y) % 100) != 0 || ((y) % 400) == 0) ? 366 : 365
  108.     There's a comment in the code telling how to get the BSD value.
  109.  
  110. The functions that are conditionally compiled if STD_INSPIRED is defined should,
  111. at this point, be looked on primarily as food for thought.  They are not in
  112. any sense "standard compatible"--some are not, in fact, specified in *any*
  113. standard.  They do, however, represent responses of various authors to
  114. standardization proposals.
  115.  
  116. Other time conversion proposals, in particular the one developed by folks at
  117. Hewlett Packard, offer a wider selection of functions that provide capabilities
  118. beyond those provided here.  The absence of such functions from this package
  119. is not meant to discourage the development, standardization, or use of such
  120. functions.  Rather, their absence reflects the decision to make this package
  121. close to SVR2 (with the exceptions outlined above) to ensure its broad
  122. acceptability.  If more powerful time conversion functions can be standardized,
  123. so much the better.
  124.  
  125. It's probably not wise to standardize everything in this package.
  126. While the command
  127.     nroff -man newctime.3
  128. produces a document that describes this package, the command
  129.     nroff -man -rX3J11 newctime.3
  130. produces a document that describes the "standardizable" parts.
  131.