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. > > I think it is worth mentioning that unless your program calls > chroot(2), you probably don't need to call tzset(3). > > Opinions?
Now including examples of the pathname format. - 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.
