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