From: millert Date: Tue, 4 Oct 2022 13:33:57 +0000 (+0000) Subject: Better path handling description, also document tzname, timezone daylight. X-Git-Url: http://artulab.com/gitweb/?a=commitdiff_plain;h=0b11e45035f5839d5e3ce9e86d234a5c7eb8f919;p=openbsd 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@ --- 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.