POSE proposal for TZ

Mon Feb 24 03:19:07 AEST 1986

From: seismo!elsie!ado
Date: Fri, 21 Feb 86 22:48:58 EST

# To unundle, sh this file
echo README 1>&2
cat >README <<'End of README'
@(#)README	1.4

The shell archive of which this file is a part contains man pages for functions
and a file format designed to deal with Daylight Savings Time variations.

The basic idea is to have a system-wide directory that contains binary files
describing time zone rules; functions such as "localtime" could read such
files before doing time conversions.

A manual page for a "time zone compiler" that turns text-file descriptions of
time zone rules into binary files is also included, as is a sample input file
for the compiler.  These would, of course, not be part of the standard;
they are included here only to show that the binary files that would be used
under this scheme can be readily created.

Source code for these functions and for the time zone compiler are available
from seismo!elsie!ado, the person to whom to direct comments (with, perhaps,
carbon copes to cbosgd!mark and seismo!philabs!linus!encore!necis!geo,
who are responsible for any good ideas that show up here).
End of README
echo settz.3 1>&2
cat >settz.3 <<'End of settz.3'
.TH SETTZ 3 
.SH NAME
settz, newctime, newlocaltime \-  convert date and time to ASCII
.SH SYNOPSIS
.nf
.B settz(zonename)
.B char *zonename;
.PP
.B char *newctime(clock)
.B long *clock;
.PP
.B
#include "time.h"
.PP
.B struct tm *newlocaltime(clock)
.B long *clock;
.PP
.B char *tz_abbr;
.SH DESCRIPTION
.I Settz
sets time zone information used by
.I newctime
and
.IR newlocaltime .
If
.I zonename
begins with a slash,
it is used as the absolute pathname of the
.IR tzfile (5)-format
file from which to read the time zone information;
if
.I zonename
begins with some other character,
it is used as a pathname relative to the standard time zone information
directory.  A call of the form
.ti +.5i
.B
settz("")
.br
causes built-in information about GMT to be used; a call of the form
.ti +.5i
.B
settz((char *) 0)
.br
is treated as if it were a call of the form
.ti +.5i
.B
settz("localtime")
.PP
.I Newlocaltime
has the same argument and return value as
.IR localtime .
If
.I newlocaltime
is called before
.I settz
is called,
.I newlocaltime
calls
.I settz
with the value returned by
.B
getenv("TZ").
.I Newlocaltime
sets
tz_abbr
to a pointer to an 
ASCII string that's the time zone abbreviation to be used with
.IR newlocaltime 's
return value.
.PP
.I Newctime
returns a pointer to a string of the form
.ti +.5i
Sat Feb 15 15:45:51 1986 EST\\n\\0
.br
where the last (variable-width) field is the time zone abbreviation.
.SH DIAGNOSTICS
.I Settz
returns zero if all seems well; it returns negative one otherwise
(and sets things up so that its built-in information about GMT is used).
.SH FILES
/etc/tzdir	standard time zone information directory
.SH "SEE ALSO"
ctime(3), getenv(3), tzfile(5)
.. @(#)settz.3	1.3
End of settz.3
echo tzfile.5 1>&2
cat >tzfile.5 <<'End of tzfile.5'
.TH TZFILE 5
.SH NAME
tzfile \- time zone information
.SH SYNOPSIS
.B
#include "tzfile.h"
.SH DESCRIPTION
The time zone information files used by
.IR settz (3)
and
.IR newlocaltime (3)
have the format of the
.I tzinfo
structure described in the include file
.B 
"tzfile.h":
.sp
.nf
.in +.5i
struct tzinfo {
	int	tz_timecnt;
	long	tz_times[TZ_MAX_TIMES];
	char	tz_types[TZ_MAX_TIMES];
	struct dsinfo {
		long	ds_gmtoff;
		char	ds_abbr[TZ_ABBR_LEN+1];
		char	ds_isdst;
	}	tz_dsinfo[TZ_MAX_TYPES];
};
.fi
.PP
The
.B tz_timecnt
field tells how many of the
.B tz_times
and
.B tz_types
stored in the file are meaningful.
Each of the meaningful
.B tz_times
entries is a starting time (as returned by
.IR time (2));
the same-indexed
.B tz_types
entry is the index of the
.B tz_dsinfo
array element that tells about how "local time" is generated starting at that
time.
For a file to be used by
.IR settz ,
its
.B tz_times
entries must be sorted in ascending order.
.PP
In the
.B tz_dsinfo
structures,
.B ds_gmtoff
gives the number of seconds that should be added to GMT;
.B ds_abbr
is the ASCII-NUL-terminated string used as the time zone abbreviation;
and
.B
ds_isdst
tells whether
.B
tm_isdst
should be set by
.IR newlocaltime (3).
.PP
.I Newlocaltime
uses the first element of
.B tz_dsinfo
if either
.B tz_timecnt
is zero or
.IR newlocaltime 's
argument is less than
.BR tz_times[0] .
.SH SEE ALSO
settz(3)
.. @(#)tzfile.5	1.4
End of tzfile.5
echo tzcomp.8 1>&2
cat >tzcomp.8 <<'End of tzcomp.8'
.TH TZCOMP 8
.SH NAME
tzcomp \- time zone compiler
.SH SYNOPSIS
.B tzcomp
[
.B \-d
directory ] filename ...
.SH DESCRIPTION
.I Tzcomp
reads text from the file(s) named on the command line
and creates the time zone information files specified in this input.
If a
.I filename
is
.BR ` - ',
the standard input is read.
.PP
This option is available:
.TP
.B \-d directory
Create time zone information files in the named directory rather than
in the standard directory named below.
.PP
A sharp characters (#) in the input introduces a comment which extends to
the end of the line the sharp character appears on.
Any line which is blank (after comment stripping) is ignored.
Non-blank lines are expected to be of one of three
types:  rule lines, zone lines, and link lines.
.PP
A rule line has the form
.nf
.B
.ti +.5i
.ta \w'Rule 'u +\w'MostNA 'u +\w'FROM 'u +\w'1973 'u +\w'TYPE 'u +\w'Apr 'u +\w'lastSun 'u +\w'2:00 'u +\w'SAVE 'u
.sp
Rule	NAME	FROM	TO	TYPE	IN	ON	AT	SAVE	LETTER/S
.sp
For example:
.ti +.5i
.sp
Rule	MostNA	1969	1973	-	Apr	lastSun	2:00	1:00	D
.sp
.fi
The fields that make up a rule line are:
.TP
.B NAME
Gives the (arbitrary) name of the set of rules this rule is part of.
.TP
.B FROM
Gives the first year in which the rule applies.
.TP
.B TO
Gives the last year in which the rule applies.
The word
.RB ` only '
may be used to repeat the value of the
.B
FROM
field.
.TP
.B TYPE
Gives the type of year in which the year applies.  If
.B TYPE
is
.B
"-"
then the rule is taken to apply in all years between
.B FROM
and
.B TO
inclusive.
If
.B TYPE
is something else, then the command
.B
.ti +.5i
years from to type
.br
is executed with arguments
.IR from ,
.IR to ,
and
.IR type
taken from the rule line; the rule is taken to apply only in those years
printed by the
.I years
command.

The distributed
.I years
command is a shell script that can handle year types
.B uspres
(United States presidential election years)
and
.B nonpres
(all other years);
other year types may be added by changing the script.
.TP
.B IN
Names the month in which the rule takes effect.  Month names may be
abbreviated.
.TP
.B ON
Gives the day on which the rule takes effect.
Recognized forms include:
.nf
.in +.5i
.sp
.ta \w'lastSun  'u
5	the fifth of the month
lastSun	the last Sunday in the month
lastMon	the last Monday in the month
Sun>=8	first Sunday on or after the eighth
Sun<=25	last Sunday on or before the 25th
.fi
.in -.5i
.sp
Names of days of the week may be abbreviated or spelled out in full.
Note that there must be no spaces within the
.B ON
field 
(or within any other field).
.TP
.B AT
Gives the time of day at which the rule takes affect.
Recognized forms include:
.nf
.in +.5i
.sp
.ta \w'1:28:13  'u
2	time in hours
2:00	time in hours and minutes
15:00	24-hour format time (for times after noon)
1:28:14	time in hours, minutes, and seconds
.fi
.in -.5i
.sp
.TP
.B SAVE
Gives the amount of time to be added to local standard time when the rule is in
effect.  This field has the same format as the
.B AT
field.
.TP
.B LETTER/S
Gives the "variable part" (for example, the 'S' or 'D' in "EST" or "EDT")
of time zone abbreviations to be used when this rule is in effect.
If this field is
.B
"-",
the variable part is null.
.PP
A zone line has the form
.sp
.nf
.ti +.5i
.ta \w'Zone 'u +\w'Eastern 'u +\w'GMTOFF 'u +\w'MostNA 'u
Zone	NAME	GMTOFF	RULES	FORMAT
.sp
For example:
.sp
.ti +.5i
Zone	Eastern	-5:00	MostNA	E%sT
.sp
.fi
The fields that make up a zone line are:
.TP
.B NAME
The name of the time zone.
This is the name used in creating the time zone information file for the zone.
.TP
.B GMTOFF
The amount of time to add to GMT to get standard time in this zone.
This field has the same format as the
.B AT
and
.B SAVE
fields of rule lines;
begin the field with a minus sign if time must be subtracted from GMT.
.TP
.B RULES
The name of the rule(s) that apply in the time zone.
If this field contains
.B
"-"
then standard time always applies in the time zone.
.TP
.B FORMAT
The format for time zone abbreviations in this time zone.
The pairs of characters
.B
"%s"
is used to show where the "variable part" of the time zone abbreviation goes.
.PP
A link line has the form
.sp
.nf
.ti +.5i
.ta \w'Link 'u +\w'LINK-FROM 'u
Link	LINK-FROM	LINK-TO
.sp
For example:
.sp
.ti +.5i
Link	Eastern		EST5EDT
.sp
.fi
The
.B LINK-FROM
field should appear as the
.B NAME
field in some zone line;
the
.B LINK-TO
field is used as an alternate name for that zone.
.PP
Lines may appear in any order in the input.
.SH EXAMPLE
[Since a sample time zone file appears in the shell archive,
this section has been omitted.]
.SH FILES
/etc/tzdir	standard directory used for created files
.SH "SEE ALSO"
settz(3), tzfile(5)
.. @(#)tzcomp.8	1.4
End of tzcomp.8
echo tzinfo 1>&2
cat >tzinfo <<'End of tzinfo'
# @(#)tzinfo	1.5

# Rule	NAME	FROM	TO	TYPE	IN	ON	AT	SAVE	LETTER/S
Rule	MostNA	1969	1973	-	Apr	lastSun	2:00	1:00	D
Rule	MostNA	1969	1973	-	Oct	lastSun	2:00	0	S
Rule	MostNA	1974	only	-	Jan	6	2:00	1:00	D
Rule	MostNA	1974	only	-	Nov	24	2:00	0	S
Rule	MostNA	1975	only	-	Feb	23	2:00	1:00	D
Rule	MostNA	1975	only	-	Oct	26	2:00	0	S
Rule	MostNA	1976	2037	-	Apr	lastSun	2:00	1:00	D
Rule	MostNA	1976	2037	-	Oct	lastSun	2:00	0	S

# Almost surely wrong:

# Rule	NAME	FROM	TO	TYPE	IN	ON	AT	SAVE	LETTER/S
Rule	Oz-Eur	1969	1973	-	Apr	lastSun	2:00	1:00	S
Rule	Oz-Eur	1969	1973	-	Oct	lastSun	2:00	0	-
Rule	Oz-Eur	1974	only	-	Jan	6	2:00	1:00	S
Rule	Oz-Eur	1974	only	-	Nov	24	2:00	0	-
Rule	Oz-Eur	1975	only	-	Feb	23	2:00	1:00	S
Rule	Oz-Eur	1975	only	-	Oct	26	2:00	0	-
Rule	Oz-Eur	1976	2037	-	Apr	lastSun	2:00	1:00	S
Rule	Oz-Eur	1976	2037	-	Oct	lastSun	2:00	0	-

# New names

# Zone	NAME		GMTOFF	RULES	FORMAT
Zone	Atlantic	-4:00	MostNA	A%sT
Zone	Eastern		-5:00	MostNA	E%sT
Zone	Central		-6:00	MostNA	C%sT
Zone	Mountain	-7:00	MostNA	M%sT
Zone	Pacific		-8:00	MostNA	P%sT
Zone	Yukon		-9:00	MostNA	Y%sT
Zone	Hawaiian	-10:00	MostNA	H%sT
Zone	Newfoundland	-3:30	-	NST
Zone	Japan		9:00	-	JST
Zone	WET		0	Oz-Eur	WE%sT
Zone	MET		1 	Oz-Eur	ME%sT
Zone	EET		2	Oz-Eur	EE%sT
Zone	AEST		10:00	Oz-Eur	AES%sT
Zone	ACST		9:30	Oz-Eur	ACS%sT
Zone	AWST		8:00	-	AWST	# No Daylight Saving here?

#
# A settz("") uses the code's built-in GMT without going to disk to get
# the information.  Still, we want things to work if somebody does a
# settz("GMT"), so. . .
#

Zone	GMT		0	-	GMT

# Old names

# Link	LINK-FROM	LINK-TO
Link	Eastern		EST5EDT
Link	Central		CST6CDT
Link	Mountain	MST7MDT
Link	Pacific		PST8PDT

# "Pacific Presidential Election Time" is being contemplated in Congress

# Rule	NAME	FROM	TO	TYPE	IN	ON	AT	SAVE	LETTER/S
Rule	Twilite	1969	1973	-	Apr	lastSun	2:00	1:00	D
Rule	Twilite	1969	1973	-	Oct	lastSun	2:00	0	S
Rule	Twilite	1974	only	-	Jan	6	2:00	1:00	D
Rule	Twilite	1974	only	-	Nov	24	2:00	0	S
Rule	Twilite	1975	only	-	Feb	23	2:00	1:00	D
Rule	Twilite	1975	only	-	Oct	26	2:00	0	S
Rule	Twilite	1976	2037	-	Apr	lastSun	2:00	1:00	D
Rule	Twilite	1976	1987	-	Oct	lastSun	2:00	0	S
Rule	Twilite	1988	2037	uspres	Oct	lastSun	2:00	1:00	PE
Rule	Twilite	1988	2037	uspres	Nov	Sun>=7	2:00	0	S
Rule	Twilite	1988	2037	nonpres	Oct	lastSun	2:00	0	S

# Zone	NAME		GMTOFF	RULES	FORMAT
Zone	New-Pacific	-8:00	Twilite	P%sT

# Next really belongs in a separate file

Link	Eastern		localtime
End of tzinfo
exit
--
	UUCP: ..decvax!seismo!elsie!ado    ARPA: elsie!ado at seismo.ARPA
	DEC, VAX and Elsie are Digital Equipment and Borden trademarks

Volume-Number: Volume 5, Number 57