Better path handling description, also document tzname, timezone daylight.

Explicitly mention that most programs do not need to call tzset() directly.
OK deraadt@ jmc@ benno@

1 files changed, 83 insertions, 42 deletions

diff --git a/lib/libc/time/tzset.3 b/lib/libc/time/tzset.3
index 12083b1d6c6..a410c4787fa 100644
--- a/lib/libc/time/tzset.3
+++ b/lib/libc/time/tzset.3
@@ -1,5 +1,5 @@
-.\"	$OpenBSD: tzset.3,v 1.25 2022/09/23 17:29:22 millert Exp $
-.Dd $Mdocdate: September 23 2022 $
+.\"	$OpenBSD: tzset.3,v 1.26 2022/10/04 13:33:57 millert Exp $
+.Dd $Mdocdate: October 4 2022 $
 .Dt TZSET 3
 .Os
 .Sh NAME
@@ -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
+is 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
@@ -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 Meridian; otherwise it shall be
 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.