Theory revision 1.1
1@(#)Theory 7.2 2 3These time and date functions are much like the System V Release 2.0 (SVR2) 4time and date functions; there are a few additions and changes to extend 5the 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 functions can account for leap seconds, thanks to Bradley White 35 (bww@k.cs.cmu.edu). 36 37These are the changes that have been made to the SVR2 functions: 38 39* The "TZ" environment variable is used in generating the name of a file 40 from which time zone information is read (or is interpreted a la 41 POSIX); "TZ" is no longer constrained to be a three-letter time zone 42 name followed by a number of hours and an optional three-letter 43 daylight time zone name. The daylight saving time rules to be used 44 for a particular time zone are encoded in the time zone file; 45 the format of the file allows U.S., Australian, and other rules to be 46 encoded, and allows for situations where more than two time zone 47 abbreviations are used. 48 49 It was recognized that allowing the "TZ" environment variable to 50 take on values such as "US/Eastern" might cause "old" programs 51 (that expect "TZ" to have a certain form) to operate incorrectly; 52 consideration was given to using some other environment variable 53 (for example, "TIMEZONE") to hold the string used to generate the 54 time zone information file name. In the end, however, it was decided 55 to continue using "TZ": it is widely used for time zone purposes; 56 separately maintaining both "TZ" and "TIMEZONE" seemed a nuisance; 57 and systems where "new" forms of "TZ" might cause problems can simply 58 use TZ values such as "EST5EDT" which can be used both by 59 "new" programs (a la POSIX) and "old" programs (as zone names and 60 offsets). 61 62* To handle places where more than two time zone abbreviations are used, 63 the functions "localtime" and "gmtime" set tzname[tmp->tm_isdst] 64 (where "tmp" is the value the function returns) to the time zone 65 abbreviation to be used. This differs from SVR2, where the elements 66 of tzname are only changed as a result of calls to tzset. 67 68* Since the "TZ" environment variable can now be used to control time 69 conversion, the "daylight" and "timezone" variables are no longer 70 needed or supported. (You can use a compile-time option to cause 71 these variables to be defined and to be set by "tzset"; however, their 72 values will not be used by "localtime.") 73 74* The "localtime" function has been set up to deliver correct results 75 for near-minimum or near-maximum time_t values. (A comment in the 76 source code tells how to get compatibly wrong results). 77 78* A function "tzsetwall" has been added to arrange for the system's 79 best approximation to local wall clock time to be delivered by 80 subsequent calls to "localtime." Source code for portable 81 applications that "must" run on local wall clock time should call 82 "tzsetwall();" if such code is moved to "old" systems that don't provide 83 tzsetwall, you won't be able to generate an executable program. 84 (These time zone functions also arrange for local wall clock time to be 85 used if tzset is called--directly or indirectly--and there's no "TZ" 86 environment variable; portable applications should not, however, rely 87 on this behavior since it's not the way SVR2 systems behave.) 88 89Points of interest to folks with Version 7 or BSD systems: 90 91* The BSD "timezone" function is not present in this package; 92 it's impossible to reliably map timezone's arguments (a "minutes west 93 of GMT" value and a "daylight saving time in effect" flag) to a 94 time zone abbreviation, and we refuse to guess. 95 Programs that in the past used the timezone function may now examine 96 tzname[localtime(&clock)->tm_isdst] to learn the correct time 97 zone abbreviation to use. Alternatively, use localtime(&clock)->tm_zone 98 if this has been enabled. 99 100* The BSD gettimeofday function is not used in this package; 101 this lets users control the time zone used in doing time conversions. 102 Users who don't try to control things (that is, users who do not set 103 the environment variable TZ) get the time conversion specified in the 104 file "/etc/zoneinfo/localtime"; see the time zone compiler writeup for 105 information on how to initialize this file. 106 107The functions that are conditionally compiled if STD_INSPIRED is defined should, 108at this point, be looked on primarily as food for thought. They are not in 109any sense "standard compatible"--some are not, in fact, specified in *any* 110standard. They do, however, represent responses of various authors to 111standardization proposals. 112 113Other time conversion proposals, in particular the one developed by folks at 114Hewlett Packard, offer a wider selection of functions that provide capabilities 115beyond those provided here. The absence of such functions from this package 116is not meant to discourage the development, standardization, or use of such 117functions. Rather, their absence reflects the decision to make this package 118close to SVR2 (with the exceptions outlined above) to ensure its broad 119acceptability. If more powerful time conversion functions can be standardized, 120so much the better. 121