original/man3/tzset.3

   1 .\" Copyright 1993 David Metcalfe (david@prism.demon.co.uk)
   2 .\"
   3 .\" Permission is granted to make and distribute verbatim copies of this
   4 .\" manual provided the copyright notice and this permission notice are
   5 .\" preserved on all copies.
   6 .\"
   7 .\" Permission is granted to copy and distribute modified versions of this
   8 .\" manual under the conditions for verbatim copying, provided that the
   9 .\" entire resulting derived work is distributed under the terms of a
  10 .\" permission notice identical to this one.
  11 .\"
  12 .\" Since the Linux kernel and libraries are constantly changing, this
  13 .\" manual page may be incorrect or out-of-date.  The author(s) assume no
  14 .\" responsibility for errors or omissions, or for damages resulting from
  15 .\" the use of the information contained herein.  The author(s) may not
  16 .\" have taken the same level of care in the production of this manual,
  17 .\" which is licensed free of charge, as they might when working
  18 .\" professionally.
  19 .\"
  20 .\" Formatted or processed versions of this manual, if unaccompanied by
  21 .\" the source, must acknowledge the copyright and authors of this work.
  22 .\"
  23 .\" References consulted:
  24 .\"     Linux libc source code
  25 .\"     Lewine's _POSIX Programmer's Guide_ (O'Reilly & Associates, 1991)
  26 .\"     386BSD man pages
  27 .\" Modified Sun Jul 25 11:01:58 1993 by Rik Faith (faith@cs.unc.edu)
  28 .\" Modified 2001-11-13, aeb
  29 .\" Modified 2004-12-01 mtk and Martin Schulze <joey@infodrom.org>
  30 .\"
  31 .TH TZSET 3  2010-02-25 "" "Linux Programmer's Manual"
  32 .SH NAME
  33 tzset, tzname, timezone, daylight \- initialize time conversion information
  34 .SH SYNOPSIS
  35 .nf
  36 .B #include <time.h>
  37 .sp
  38 .B void tzset (void);
  39 .sp
  40 .BI "extern char *" tzname [2];
  41 .BI "extern long " timezone ;
  42 .BI "extern int " daylight ;
  43 .fi
  44 .sp
  45 .in -4n
  46 Feature Test Macro Requirements for glibc (see
  47 .BR feature_test_macros (7)):
  48 .in
  49 .sp
  50 .BR tzset ():
  51 _POSIX_C_SOURCE\ >=\ 1 || _XOPEN_SOURCE || _POSIX_SOURCE
  52 .br
  53 .IR tzname :
  54 _POSIX_C_SOURCE\ >=\ 1 || _XOPEN_SOURCE || _POSIX_SOURCE
  55 .br
  56 .IR timezone :
  57 _SVID_SOURCE || _XOPEN_SOURCE
  58 .br
  59 .IR daylight :
  60 _SVID_SOURCE || _XOPEN_SOURCE
  61 .SH DESCRIPTION
  62 The
  63 .BR tzset ()
  64 function initializes the \fItzname\fP variable from the
  65 .B TZ
  66 environment variable.
  67 This function is automatically called by the
  68 other time conversion functions that depend on the timezone.
  69 In a System-V-like environment, it will also set the variables \fItimezone\fP
  70 (seconds West of UTC) and \fIdaylight\fP (to 0 if this timezone does not
  71 have any daylight saving time rules, or to nonzero if there is a time during
  72 the year when daylight saving time applies).
  73 .PP
  74 If the
  75 .B TZ
  76 variable does not appear in the environment, the \fItzname\fP
  77 variable is initialized with the best approximation of local wall clock
  78 time, as specified by the
  79 .BR tzfile (5)-format
  80 file \fIlocaltime\fP
  81 found in the system timezone directory (see below).
  82 (One also often sees
  83 .I /etc/localtime
  84 used here, a symlink to the right file in the system timezone directory.)
  85 .PP
  86 If the
  87 .B TZ
  88 variable does appear in the environment but its value is empty
  89 or its value cannot be interpreted using any of the formats specified
  90 below, Coordinated Universal Time (UTC) is used.
  91 .PP
  92 The value of
  93 .B TZ
  94 can be one of three formats.
  95 The first format is used
  96 when there is no daylight saving time in the local timezone:
  97 .sp
  98 .RS
  99 .I std offset
 100 .RE
 101 .sp
 102 The \fIstd\fP string specifies the name of the timezone and must be
 103 three or more alphabetic characters.
 104 The \fIoffset\fP string immediately
 105 follows \fIstd\fP and specifies the time value to be added to the local
 106 time to get Coordinated Universal Time (UTC).
 107 The \fIoffset\fP is positive
 108 if the local timezone is west of the Prime Meridian and negative if it is
 109 east.
 110 The hour must be between 0 and 24, and the minutes and seconds
 111 0 and 59.
 112 .PP
 113 The second format is used when there is daylight saving time:
 114 .sp
 115 .RS
 116 .I std offset dst [offset],start[/time],end[/time]
 117 .RE
 118 .sp
 119 There are no spaces in the specification.
 120 The initial \fIstd\fP and
 121 \fIoffset\fP specify the standard timezone, as described above.
 122 The \fIdst\fP string and \fIoffset\fP specify the name and offset for the
 123 corresponding daylight saving timezone.
 124 If the offset is omitted,
 125 it default to one hour ahead of standard time.
 126 .PP
 127 The \fIstart\fP field specifies when daylight saving time goes into
 128 effect and the \fIend\fP field specifies when the change is made back to
 129 standard time.
 130 These fields may have the following formats:
 131 .TP
 132 J\fIn\fP
 133 This specifies the Julian day with \fIn\fP between 1 and 365.
 134 February 29 is never counted even in leap years.
 135 .TP
 136 .I n
 137 This specifies the Julian day with \fIn\fP between 1 and 365.
 138 February 29 is counted in leap years.
 139 .TP
 140 M\fIm\fP.\fIw\fP.\fId\fP
 141 This specifies day \fId\fP (0 <= \fId\fP <= 6) of week \fIw\fP
 142 (1 <= \fIw\fP <= 5) of month \fIm\fP (1 <= \fIm\fP <= 12).
 143 Week 1 is
 144 the first week in which day \fId\fP occurs and week 5 is the last week
 145 in which day \fId\fP occurs.
 146 Day 0 is a Sunday.
 147 .PP
 148 The \fItime\fP fields specify when, in the local time currently in effect,
 149 the change to the other time occurs.
 150 If omitted, the default is 02:00:00.
 151
 152 Here is an example for New Zealand,
 153 where the standard time (NZST) is 12 hours ahead of UTC,
 154 and daylight saving time (NZDT), 13 hours ahead of UTC,
 155 runs from the first Sunday in October to the third Sunday in March,
 156 and the changeovers happen at the default time of 02:00:00:
 157 .nf
 158
 159     TZ="NZST-12:00:00NZDT-13:00:00,M10.1.0,M3.3.0"
 160 .fi
 161 .PP
 162 The third format specifies that the timezone information should be read
 163 from a file:
 164 .sp
 165 .RS
 166 :[filespec]
 167 .RE
 168 .sp
 169 If the file specification \fIfilespec\fP is omitted, the timezone
 170 information is read from the file
 171 .I localtime
 172 in the system timezone directory, which nowadays usually is
 173 .IR /usr/share/zoneinfo .
 174 This file is in
 175 .BR tzfile (5)
 176 format.
 177 If \fIfilespec\fP is given, it specifies another
 178 .BR tzfile (5)-format
 179 file to read the timezone information from.
 180 If \fIfilespec\fP does not begin with a \(aq/\(aq, the file specification is
 181 relative to the system timezone directory.
 182 .PP
 183 Here's an example, once more for New Zealand:
 184 .nf
 185
 186     TZ=":Pacific/Auckland"
 187 .fi
 188 .SH FILES
 189 The system timezone directory used depends on the (g)libc version.
 190 Libc4 and libc5 use
 191 .IR /usr/lib/zoneinfo ,
 192 and, since libc-5.4.6,
 193 when this doesn't work, will try
 194 .IR /usr/share/zoneinfo .
 195 Glibc2 will use the environment variable
 196 .BR TZDIR ,
 197 when that exists.
 198 Its default depends on how it was installed, but normally is
 199 .IR /usr/share/zoneinfo .
 200 .LP
 201 This timezone directory contains the files
 202 .nf
 203 localtime      local timezone file
 204 posixrules     rules for POSIX-style TZ's
 205 .fi
 206 .LP
 207 Often
 208 .I /etc/localtime
 209 is a symlink to the file
 210 .I localtime
 211 or to the correct timezone file in the system timezone directory.
 212 .SH "CONFORMING TO"
 213 SVr4, POSIX.1-2001, 4.3BSD.
 214 .SH NOTES
 215 Note that the variable \fIdaylight\fP does not indicate that daylight
 216 saving time applies right now.
 217 It used to give the number of some
 218 algorithm (see the variable \fItz_dsttime\fP in
 219 .BR gettimeofday (2)).
 220 It has been obsolete for many years but is required by SUSv2.
 221 .LP
 222 4.3BSD had a function
 223 .BI "char *timezone(" zone ", " dst )
 224 that returned the
 225 name of the timezone corresponding to its first argument (minutes
 226 West of UTC).
 227 If the second argument was 0, the standard name was used,
 228 otherwise the daylight saving time version.
 229 .SH "SEE ALSO"
 230 .BR date (1),
 231 .BR gettimeofday (2),
 232 .BR time (2),
 233 .BR ctime (3),
 234 .BR getenv (3),
 235 .BR tzfile (5)