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: src/lib/libc/gen/tzset.3,v 1.12 2001/10/01 16:08:51 ru Exp $
  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
 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.  Only
 135 .Em std
 136 is required; if
 137 .Em dst
 138 is missing, then summer time does not apply in this locale.
 139 Upper and lowercase letters are explicitly allowed.  Any characters
 140 except a leading colon
 141 .Pq Ql \&: ,
 142 digits, comma
 143 .Pq Ql \&, ,
 144 minus
 145 .Pq Ql \- ,
 146 plus
 147 .Pq Ql + ,
 148 and
 149 .Tn ASCII
 150 .Dv NUL
 151 are allowed.
 152 .It Em offset
 153 Indicates the value one must add to the local time to arrive at
 154 Coordinated Universal Time.  The
 155 .Em offset
 156 has the form:
 157 .Bd -ragged -offset indent
 158 .Sm off
 159 .Em hh Bo
 160 .Em : mm
 161 .Bq Em : ss
 162 .Bc
 163 .Sm on
 164 .Ed
 165 .Pp
 166 The minutes
 167 .Pq Em mm
 168 and seconds
 169 .Pq Em ss
 170 are optional.  The hour
 171 .Pq Em hh
 172 is required and may be a single digit.  The
 173 .Em offset
 174 following
 175 .Em std
 176 is required.  If no
 177 .Em offset
 178 follows
 179 .Em dst ,
 180 summer time is assumed to be one hour ahead of standard time.  One or
 181 more digits may be used; the value is always interpreted as a decimal
 182 number.  The hour must be between zero and 24, and the minutes (and
 183 seconds) \(em if present \(em between zero and 59.  If preceded by a
 184 .Pq Ql \-
 185 the time zone shall be east of the Prime Meridian; otherwise it shall be
 186 west (which may be indicated by an optional preceding
 187 .Pq Ql + ) .
 188 .It Em rule
 189 Indicates when to change to and back from summer time.  The
 190 .Em rule
 191 has the form:
 192 .Bd -ragged -offset indent
 193 .Em date/time,date/time
 194 .Ed
 195 .Pp
 196 where the first
 197 .Em date
 198 describes when the change from standard to summer time occurs and the
 199 second
 200 .Em date
 201 describes when the change back happens.  Each
 202 .Em time
 203 field describes when, in current local time, the change to the other
 204 time is made.
 205 .Pp
 206 The format of
 207 .Em date
 208 is one of the following:
 209 .Bl -tag -width "M.m.n.d"
 210 .It Sy J Em n
 211 The Julian day
 212 .Em n
 213 (1 \*(Le
 214 .Em n
 215 \*(Le 365).
 216 Leap days are not counted; that is, in all years \(em including leap
 217 years \(em February 28 is day 59 and March 1 is day 60.  It is
 218 impossible to explicitly refer to the occasional February 29.
 219 .It Em n
 220 The zero-based Julian day
 221 (0 \*(Le
 222 .Em n
 223 \*(Le 365 ) .
 224 Leap days are counted, and it is possible to refer to February 29.
 225 .It Sy M  Em m.n.d
 226 The
 227 .Em d Ns 'th
 228 day (0 \*(Le
 229 .Em d
 230 \*(Le 6)
 231 of week
 232 .Em n
 233 of month
 234 .Em m
 235 of the year
 236 (1 \*(Le
 237 .Em n
 238 \*(Le 5),
 239 (1 \*(Le
 240 .Em m
 241 \*(Le 12),
 242 where week 5 means
 243 .Do
 244 the last
 245 .Em d
 246 day in month
 247 .Em m
 248 .Dc
 249 which may occur in either the fourth or the fifth week).  Week 1 is the
 250 first week in which the
 251 .Em d Ns 'th
 252 day occurs.  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.  The default, if
 263 .Em time
 264 is not given, is
 265 .Sy 02:00:00 .
 266 .El
 267 .Pp
 268 If no
 269 .Em rule
 270 is present in the
 271 .Ev TZ
 272 specification, the rules specified
 273 by the
 274 .Xr tzfile 5 Ns -format
 275 file
 276 .Em posixrules
 277 in the system time conversion information directory are used, with the
 278 standard and summer time offsets from
 279 .Tn UTC
 280 replaced by those specified by
 281 the
 282 .Em offset
 283 values in
 284 .Ev TZ .
 285 .El
 286 .Pp
 287 For compatibility with System V Release 3.1, a semicolon
 288 .Pq Ql \&;
 289 may be used to separate the
 290 .Em rule
 291 from the rest of the specification.
 292 .Sh FILES
 293 .Bl -tag -width /usr/share/zoneinfo/posixrules -compact
 294 .It Pa /etc/localtime
 295 local time zone file
 296 .It Pa /usr/share/zoneinfo
 297 time zone directory
 298 .It Pa /usr/share/zoneinfo/posixrules
 299 rules for
 300 .Tn POSIX Ns -style
 301 .Tn TZ Ns 's
 302 .It Pa /usr/share/zoneinfo/GMT
 303 for
 304 .Tn UTC
 305 leap seconds
 306 .El
 307 .Pp
 308 If the file
 309 .Pa /usr/share/zoneinfo/GMT
 310 does not exist,
 311 .Tn UTC
 312 leap seconds are loaded from
 313 .Pa /usr/share/zoneinfo/posixrules .
 314 .Sh SEE ALSO
 315 .Xr date 1 ,
 316 .Xr gettimeofday 2 ,
 317 .Xr ctime 3 ,
 318 .Xr getenv 3 ,
 319 .Xr time 3 ,
 320 .Xr tzfile 5
 321 .Sh HISTORY
 322 The
 323 .Fn tzset
 324 and
 325 .Fn tzsetwall
 326 functions first appeared in
 327 .Bx 4.4 .