\HeaderA{timezones}{Time Zones}{timezones}
\aliasA{Sys.timezone}{timezones}{Sys.timezone}
\aliasA{time zone}{timezones}{time zone}
\aliasA{time zones}{timezones}{time zones}
\aliasA{timezone}{timezones}{timezone}
\keyword{utilities}{timezones}
\keyword{chron}{timezones}
\begin{Description}\relax
Information about time zones in \R.  \code{Sys.timezone} returns
the current time zone.
\end{Description}
\begin{Usage}
\begin{verbatim}
Sys.timezone()
\end{verbatim}
\end{Usage}
\begin{Details}\relax
Time zones are a system-specific topic, but as from \R{} 2.7.0 almost
all \R{} platforms use the same underlying code, used by Linux, Mac OS
X, Solaris, AIX, FreeBSD, Sun Java >= 1.4 and Tcl >= 8.5, and supplied
with \R{} on Windows.

It is not in general possible to retrieve the system's own name(s) for
the current timezone, but \code{Sys.timezone} will retrieve the name
it uses for the current time (and the name may differ depending on
whether daylight saving time is in effect).

On most platforms it is  possible to set the time zone via the
environment variable \env{TZ}: see the section on \sQuote{Time zone
names} for suitable values.

Note that the principal difficulty with time zones is their individual
history: over the last 100 years places have changed their affiliation
between major time zones, have opted out of (or in to) DST in
various years or adopted rule changes late or not at all.  This often
involves tiny administative units in the US/Canada: Iowa had 23
different implementations of DST in the 1960's!

Time zones did not come into use until the second half of the
nineteenth century, and DST was first introduced in the early
twentieth century, most widely during the First World War (in 1916).
The most common implementation of \code{POSIXct} is a signed 32-bit
integers and so only goes back to the end of 1901: on such systems \R{}
assumes that dates prior to that are in the same time zone as they
were in 1902.
\end{Details}
\begin{Value}
\code{Sys.timezone} returns an OS-specific character string, possibly
an empty string.  Typically this is an abbreviation such as \code{"EST"}.
\end{Value}
\begin{Section}{Time zone names}
Where OSes describe their valid time zones can be obscure.  The help
for the C function \code{tzset} can be helpful, but it
can also be inaccurate.  There is a cumbersome POSIX specification
(listed under environment variable \env{TZ} at
\url{http://www.opengroup.org/onlinepubs/009695399/basedefs/xbd_chap08.html}),
which is often at least partially supported, but there usually are
other more user-friendly ways to specify timezones.

Many systems make use of a timezone database compiled by Arthur Olson,
in which the preferred way to refer to a time zone by a location
(typically of a city) e.g. \code{Europe/London},
\code{America/Los\_Angeles}, \code{Pacific/Easter}.  Some traditional
designations are also allowed such as \code{EST5EDT} or
\code{GB}.  (Beware that some of these designations may not be what you
think: in particular \code{EST} is a time zone used in Canada
\emph{without} daylight savings time, and not \code{EST5EDT} nor
(Australian) Eastern Standard Time.)  The designation can also be an
optional colon prepended to the path to a file giving complied zone
information (and the examples above are all files in a system-specific
location).  See \url{http://www.twinsun.com/tz/tz-link.htm} for more
details and references.

For most Unix-alikes use the Olson databases.  The 
system-specific default location in the file system varies, e.g. 
\file{/usr/share/zoneinfo}, \file{/usr/etc/zoneinfo},
\file{/usr/lib/zoneinfo} or \file{/usr/share/lib/zoneinfo}.
\end{Section}
\begin{Note}\relax
There is currently (2007/8) considerable disruption over changes to
the timings of the DST transitions, aimed at energy conservation.
These often have short notice and time zone databases may not be up to
date (even if the OS has been updated recently).

Note that except on Windows, the operation of time zones is an OS
service, and even on Windows a third-party database is used and can be
updated (see the section on \sQuote{Time zone names}).  Incorrect
results will never be an \R{} issue, so please ensure that you have the
courtesy not to blame \R{} for them.
\end{Note}
\begin{SeeAlso}\relax
\code{\LinkA{Sys.time}{Sys.time}}, \code{\LinkA{as.POSIXlt}{as.POSIXlt}}.

\url{http://en.wikipedia.org/wiki/Time_zone} and
\url{http://www.twinsun.com/tz/tz-link.htm} for extensive sets of links.
\end{SeeAlso}
\begin{Examples}
\begin{ExampleCode}
Sys.timezone()
\end{ExampleCode}
\end{Examples}

