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