original/man3/tzset.3

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