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 .\" 4. 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 November 17, 1993
  35 .Dt TZSET 3
  36 .Os
  37 .Sh NAME
  38 .Nm tzset ,
  39 .Nm tzsetwall
  40 .Nd initialize time conversion information
  41 .Sh LIBRARY
  42 .Lb libc
  43 .Sh SYNOPSIS
  44 .In time.h
  45 .Ft void
  46 .Fn tzset void
  47 .Ft void
  48 .Fn tzsetwall void
  49 .Sh DESCRIPTION
  50 The
  51 .Fn tzset
  52 function
  53 initializes time conversion information used by the library routine
  54 .Xr localtime 3 .
  55 The environment variable
  56 .Ev TZ
  57 specifies how this is done.
  58 .Pp
  59 If
  60 .Ev TZ
  61 does not appear in the environment, the best available approximation to
  62 local wall clock time, as specified by the
  63 .Xr tzfile 5 Ns -format
  64 file
  65 .Pa /etc/localtime
  66 is used.
  67 .Pp
  68 If
  69 .Ev TZ
  70 appears in the environment but its value is a null string, Coordinated
  71 Universal Time
  72 .Pq Tn UTC
  73 is used (without leap second correction).
  74 .Pp
  75 If
  76 .Ev TZ
  77 appears in the environment and its value begins with a colon
  78 .Pq Ql \&: ,
  79 the rest of its value is used as a pathname of a
  80 .Xr tzfile 5 Ns -format
  81 file from which to read the time conversion information.
  82 If the first character of the pathname is a slash
  83 .Pq Ql /
  84 it is used as
  85 an absolute pathname; otherwise, it is used as a pathname relative to
  86 the system time conversion information directory.
  87 .Pp
  88 If its value does not begin with a colon, it is first used as the pathname
  89 of a file (as described above) from which to read the time conversion
  90 information.
  91 If that file cannot be read, the value is then interpreted as a direct
  92 specification (the format is described below) of the time conversion
  93 information.
  94 .Pp
  95 If the
  96 .Ev TZ
  97 environment variable does not specify a
  98 .Xr tzfile 5 Ns -format
  99 file and cannot be interpreted as a direct specification,
 100 .Tn UTC
 101 is used.
 102 .Pp
 103 The
 104 .Fn tzsetwall
 105 function
 106 sets things up so that
 107 .Xr localtime 3
 108 returns the best available approximation of local wall clock time.
 109 .Sh SPECIFICATION FORMAT
 110 When
 111 .Ev TZ
 112 is used directly as a specification of the time conversion information,
 113 it must have the following syntax (spaces inserted for clarity):
 114 .Bd -ragged -offset indent
 115 .Em std offset
 116 .Bo
 117 .Em dst
 118 .Bq Em offset
 119 .Bq , Em rule
 120 .Bc
 121 .Ed
 122 .Pp
 123 Where:
 124 .Bl -tag -width std_and_dst -offset indent
 125 .It Em std No and Em dst
 126 Three or more bytes that are the designation for the standard
 127 .Pq Em std
 128 or summer
 129 .Pq Em dst
 130 time zone.
 131 Only
 132 .Em std
 133 is required; if
 134 .Em dst
 135 is missing, then summer time does not apply in this locale.
 136 Upper and lowercase letters are explicitly allowed.
 137 Any characters
 138 except a leading colon
 139 .Pq Ql \&: ,
 140 digits, comma
 141 .Pq Ql \&, ,
 142 minus
 143 .Pq Ql \- ,
 144 plus
 145 .Pq Ql + ,
 146 and
 147 .Tn ASCII
 148 .Dv NUL
 149 are allowed.
 150 .It Em offset
 151 Indicates the value one must add to the local time to arrive at
 152 Coordinated Universal Time.
 153 The
 154 .Em offset
 155 has the form:
 156 .Bd -ragged -offset indent
 157 .Sm off
 158 .Em hh Bo
 159 .Em : mm
 160 .Bq Em : ss
 161 .Bc
 162 .Sm on
 163 .Ed
 164 .Pp
 165 The minutes
 166 .Pq Em mm
 167 and seconds
 168 .Pq Em ss
 169 are optional.
 170 The hour
 171 .Pq Em hh
 172 is required and may be a single digit.
 173 The
 174 .Em offset
 175 following
 176 .Em std
 177 is required.
 178 If no
 179 .Em offset
 180 follows
 181 .Em dst ,
 182 summer time is assumed to be one hour ahead of standard time.
 183 One or
 184 more digits may be used; the value is always interpreted as a decimal
 185 number.
 186 The hour must be between zero and 24, and the minutes (and
 187 seconds) \(em if present \(em between zero and 59.
 188 If preceded by a
 189 .Pq Ql \-
 190 the time zone shall be east of the Prime Meridian; otherwise it shall be
 191 west (which may be indicated by an optional preceding
 192 .Pq Ql + ) .
 193 .It Em rule
 194 Indicates when to change to and back from summer time.
 195 The
 196 .Em rule
 197 has the form:
 198 .Bd -ragged -offset indent
 199 .Em date/time,date/time
 200 .Ed
 201 .Pp
 202 where the first
 203 .Em date
 204 describes when the change from standard to summer time occurs and the
 205 second
 206 .Em date
 207 describes when the change back happens.
 208 Each
 209 .Em time
 210 field describes when, in current local time, the change to the other
 211 time is made.
 212 .Pp
 213 The format of
 214 .Em date
 215 is one of the following:
 216 .Bl -tag -width "M.m.n.d"
 217 .It Sy J Em n
 218 The Julian day
 219 .Em n
 220 (1 \*(Le
 221 .Em n
 222 \*(Le 365).
 223 Leap days are not counted; that is, in all years \(em including leap
 224 years \(em February 28 is day 59 and March 1 is day 60.
 225 It is
 226 impossible to explicitly refer to the occasional February 29.
 227 .It Em n
 228 The zero-based Julian day
 229 (0 \*(Le
 230 .Em n
 231 \*(Le 365 ) .
 232 Leap days are counted, and it is possible to refer to February 29.
 233 .It Sy M Em m.n.d
 234 The
 235 .Em d Ns 'th
 236 day (0 \*(Le
 237 .Em d
 238 \*(Le 6)
 239 of week
 240 .Em n
 241 of month
 242 .Em m
 243 of the year
 244 (1 \*(Le
 245 .Em n
 246 \*(Le 5),
 247 (1 \*(Le
 248 .Em m
 249 \*(Le 12),
 250 where week 5 means
 251 .Do
 252 the last
 253 .Em d
 254 day in month
 255 .Em m
 256 .Dc
 257 which may occur in either the fourth or the fifth week).
 258 Week 1 is the
 259 first week in which the
 260 .Em d Ns 'th
 261 day occurs.
 262 Day zero is Sunday.
 263 .Pp
 264 The
 265 .Em time
 266 has the same format as
 267 .Em offset
 268 except that no leading sign
 269 .Pq Ql \-
 270 or
 271 .Pq Ql +
 272 is allowed.
 273 The default, if
 274 .Em time
 275 is not given, is
 276 .Sy 02:00:00 .
 277 .El
 278 .Pp
 279 If no
 280 .Em rule
 281 is present in the
 282 .Ev TZ
 283 specification, the rules specified
 284 by the
 285 .Xr tzfile 5 Ns -format
 286 file
 287 .Em posixrules
 288 in the system time conversion information directory are used, with the
 289 standard and summer time offsets from
 290 .Tn UTC
 291 replaced by those specified by
 292 the
 293 .Em offset
 294 values in
 295 .Ev TZ .
 296 .El
 297 .Pp
 298 For compatibility with System V Release 3.1, a semicolon
 299 .Pq Ql \&;
 300 may be used to separate the
 301 .Em rule
 302 from the rest of the specification.
 303 .Sh FILES
 304 .Bl -tag -width /usr/share/zoneinfo/posixrules -compact
 305 .It Pa /etc/localtime
 306 local time zone file
 307 .It Pa /usr/share/zoneinfo
 308 time zone directory
 309 .It Pa /usr/share/zoneinfo/posixrules
 310 rules for
 311 .Tn POSIX Ns -style
 312 .Tn TZ Ns 's
 313 .It Pa /usr/share/zoneinfo/Etc/GMT
 314 for
 315 .Tn UTC
 316 leap seconds
 317 .El
 318 .Pp
 319 If the file
 320 .Pa /usr/share/zoneinfo/UTC
 321 does not exist,
 322 .Tn UTC
 323 leap seconds are loaded from
 324 .Pa /usr/share/zoneinfo/posixrules .
 325 .Sh SEE ALSO
 326 .Xr date 1 ,
 327 .Xr gettimeofday 2 ,
 328 .Xr ctime 3 ,
 329 .Xr getenv 3 ,
 330 .Xr time 3 ,
 331 .Xr tzfile 5
 332 .Sh HISTORY
 333 The
 334 .Fn tzset
 335 and
 336 .Fn tzsetwall
 337 functions first appeared in
 338 .Bx 4.4 .