lib/libc/gen/tzset.3

   1 .\" Copyright (c) 1989, 1991, 1993
   2 .\"     The Regents of the University of California.  All rights reserved.
   3 .\"
   4 .\" This code is derived from software contributed to Berkeley by
   5 .\" Arthur Olson.
   6 .\"
   7 .\" Redistribution and use in source and binary forms, with or without
   8 .\" modification, are permitted provided that the following conditions
   9 .\" are met:
  10 .\" 1. Redistributions of source code must retain the above copyright
  11 .\"    notice, this list of conditions and the following disclaimer.
  12 .\" 2. Redistributions in binary form must reproduce the above copyright
  13 .\"    notice, this list of conditions and the following disclaimer in the
  14 .\"    documentation and/or other materials provided with the distribution.
  15 .\" 3. Neither the name of the University nor the names of its contributors
  16 .\"    may be used to endorse or promote products derived from this software
  17 .\"    without specific prior written permission.
  18 .\"
  19 .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
  20 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  21 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  22 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
  23 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  24 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  25 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  26 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  27 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  28 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  29 .\" SUCH DAMAGE.
  30 .\"
  31 .\"     @(#)tzset.3     8.2 (Berkeley) 11/17/93
  32 .\" $FreeBSD$
  33 .\"
  34 .Dd March 6, 2023
  35 .Dt TZSET 3
  36 .Os
  37 .Sh NAME
  38 .Nm tzset
  39 .Nd initialize time conversion information
  40 .Sh LIBRARY
  41 .Lb libc
  42 .Sh SYNOPSIS
  43 .In time.h
  44 .Ft void
  45 .Fn tzset void
  46 .Sh DESCRIPTION
  47 The
  48 .Fn tzset
  49 function
  50 initializes time conversion information used by the library routine
  51 .Xr localtime 3 .
  52 The environment variable
  53 .Ev TZ
  54 specifies how this is done.
  55 .Pp
  56 If
  57 .Ev TZ
  58 does not appear in the environment, the best available approximation to
  59 local wall clock time, as specified by the
  60 .Xr tzfile 5 Ns -format
  61 file
  62 .Pa /etc/localtime
  63 is used.
  64 .Pp
  65 If
  66 .Ev TZ
  67 appears in the environment but its value is a null string, Coordinated
  68 Universal Time
  69 .Pq Tn UTC
  70 is used (without leap second correction).
  71 .Pp
  72 If
  73 .Ev TZ
  74 appears in the environment and its value begins with a colon
  75 .Pq Ql \&: ,
  76 the rest of its value is used as a pathname of a
  77 .Xr tzfile 5 Ns -format
  78 file from which to read the time conversion information.
  79 If the first character of the pathname is a slash
  80 .Pq Ql /
  81 it is used as
  82 an absolute pathname; otherwise, it is used as a pathname relative to
  83 the system time conversion information directory.
  84 .Pp
  85 If its value does not begin with a colon, it is first used as the pathname
  86 of a file (as described above) from which to read the time conversion
  87 information.
  88 If that file cannot be read, the value is then interpreted as a direct
  89 specification (the format is described below) of the time conversion
  90 information.
  91 .Pp
  92 If the
  93 .Ev TZ
  94 environment variable does not specify a
  95 .Xr tzfile 5 Ns -format
  96 file and cannot be interpreted as a direct specification,
  97 .Tn UTC
  98 is used.
  99 .Sh SPECIFICATION FORMAT
 100 When
 101 .Ev TZ
 102 is used directly as a specification of the time conversion information,
 103 it must have the following syntax (spaces inserted for clarity):
 104 .Bd -ragged -offset indent
 105 .Em std offset
 106 .Bo
 107 .Em dst
 108 .Bq Em offset
 109 .Bq , Em rule
 110 .Bc
 111 .Ed
 112 .Pp
 113 Where:
 114 .Bl -tag -width std_and_dst -offset indent
 115 .It Em std No and Em dst
 116 Three or more bytes that are the designation for the standard
 117 .Pq Em std
 118 or summer
 119 .Pq Em dst
 120 time zone.
 121 Only
 122 .Em std
 123 is required; if
 124 .Em dst
 125 is missing, then summer time does not apply in this locale.
 126 Upper and lowercase letters are explicitly allowed.
 127 Any characters
 128 except a leading colon
 129 .Pq Ql \&: ,
 130 digits, comma
 131 .Pq Ql \&, ,
 132 minus
 133 .Pq Ql \- ,
 134 plus
 135 .Pq Ql + ,
 136 and
 137 .Tn ASCII
 138 .Dv NUL
 139 are allowed.
 140 .It Em offset
 141 Indicates the value one must add to the local time to arrive at
 142 Coordinated Universal Time.
 143 The
 144 .Em offset
 145 has the form:
 146 .Bd -ragged -offset indent
 147 .Sm off
 148 .Em hh Bo
 149 .Em : mm
 150 .Bq Em : ss
 151 .Bc
 152 .Sm on
 153 .Ed
 154 .Pp
 155 The minutes
 156 .Pq Em mm
 157 and seconds
 158 .Pq Em ss
 159 are optional.
 160 The hour
 161 .Pq Em hh
 162 is required and may be a single digit.
 163 The
 164 .Em offset
 165 following
 166 .Em std
 167 is required.
 168 If no
 169 .Em offset
 170 follows
 171 .Em dst ,
 172 summer time is assumed to be one hour ahead of standard time.
 173 One or
 174 more digits may be used; the value is always interpreted as a decimal
 175 number.
 176 The hour must be between zero and 24, and the minutes (and
 177 seconds) \(em if present \(em between zero and 59.
 178 If preceded by a
 179 .Pq Ql \-
 180 the time zone shall be east of the Prime Meridian; otherwise it shall be
 181 west (which may be indicated by an optional preceding
 182 .Pq Ql + ) .
 183 .It Em rule
 184 Indicates when to change to and back from summer time.
 185 The
 186 .Em rule
 187 has the form:
 188 .Bd -ragged -offset indent
 189 .Em date/time,date/time
 190 .Ed
 191 .Pp
 192 where the first
 193 .Em date
 194 describes when the change from standard to summer time occurs and the
 195 second
 196 .Em date
 197 describes when the change back happens.
 198 Each
 199 .Em time
 200 field describes when, in current local time, the change to the other
 201 time is made.
 202 .Pp
 203 The format of
 204 .Em date
 205 is one of the following:
 206 .Bl -tag -width "M.m.n.d"
 207 .It Sy J Em n
 208 The Julian day
 209 .Em n
 210 (1 \*(Le
 211 .Em n
 212 \*(Le 365).
 213 Leap days are not counted; that is, in all years \(em including leap
 214 years \(em February 28 is day 59 and March 1 is day 60.
 215 It is
 216 impossible to explicitly refer to the occasional February 29.
 217 .It Em n
 218 The zero-based Julian day
 219 (0 \*(Le
 220 .Em n
 221 \*(Le 365 ) .
 222 Leap days are counted, and it is possible to refer to February 29.
 223 .It Sy M Em m.n.d
 224 The
 225 .Em d Ns 'th
 226 day (0 \*(Le
 227 .Em d
 228 \*(Le 6)
 229 of week
 230 .Em n
 231 of month
 232 .Em m
 233 of the year
 234 (1 \*(Le
 235 .Em n
 236 \*(Le 5),
 237 (1 \*(Le
 238 .Em m
 239 \*(Le 12),
 240 where week 5 means
 241 .Do
 242 the last
 243 .Em d
 244 day in month
 245 .Em m
 246 .Dc
 247 which may occur in either the fourth or the fifth week).
 248 Week 1 is the
 249 first week in which the
 250 .Em d Ns 'th
 251 day occurs.
 252 Day zero is Sunday.
 253 .Pp
 254 The
 255 .Em time
 256 has the same format as
 257 .Em offset
 258 except that no leading sign
 259 .Pq Ql \-
 260 or
 261 .Pq Ql +
 262 is allowed.
 263 The default, if
 264 .Em time
 265 is not given, is
 266 .Sy 02:00:00 .
 267 .El
 268 .Pp
 269 If no
 270 .Em rule
 271 is present in the
 272 .Ev TZ
 273 specification, the rules specified
 274 by the
 275 .Xr tzfile 5 Ns -format
 276 file
 277 .Em posixrules
 278 in the system time conversion information directory are used, with the
 279 standard and summer time offsets from
 280 .Tn UTC
 281 replaced by those specified by
 282 the
 283 .Em offset
 284 values in
 285 .Ev TZ .
 286 .El
 287 .Pp
 288 For compatibility with System V Release 3.1, a semicolon
 289 .Pq Ql \&;
 290 may be used to separate the
 291 .Em rule
 292 from the rest of the specification.
 293 .Sh FILES
 294 .Bl -tag -width /usr/share/zoneinfo/posixrules -compact
 295 .It Pa /etc/localtime
 296 local time zone file
 297 .It Pa /usr/share/zoneinfo
 298 time zone directory
 299 .It Pa /usr/share/zoneinfo/posixrules
 300 rules for
 301 .Tn POSIX Ns -style
 302 .Tn TZ Ns 's
 303 .It Pa /usr/share/zoneinfo/Etc/GMT
 304 for
 305 .Tn UTC
 306 leap seconds
 307 .El
 308 .Pp
 309 If the file
 310 .Pa /usr/share/zoneinfo/UTC
 311 does not exist,
 312 .Tn UTC
 313 leap seconds are loaded from
 314 .Pa /usr/share/zoneinfo/posixrules .
 315 .Sh SEE ALSO
 316 .Xr date 1 ,
 317 .Xr gettimeofday 2 ,
 318 .Xr ctime 3 ,
 319 .Xr getenv 3 ,
 320 .Xr time 3 ,
 321 .Xr tzfile 5
 322 .Sh HISTORY
 323 The
 324 .Fn tzset
 325 function first appeared in
 326 .Bx 4.4 .