time/newtzset.3

   1 .TH NEWTZSET 3
   2 .SH NAME
   3 tzset \- initialize time conversion information
   4 .SH SYNOPSIS
   5 .nf
   6 .B void tzset()
   7 .PP
   8 .B cc ... -lz
   9 .fi
  10 .SH DESCRIPTION
  11 .I Tzset
  12 uses the value of the environment variable
  13 .B TZ
  14 to set time conversion information used by
  15 .IR localtime .
  16 If
  17 .B TZ
  18 does not appear in the environment,
  19 the best available approximation to local wall clock time, as specified
  20 by the
  21 .IR tzfile (5)-format
  22 file
  23 .B localtime
  24 in the system time conversion information directory, is used by
  25 .IR localtime .
  26 If
  27 .B TZ
  28 appears in the environment but its value is a null string,
  29 Coordinated Universal Time (UTC) is used (without leap second
  30 correction).  If
  31 .B TZ
  32 appears in the environment and its value is not a null string:
  33 .IP
  34 if the value begins with a colon, it is used as a pathname of a file
  35 from which to read the time conversion information;
  36 .IP
  37 if the value does not begin with a colon, it is first used as the
  38 pathname of a file from which to read the time conversion information,
  39 and, if that file cannot be read, is used directly as a specification of
  40 the time conversion information.
  41 .PP
  42 When
  43 .B TZ
  44 is used as a pathname, if it begins with a slash,
  45 it is used as an absolute pathname; otherwise,
  46 it is used as a pathname relative to a system time conversion information
  47 directory.
  48 The file must be in the format specified in
  49 .IR tzfile (5).
  50 .PP
  51 When
  52 .B TZ
  53 is used directly as a specification of the time conversion information,
  54 it must have the following syntax (spaces inserted for clarity):
  55 .IP
  56 \fIstd\|offset\fR[\fIdst\fR[\fIoffset\fR][\fB,\fIrule\fR]]
  57 .PP
  58 Where:
  59 .RS
  60 .TP 15
  61 .IR std " and " dst
  62 Three or more bytes that are the designation for the standard
  63 .RI ( std )
  64 or summer
  65 .RI ( dst )
  66 time zone.  Only
  67 .I std
  68 is required; if
  69 .I dst
  70 is missing, then summer time does not apply in this locale.
  71 Upper- and lowercase letters are explicitly allowed.  Any characters
  72 except a leading colon
  73 .RB ( : ),
  74 digits, comma
  75 .RB ( , ),
  76 minus
  77 .RB ( \(mi ),
  78 plus
  79 .RB ( \(pl ),
  80 and ASCII NUL are allowed.
  81 .TP
  82 .I offset
  83 Indicates the value one must add to the local time to arrive at
  84 Coordinated Universal Time.  The
  85 .I offset
  86 has the form:
  87 .RS
  88 .IP
  89 \fIhh\fR[\fB:\fImm\fR[\fB:\fIss\fR]]
  90 .RE
  91 .IP
  92 The minutes
  93 .RI ( mm )
  94 and seconds
  95 .RI ( ss )
  96 are optional.  The hour
  97 .RI ( hh )
  98 is required and may be a single digit.  The
  99 .I offset
 100 following
 101 .I std
 102 is required.  If no
 103 .I offset
 104 follows
 105 .IR dst ,
 106 summer time is assumed to be one hour ahead of standard time.  One or
 107 more digits may be used; the value is always interpreted as a decimal
 108 number.  The hour must be between zero and 24, and the minutes (and
 109 seconds) \(em if present \(em between zero and 59.  If preceded by a
 110 .RB `` \(mi '',
 111 the time zone shall be east of the Prime Meridian; otherwise it shall be
 112 west (which may be indicated by an optional preceding
 113 .RB `` \(pl '').
 114 .TP
 115 .I rule
 116 Indicates when to change to and back from summer time.  The
 117 .I rule
 118 has the form:
 119 .RS
 120 .IP
 121 \fIdate\fB/\fItime\fB,\fIdate\fB/\fItime\fR
 122 .RE
 123 .IP
 124 where the first
 125 .I date
 126 describes when the change from standard to summer time occurs and the
 127 second
 128 .I date
 129 describes when the change back happens.  Each
 130 .I time
 131 field describes when, in current local time, the change to the other
 132 time is made.
 133 .IP
 134 The format of
 135 .I date
 136 is one of the following:
 137 .RS
 138 .TP 10
 139 .BI J n
 140 The Julian day
 141 .I n
 142 .RI "(1\ \(<=" "\ n\ " "\(<=\ 365).
 143 Leap days are not counted; that is, in all years \(em including leap
 144 years \(em February 28 is day 59 and March 1 is day 60.  It is
 145 impossible to explicitly refer to the occasional February 29.
 146 .TP
 147 .I n
 148 The zero-based Julian day
 149 .RI "(0\ \(<=" "\ n\ " "\(<=\ 365).
 150 Leap days are counted, and it is possible to refer to February 29.
 151 .TP
 152 .BI M m . n . d
 153 The
 154 .IR d' th
 155 day
 156 .RI "(0\ \(<=" "\ d\ " "\(<=\ 6)
 157 of week
 158 .I n
 159 of month
 160 .I m
 161 of the year
 162 .RI "(1\ \(<=" "\ n\ " "\(<=\ 5,
 163 .RI "1\ \(<=" "\ m\ " "\(<=\ 12,
 164 where week 5 means ``the last
 165 .I d
 166 day in month
 167 .IR m ''
 168 which may occur in either the fourth or the fifth week).  Week 1 is the
 169 first week in which the
 170 .IR d' th
 171 day occurs.  Day zero is Sunday.
 172 .RE
 173 .IP "" 15
 174 The
 175 .I time
 176 has the same format as
 177 .I offset
 178 except that no leading sign
 179 .RB (`` \(mi ''
 180 or
 181 .RB `` \(pl '')
 182 is allowed.  The default, if
 183 .I time
 184 is not given, is
 185 .BR 02:00:00 .
 186 .RE
 187 .LP
 188 If no
 189 .I rule
 190 is present in
 191 .BR TZ ,
 192 the rules specified
 193 by the
 194 .IR tzfile (5)-format
 195 file
 196 .B posixrules
 197 in the system time conversion information directory are used, with the
 198 standard and summer time offsets from UTC replaced by those specified by
 199 the
 200 .I offset
 201 values in
 202 .BR TZ .
 203 .PP
 204 For compatibility with System V Release 3.1, a semicolon
 205 .RB ( ; )
 206 may be used to separate the
 207 .I rule
 208 from the rest of the specification.
 209 .PP
 210 If the
 211 .B TZ
 212 environment variable does not specify a
 213 .IR tzfile (5)-format
 214 and cannot be interpreted as a direct specification,
 215 UTC is used.
 216 .SH FILES
 217 .ta \w'/usr/local/etc/zoneinfo/posixrules\0\0'u
 218 /usr/local/etc/zoneinfo time zone information directory
 219 .br
 220 /usr/local/etc/zoneinfo/localtime       local time zone file
 221 .br
 222 /usr/local/etc/zoneinfo/posixrules      used with POSIX-style TZ's
 223 .br
 224 /usr/local/etc/zoneinfo/GMT     for UTC leap seconds
 225 .sp
 226 If
 227 .B /usr/local/etc/zoneinfo/GMT
 228 is absent,
 229 UTC leap seconds are loaded from
 230 .BR /usr/local/etc/zoneinfo/posixrules .
 231 .SH SEE ALSO
 232 getenv(3),
 233 newctime(3),
 234 time(2),
 235 tzfile(5)
 236 .\" @(#)newtzset.3      7.3