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