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