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 .TH TZSET 3  2001-11-13 "" "Linux Programmer's Manual"
  30 .SH NAME
  31 tzset, tzname, timezone, daylight \- initialize time conversion information
  32 .SH SYNOPSIS
  33 .nf
  34 .B #include <time.h>
  35 .sp
  36 .B void tzset (void);
  37 .sp
  38 .BI "extern char *" tzname [2];
  39 .BI "extern long " timezone ;
  40 .BI "extern int " daylight ;
  41 .fi
  42 .SH DESCRIPTION
  43 The \fBtzset()\fP function initializes the \fItzname\fP variable from the
  44 TZ environment variable.  This function is automatically called by the
  45 other time conversion functions that depend on the time zone.
  46 In a SysV-like environment it will also set the variables \fItimezone\fP
  47 (seconds West of GMT) and \fIdaylight\fP (0 if this time zone does not
  48 have any daylight savings time rules, nonzero if there is a time during
  49 the year when daylight savings time applies).
  50 .PP
  51 If the TZ variable does not appear in the environment, the \fItzname\fP
  52 variable is initialized with the best approximation of local wall clock
  53 time, as specified by the
  54 .BR tzfile (5)-format
  55 file \fIlocaltime\fP
  56 found in the system timezone directory (see below).
  57 (One also often sees
  58 .I /etc/localtime
  59 used here, a symlink to the right file in the system timezone directory.)
  60 .PP
  61 If the TZ variable does appear in the environment but its value is NULL
  62 or its value cannot be interpreted using any of the formats specified
  63 below, Coordinated Universal Time (UTC) is used.
  64 .PP
  65 The value of TZ can be one of three formats.  The first format is used
  66 when there is no daylight saving time in the local time zone:
  67 .sp
  68 .RS
  69 .I std offset
  70 .RE
  71 .sp
  72 The \fIstd\fP string specifies the name of the time zone and must be
  73 three or more alphabetic characters.  The \fIoffset\fP string immediately
  74 follows \fIstd\fP and specifies the time value to be added to the local
  75 time to get Coordinated Universal Time (UTC).  The \fIoffset\fP is positive
  76 if the local time zone is west of the Prime Meridian and negative if it is
  77 east.  The hour must be between 0 and 24, and the minutes and seconds
  78 0 and 59.
  79 .PP
  80 The second format is used when there is daylight saving time:
  81 .sp
  82 .RS
  83 .I std offset dst [offset],start[/time],end[/time]
  84 .RE
  85 .sp
  86 There are no spaces in the specification.  The initial \fIstd\fP and
  87 \fIoffset\fP specify the standard time zone, as described above.  The
  88 \fIdst\fP string and \fIoffset\fP specify the name and offset for the
  89 corresponding daylight savings time zone.  If the offset is omitted,
  90 it defaults  to one hour ahead of standard time.
  91 .PP
  92 The \fIstart\fP field specifies when daylight savings time goes into
  93 effect and the \fIend\fP field specifies when the change is made back to
  94 standard time.  These fields may have the following formats:
  95 .TP
  96 J\fIn\fP
  97 This specifies the Julian day with \fIn\fP between 1 and 365.  February
  98 29 is never counted even in leap years.
  99 .TP
 100 .I n
 101 This specifies the Julian day with \fIn\fP between 1 and 365.  February
 102 29 is counted in leap years.
 103 .TP
 104 M\fIm\fP.\fIw\fP.\fId\fP
 105 This specifies day \fId\fP (0 <= \fId\fP <= 6) of week \fIw\fP
 106 (1 <= \fIw\fP <= 5) of month \fIm\fP (1 <= \fIm\fP <= 12).  Week 1 is
 107 the first week in which day \fId\fP occurs and week 5 is the last week
 108 in which day \fId\fP occurs.  Day 0 is a Sunday.
 109 .PP
 110 The \fItime\fP fields specify when, in the local time currently in effect,
 111 the change to the other time occurs.  If omitted, the default is 02:00:00.
 112 .PP
 113 The third format specifies that the time zone information should be read
 114 from a file:
 115 .sp
 116 .RS
 117 :[filespec]
 118 .RE
 119 .sp
 120 If the file specification \fIfilespec\fP is omitted, the time zone
 121 information is read from the file
 122 .I localtime
 123 in the system timezone directory, which nowadays usually is
 124 .IR /usr/share/zoneinfo .
 125 This file is in
 126 .BR tzfile (5)
 127 format.  If \fIfilespec\fP is given, it specifies another
 128 .BR tzfile (5)-format
 129 file to read the time zone information from.  If
 130 \fIfilespec\fP does not begin with a `/', the file specification is
 131 relative to the system timezone directory.
 132 .SH FILES
 133 The system time zone directory used depends on the (g)libc version.
 134 Libc4 and libc5 use
 135 .IR /usr/lib/zoneinfo ,
 136 and, since libc-5.4.6,
 137 when this doesn't work, will try
 138 .IR /usr/share/zoneinfo .
 139 Glibc2 will use the environment variable TZDIR, when that exists.
 140 Its default depends on how it was installed, but normally is
 141 .IR /usr/share/zoneinfo .
 142 .LP
 143 This timezone directory contains the files
 144 .nf
 145 localtime      local time zone file
 146 posixrules     rules for POSIX-style TZ's
 147 .fi
 148 .LP
 149 Often
 150 .I /etc/localtime
 151 is a symlink to the file
 152 .I localtime
 153 or to the correct time zone file in the system time zone directory.
 154 .SH "CONFORMING TO"
 155 SVID 3, POSIX, BSD 4.3
 156 .SH NOTES
 157 Note that the variable \fIdaylight\fP does not indicate that daylight
 158 savings time applies right now. It used to give the number of some
 159 algorithm (see the variable \fItz_dsttime\fP in
 160 .BR gettimeofday (2)).
 161 It has been obsolete for many years but is required by SUSv2.
 162 .LP
 163 BSD4.3 had a routine \fIchar *timezone(zone,dst)\fP that returned the
 164 name of the time zone corresponding to its first argument (minutes
 165 West of GMT). If the second argument was 0, the standard name was used,
 166 otherwise the daylight savings time version.
 167 .SH "SEE ALSO"
 168 .BR date (1),
 169 .BR gettimeofday (2),
 170 .BR time (2),
 171 .BR ctime (3),
 172 .BR getenv (3),
 173 .BR tzfile (5)