Todd C. Miller(mill...@openbsd.org) on 2022.10.03 13:32:22 -0600: > On Mon, 03 Oct 2022 13:27:05 -0600, "Todd C. Miller" wrote: > > > We did not document tzname, timezone or daylight and the rules > > regarding pathnames was not entirely clear.
reads ok to me > > I think it is worth mentioning that unless your program calls > > chroot(2), you probably don't need to call tzset(3). good idea > > Opinions? > > Now including examples of the pathname format. ok benno@ > - todd > > Index: lib/libc/time/tzset.3 > =================================================================== > RCS file: /cvs/src/lib/libc/time/tzset.3,v > retrieving revision 1.25 > diff -u -p -u -r1.25 tzset.3 > --- lib/libc/time/tzset.3 23 Sep 2022 17:29:22 -0000 1.25 > +++ lib/libc/time/tzset.3 3 Oct 2022 19:32:05 -0000 > @@ -8,62 +8,103 @@ > .Nd initialize time conversion information > .Sh SYNOPSIS > .In time.h > +.Vt extern char *tzname[2]; > +.Vt extern long timezone; > +.Vt extern long daylight; > .Ft void > .Fn tzset "void" > .Ft void > .Fn tzsetwall "void" > .Sh DESCRIPTION > +The > .Fn tzset > -uses the value of the environment variable > +function uses the value of the environment variable > .Ev TZ > -to set time conversion information used by > +to set the time conversion information used by > .Xr localtime 3 . > -If > -.Ev TZ > -does not appear in the environment, > -or if the calling process has changed its user or group ID, > -the best available approximation to local wall clock time, as specified > -by the > -.Xr tzfile 5 > -format file > -.Pa /etc/localtime , > -is used by > +It also sets the following external variables: > +.Bl -tag -width "tzname[2]" > +.It Vt tzname[2] > +the designations for standard and daylight saving time, see the description > of > +.Ar std No and Ar dst > +below > +.It Vt timezone > +the number of seconds West of UTC > +.It Vt daylight > +0 if the time zone has never observed daylight saving time, otherwise > +non-zero > +.El > +.Pp > +Most programs do not need to call > +.Fn tzset > +directly, it will be called automatically as needed by the functions > +described in > .Xr localtime 3 . > +Privileged processes that use > +.Xr chroot 2 > +may wish to call > +.Fn tzset > +to initialize the time conversion information before changing to > +a restricted root directory that does not include time conversion > +data files. > .Pp > If > .Ev TZ > -appears in the environment but its value is a null string, > -Coordinated Universal Time (UTC) is used (without leap second > -correction). > +does not appear in the environment, or if the calling process has > +changed its user or group ID, the system time zone file, > +.Pa /etc/localtime , > +is used. > .Pp > If > .Ev TZ > -appears in the environment and its value begins with a colon, > -it is used as the pathname of a file > -from which to read the time conversion information. > +appears in the environment it may be one of two formats: > +.Bl -bullet > +.It > +the pathname of a > +.Xr tzfile 5 > +format file from which to read the time conversion information, > +optionally prefixed with a colon > +.Pq Ql \&: , > +such as > +.Dq :America/Denver > +or > +.Dq Europe/Berlin . > +.It > +a string that directly specifies the time conversion information > +(see below) which may not begin with a colon > +.Pq Ql \&: > +.El > .Pp > If > .Ev TZ > appears in the environment and its value does not begin with a colon, > it is first used as the > -pathname of a file from which to read the time conversion information, > +pathname of a > +.Xr tzfile 5 > +format file from which to read the time conversion information, > and, if that file cannot be read, is used directly as a specification of > the time conversion information. > +A value beginning with a colon > +.Pq Ql \&: > +is always treated as a pathname. > +.Pp > +If > +.Ev TZ > +it set to the empty string, Coordinated Universal Time (UTC) is > +used (without leap second correction). > .Pp > When > .Ev TZ > -is used as a pathname, it must be relative to the system time > +is used as a pathname, it must either be a path relative to the system time > conversion information directory, > -.Pa /usr/share/zoneinfo . > -If > -.Ev TZ > -begins with a > -.Ql / > -or contains > +.Pa /usr/share/zoneinfo > +or an absolute path that begins with > +.Pa /usr/share/zoneinfo/ . > +Other absolute paths, or paths that contain > .Ql \&../ , > -it is ignored and the system local time zone file, > +will be ignored and the system local time zone file, > .Pa /etc/localtime , > -is used instead. > +will be used instead. > The file must be in the format specified in > .Xr tzfile 5 . > .Pp > @@ -74,7 +115,7 @@ it must have the following syntax (witho > .Ar std > and > .Ar offset ) : > -.Bd -ragged -offset indent > +.Bd -offset indent > .Ar std > .Sm off > .Ar offset > @@ -88,23 +129,23 @@ Where: > .It Ar std No and Ar dst > Three or more bytes that are the designation for the standard > .Pq Ar std > -or summer > +or the daylight saving > .Pq Ar dst > time zone. > Only > .Ar std > is required; if > .Ar dst > -is missing, then summer time does not apply in this locale. > +is missing, then daylight saving time does not apply in this locale. > Upper and lowercase letters are explicitly allowed. > Any characters except a leading colon > -.Pq Sq \&: , > +.Pq Ql \&: , > digits, comma > -.Pq Sq \&, , > +.Pq Ql \&, , > minus > -.Pq Sq \&- , > +.Pq Ql \&- , > plus > -.Pq Sq \&+ , > +.Pq Ql \&+ , > and ASCII NUL are allowed. > .It Ar offset > Indicates the value one must add to the local time to arrive at > @@ -131,7 +172,7 @@ If no > .Ar offset > follows > .Ar dst , > -summer time is assumed to be one hour ahead of standard time. > +daylight saving time is assumed to be one hour ahead of standard time. > One or more digits may be used; the value is always interpreted as a > decimal number. > The hour must be between zero and 24, and the minutes (and > @@ -142,7 +183,7 @@ the time zone shall be east of the Prime > west (which may be indicated by an optional preceding > .Dq \&+ ) . > .It Ar rule > -Indicates when to change to and back from summer time. > +Indicates when to change to and back from daylight saving time. > .Ar rule > has the form: > .Pp > @@ -150,7 +191,7 @@ has the form: > .Pp > where the first > .Ar date > -describes when the change from standard to summer time occurs and the > +describes when the change from standard to daylight saving time occurs and > the > second > .Ar date > describes when the change back happens. > @@ -226,14 +267,14 @@ format > file > .Cm posixrules > in the system time conversion information directory are used, with the > -standard and summer time offsets from UTC replaced by those specified by > -the > +standard and daylight saving time offsets from UTC replaced by those > +specified by the > .Ar offset > values in > .Ev TZ . > .Pp > For compatibility with System V Release 3.1, a semicolon > -.Pq Sq \&; > +.Pq Ql \&; > may be used to separate the > .Ar rule > from the rest of the specification. >