Re: tzset(3): update man page to reality
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 - 1.25 > +++ lib/libc/time/tzset.3 3 Oct 2022 19:32:05 - > @@ -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 >
Re: tzset(3): update man page to reality
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 - 1.25 +++ lib/libc/time/tzset.3 3 Oct 2022 19:32:05 - @@ -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 \&- ,
tzset(3): update man page to reality
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? - 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 - 1.25 +++ lib/libc/time/tzset.3 3 Oct 2022 19:24:02 - @@ -8,62 +8,99 @@ .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 \&: +.It +a string containing 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 +111,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 +125,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 +168,7 @@ If no .Ar
