initial import of NetBSD tree

1 files changed, 120 insertions, 0 deletions

diff --git a/lib/libc/time/Theory b/lib/libc/time/Theory
new file mode 100644
index 00000000000..93a07c0f7da
--- /dev/null
+++ b/lib/libc/time/Theory
@@ -0,0 +1,120 @@
+@(#)Theory	7.2
+
+These time and date functions are much like the System V Release 2.0 (SVR2)
+time and date functions; there are a few additions and changes to extend
+the usefulness of the SVR2 functions:
+
+*	In SVR2, time display in a process is controlled by the environment
+	variable TZ, which "must be a three-letter time zone name, followed
+	by a number representing the difference between local time and
+	Greenwich Mean Time in hours, followed by an optional three-letter
+	name for a daylight time zone;" when the optional daylight time zone is
+	present, "standard U.S.A. Daylight Savings Time conversion is applied."
+	This means that SVR2 can't deal with other (for example, Australian)
+	daylight savings time rules, or situations where more than two
+	time zone abbreviations are used in an area.
+
+*	In SVR2, time conversion information is compiled into each program
+	that does time conversion.  This means that when time conversion
+	rules change (as in the United States in 1987), all programs that
+	do time conversion must be recompiled to ensure proper results.
+
+*	In SVR2, time conversion fails for near-minimum or near-maximum
+	time_t values when doing conversions for places that don't use GMT.
+
+*	In SVR2, there's no tamper-proof way for a process to learn the
+	system's best idea of local wall clock.  (This is important for
+	applications that an administrator wants used only at certain times--
+	without regard to whether the user has fiddled the "TZ" environment
+	variable.  While an administrator can "do everything in GMT" to get
+	around the problem, doing so is inconvenient and precludes handling
+	daylight savings time shifts--as might be required to limit phone
+	calls to off-peak hours.)
+
+*	These functions can account for leap seconds, thanks to Bradley White
+	(bww@k.cs.cmu.edu).
+
+These are the changes that have been made to the SVR2 functions:
+
+*	The "TZ" environment variable is used in generating the name of a file
+	from which time zone information is read (or is interpreted a la
+	POSIX); "TZ" is no longer constrained to be a three-letter time zone
+	name followed by a number of hours and an optional three-letter
+	daylight time zone name.  The daylight saving time rules to be used
+	for a particular time zone are encoded in the time zone file;
+	the format of the file allows U.S., Australian, and other rules to be
+	encoded, and allows for situations where more than two time zone
+	abbreviations are used.
+
+	It was recognized that allowing the "TZ" environment variable to
+	take on values such as "US/Eastern" might cause "old" programs
+	(that expect "TZ" to have a certain form) to operate incorrectly;
+	consideration was given to using some other environment variable
+	(for example, "TIMEZONE") to hold the string used to generate the
+	time zone information file name.  In the end, however, it was decided
+	to continue using "TZ":  it is widely used for time zone purposes;
+	separately maintaining both "TZ" and "TIMEZONE" seemed a nuisance;
+	and systems where "new" forms of "TZ" might cause problems can simply
+	use TZ values such as "EST5EDT" which can be used both by
+	"new" programs (a la POSIX) and "old" programs (as zone names and
+	offsets).
+
+*	To handle places where more than two time zone abbreviations are used,
+	the functions "localtime" and "gmtime" set tzname[tmp->tm_isdst]
+	(where "tmp" is the value the function returns) to the time zone
+	abbreviation to be used.  This differs from SVR2, where the elements
+	of tzname are only changed as a result of calls to tzset.
+
+*	Since the "TZ" environment variable can now be used to control time
+	conversion, the "daylight" and "timezone" variables are no longer
+	needed or supported.  (You can use a compile-time option to cause
+	these variables to be defined and to be set by "tzset"; however, their
+	values will not be used by "localtime.")
+
+*	The "localtime" function has been set up to deliver correct results
+	for near-minimum or near-maximum time_t values.  (A comment in the
+	source code tells how to get compatibly wrong results).
+
+*	A function "tzsetwall" has been added to arrange for the system's
+	best approximation to local wall clock time to be delivered by
+	subsequent calls to "localtime."  Source code for portable
+	applications that "must" run on local wall clock time should call
+	"tzsetwall();" if such code is moved to "old" systems that don't provide
+	tzsetwall, you won't be able to generate an executable program.
+	(These time zone functions also arrange for local wall clock time to be
+	used if tzset is called--directly or indirectly--and there's no "TZ"
+	environment variable; portable applications should not, however, rely
+	on this behavior since it's not the way SVR2 systems behave.)
+
+Points of interest to folks with Version 7 or BSD systems:
+
+*	The BSD "timezone" function is not present in this package;
+	it's impossible to reliably map timezone's arguments (a "minutes west
+	of GMT" value and a "daylight saving time in effect" flag) to a
+	time zone abbreviation, and we refuse to guess.
+	Programs that in the past used the timezone function may now examine
+	tzname[localtime(&clock)->tm_isdst] to learn the correct time
+	zone abbreviation to use.  Alternatively, use localtime(&clock)->tm_zone
+	if this has been enabled.
+
+*	The BSD gettimeofday function is not used in this package;
+	this lets users control the time zone used in doing time conversions.
+	Users who don't try to control things (that is, users who do not set
+	the environment variable TZ) get the time conversion specified in the
+	file "/etc/zoneinfo/localtime"; see the time zone compiler writeup for
+	information on how to initialize this file.
+
+The functions that are conditionally compiled if STD_INSPIRED is defined should,
+at this point, be looked on primarily as food for thought.  They are not in
+any sense "standard compatible"--some are not, in fact, specified in *any*
+standard.  They do, however, represent responses of various authors to
+standardization proposals.
+
+Other time conversion proposals, in particular the one developed by folks at
+Hewlett Packard, offer a wider selection of functions that provide capabilities
+beyond those provided here.  The absence of such functions from this package
+is not meant to discourage the development, standardization, or use of such
+functions.  Rather, their absence reflects the decision to make this package
+close to SVR2 (with the exceptions outlined above) to ensure its broad
+acceptability.  If more powerful time conversion functions can be standardized,
+so much the better.