Return to Theory CVS log

Up to [CSRG BSD Unix] / 43BSDTahoe / etc / tzone

Annotation of 43BSDTahoe/etc/tzone/Theory, revision 1.1

1.1     ! root        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.

This archive runs on limited infrastructure. Preserving old code on modern bandwidth. Automated agents are requested to crawl responsibly.