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  2015-01-30 "" "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 system timezone is used.
  79 The system timezone is configured by copying, or linking, a file in the
  80 .BR tzfile "(5) format to"
  81 .IR /etc/localtime .
  82 A timezone database of these files may be located in the system
  83 timezone directory (see the \fBFILES\fP section below).
  84 .PP
  85 If the
  86 .B TZ
  87 variable does appear in the environment, but its value is empty,
  88 or its value cannot be interpreted using any of the formats specified
  89 below, then Coordinated Universal Time (UTC) is used.
  90 .PP
  91 The value of
  92 .B TZ
  93 can be one of two formats.
  94 The first format is a string of characters that directly represent the
  95 timezone to be used:
  96 .sp
  97 .RS
  98 .RI "std offset " dst [ offset ][, start [ /time ], end [ /time ]]
  99 .RE
 100 .sp
 101 There are no spaces in the specification.
 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 \fIdst\fP string and \fIoffset\fP specify the name and offset for the
 114 corresponding daylight saving timezone.
 115 If the offset is omitted,
 116 it defaults to one hour ahead of standard time.
 117 .PP
 118 The \fIstart\fP field specifies when daylight saving time goes into
 119 effect and the \fIend\fP field specifies when the change is made back to
 120 standard time.
 121 These fields may have the following formats:
 122 .TP
 123 J\fIn\fP
 124 This specifies the Julian day with \fIn\fP between 1 and 365.
 125 Leap days are not counted.
 126 In this format, February 29 can't be represented;
 127 February 28 is day 59, and March 1 is always day 60.
 128 .TP
 129 .I n
 130 This specifies the zero-based Julian day with \fIn\fP between 0 and 365.
 131 February 29 is counted in leap years.
 132 .TP
 133 M\fIm\fP.\fIw\fP.\fId\fP
 134 This specifies day \fId\fP (0 <= \fId\fP <= 6) of week \fIw\fP
 135 (1 <= \fIw\fP <= 5) of month \fIm\fP (1 <= \fIm\fP <= 12).
 136 Week 1 is
 137 the first week in which day \fId\fP occurs and week 5 is the last week
 138 in which day \fId\fP occurs.
 139 Day 0 is a Sunday.
 140 .PP
 141 The \fItime\fP fields specify when, in the local time currently in effect,
 142 the change to the other time occurs.
 143 If omitted, the default is 02:00:00.
 144
 145 Here is an example for New Zealand,
 146 where the standard time (NZST) is 12 hours ahead of UTC,
 147 and daylight saving time (NZDT), 13 hours ahead of UTC,
 148 runs from the first Sunday in October to the third Sunday in March,
 149 and the changeovers happen at the default time of 02:00:00:
 150 .nf
 151
 152     TZ="NZST-12:00:00NZDT-13:00:00,M10.1.0,M3.3.0"
 153 .fi
 154 .PP
 155 The second format specifies that the timezone information should be read
 156 from a file:
 157 .sp
 158 .RS
 159 :[filespec]
 160 .RE
 161 .sp
 162 If the file specification \fIfilespec\fP is omitted, or its value cannot
 163 be interpreted, then Coordinated Universal Time (UTC) is used.
 164 If \fIfilespec\fP is given, it specifies another
 165 .BR tzfile (5)-format
 166 file to read the timezone information from.
 167 If \fIfilespec\fP does not begin with a \(aq/\(aq, the file specification is
 168 relative to the system timezone directory.  If the colon is omitted each
 169 of the above \fBTZ\fP formats will be tried.
 170 .PP
 171 Here's an example, once more for New Zealand:
 172 .nf
 173
 174     TZ=":Pacific/Auckland"
 175 .fi
 176 .SH ENVIRONMENT
 177 .TP
 178 .B TZ
 179 If this variable is set its value takes precedence over the system
 180 configured timezone.
 181 .TP
 182 .B TZDIR
 183 If this variable is set its value takes precedence over the system
 184 configured timezone database directory path.
 185 .SH FILES
 186 .TP
 187 .B /etc/localtime
 188 The system timezone file.
 189 .TP
 190 .B /usr/share/zoneinfo/
 191 The system timezone database directory.
 192 .TP
 193 .B /usr/share/zoneinfo/posixrules
 194 When a TZ string includes a dst timezone without anything following it,
 195 then this file is used for the start/end rules.
 196 It is in the
 197 .BR tzfile "(5) format."
 198 By default, the zoneinfo Makefile hard links it to the
 199 .IR America/New_York " tzfile."
 200 .PP
 201 Above are the current standard file locations, but they are
 202 configurable when glibc is compiled.
 203 .SH CONFORMING TO
 204 SVr4, POSIX.1-2001, 4.3BSD.
 205 .SH NOTES
 206 Note that the variable \fIdaylight\fP does not indicate that daylight
 207 saving time applies right now.
 208 It used to give the number of some
 209 algorithm (see the variable \fItz_dsttime\fP in
 210 .BR gettimeofday (2)).
 211 It has been obsolete for many years but is required by SUSv2.
 212 .LP
 213 4.3BSD had a function
 214 .BI "char *timezone(" zone ", " dst )
 215 that returned the
 216 name of the timezone corresponding to its first argument (minutes
 217 West of UTC).
 218 If the second argument was 0, the standard name was used,
 219 otherwise the daylight saving time version.
 220 .SH SEE ALSO
 221 .BR date (1),
 222 .BR gettimeofday (2),
 223 .BR time (2),
 224 .BR ctime (3),
 225 .BR getenv (3),
 226 .BR tzfile (5)
 227 .SH COLOPHON
 228 This page is part of release 3.79 of the Linux
 229 .I man-pages
 230 project.
 231 A description of the project,
 232 information about reporting bugs,
 233 and the latest version of this page,
 234 can be found at
 235 \%http://www.kernel.org/doc/man\-pages/.