1% File src/library/base/man/timezones.Rd 2% Part of the R package, https://www.R-project.org 3% Copyright 1995-2021 R Core Team 4% Distributed under GPL 2 or later 5 6\name{timezones} 7\alias{Sys.timezone} 8\alias{OlsonNames} 9\alias{timezone} 10\alias{timezones} 11\alias{time zone} 12\alias{time zones} 13\alias{TZ} 14\alias{TZDIR} 15\alias{.sys.timezone} 16 17\title{Time Zones} 18\description{ 19 Information about time zones in \R. \code{Sys.timezone} returns 20 the name of the current time zone. 21} 22 23\usage{ 24Sys.timezone(location = TRUE) 25 26OlsonNames(tzdir = NULL) 27} 28 29\arguments{ 30 \item{location}{logical: defunct: ignored, with a warning for false values.} 31 32 \item{tzdir}{The time-zone database to be used: the default is to try 33 known locations until one is found.} 34} 35 36\details{ 37 Time zones are a system-specific topic, but these days almost all \R 38 platforms use similar underlying code, used by Linux, macOS, Solaris, 39 AIX and FreeBSD, and installed with \R on Windows. (Unfortunately 40 there are many system-specific errors in the implementations.) It is 41 possible to use the \R sources' version of the code on Unix-alikes as 42 well as on Windows: this is the default for macOS and recommended for 43 Solaris. 44 45 It should be possible to set the current time zone via the environment 46 variable \env{TZ}: see the section on \sQuote{Time zone names} for 47 suitable values. \code{Sys.timezone()} will return the value of 48 \env{TZ} if set initially (and on some OSes it is always set), 49 otherwise it will try to retrieve from the OS a value which if set for 50 \env{TZ} would give the initial time zone. (\sQuote{Initially} means 51 before any time-zone functions are used: if \env{TZ} is being set to 52 override the OS setting or if the \sQuote{try} does not get this 53 right, it should be set before the \R process is started or (probably 54 early enough) in file \code{\link{.Rprofile}}). 55 56 %% glibc silently uses UTC but uses the invalid name as the 57 %% abbreviations. tzcode as used by R warns and uses UTC. 58 If \env{TZ} is set but invalid, most platforms default to \samp{UTC}, 59 the time zone colloquially known as \samp{GMT} (see 60 \url{https://en.wikipedia.org/wiki/Coordinated_Universal_Time}). 61 (Some but not all platforms will give a warning for invalid values.) 62 If it is unset or empty the \emph{system} time zone is used (the one 63 returned by \code{Sys.timezone}). 64 65 %% arguably, 'railway time' in the UK in 1840 was earliest. 66 Time zones did not come into use until the middle of the nineteenth 67 century and were not widely adopted until the twentieth, and 68 \emph{daylight saving time} (DST, also known as \emph{summer time}) 69 was first introduced in the early twentieth century, most widely in 70 1916. Over the last 100 years places have changed their affiliation 71 between major time zones, have opted out of (or in to) DST in various 72 years or adopted DST rule changes late or not at all. (The UK 73 experimented with DST throughout 1971, only.) In a few countries (one 74 is the Irish Republic) it is the summer time which is the 75 \sQuote{standard} time and a different name is used in winter. And 76 there can be multiple changes during a year, for example for Ramadan. 77 78 A quite common system implementation of \code{POSIXct} is as signed 79 32-bit integers and so only goes back to the end of 1901: on such 80 systems \R assumes that dates prior to that are in the same time zone 81 as they were in 1902. Most of the world had not adopted time zones by 82 1902 (so used local \sQuote{mean time} based on longitude) but for a 83 few places there had been time-zone changes before then. 64-bit 84 representations are becoming common; unfortunately on some 64-bit OSes 85 the database information is 32-bit and so only available for the range 86 1901--2038, and incompletely for the end years. 87 88 As from \R 3.5.0, when a time zone location is first found in a 89 session, its value is cached in object \code{.sys.timezone} in the 90 base environment. 91} 92 93\value{ 94 \code{Sys.timezone} returns an OS-specific character string, possibly 95 \code{NA} or an empty string (which on some OSes means \samp{UTC}). 96 This will be a location such as \code{"Europe/London"} if one can be 97 ascertained. 98 99 A time zone region may be known by several names: for example 100 \samp{"Europe/London"} is also known as \samp{GB}, \samp{GB-Eire}, 101 \samp{Europe/Belfast}, \samp{Europe/Guernsey}, 102 \samp{Europe/Isle_of_Man} and \samp{Europe/Jersey}. A few regions 103 are also known by a summary of their time zone, 104 e.g.\sspace{}\samp{PST8PDT} is an alias for 105 \samp{America/Los_Angeles}. 106 107 \code{OlsonNames} returns a character vector, see the examples for 108 typical cases. It may have an attribute \code{"Version"}, something 109 like \samp{"2020a"}. 110} 111 112\section{Time zone names}{ 113 Names \code{"UTC"} and its synonym \code{"GMT"} are accepted on all 114 platforms. 115 116 Where OSes describe their valid time zones can be obscure. The help 117 for the C function \code{tzset} can be helpful, but it can also be 118 inaccurate. There is a cumbersome POSIX specification (listed under 119 environment variable \env{TZ} at 120 \url{https://pubs.opengroup.org/onlinepubs/9699919799/basedefs/V1_chap08.html#tag_08}), 121 which is often at least partially supported, but there are other more 122 user-friendly ways to specify time zones. 123 124 Almost all \R platforms make use of a time-zone database originally 125 compiled by Arthur David Olson and now managed by IANA, in which the 126 preferred way to refer to a time zone is by a location (typically of a 127 city), e.g., \code{Europe/London}, \code{America/Los_Angeles}, 128 \code{Pacific/Easter} within a \sQuote{time zone region}. Some 129 traditional designations are also allowed such as \code{EST5EDT} or 130 \code{GB}. (Beware that some of these designations may not be what 131 you expect: in particular \code{EST} is a time zone used in Canada 132 \emph{without} daylight saving time, and not \code{EST5EDT} nor 133 (Australian) Eastern Standard Time.) The designation can also be an 134 optional colon prepended to the path to a file giving complied zone 135 information (and the examples above are all files in a system-specific 136 location). See \url{https://data.iana.org/time-zones/tz-link.html} 137 for more details and references. By convention, regions with a unique 138 time-zone history since 1970 have specific names in the database, but 139 those with different earlier histories may not. Each time zone has 140 one or two (the second for DST) \emph{abbreviations} used when 141 formatting times. 142 143 The abbreviations used have changed over the years: for example France 144 used \samp{PMT} (\sQuote{Paris Mean Time}) from 1891 to 1911 then 145 \samp{WET/WEST} up to 1940 and \samp{CET/CEST} from 1946. (In almost 146 all time zones the abbreviations have been stable since 1970.) The 147 POSIX standard allows only one or two abbreviations per time zone, so 148 you may see the current abbreviation(s) used for older times. 149 150 For some time zones abbreviations are like \samp{-03} and 151 \samp{+0845}: this is done when there is no official abbreviation. 152 (Negative values are behind (West of) UTC, as for the \code{"\%z"} 153 format for \code{\link{strftime}}.) 154 155 The function \code{OlsonNames} returns the time-zone names known to 156 the currently selected Olson/IANA database. The system-specific 157 location in the file system varies, 158 e.g.\sspace{}\file{/usr/share/zoneinfo} (Linux, macOS, FreeBSD), 159 \file{/usr/share/lib/zoneinfo} (Solaris, AIX), \ldots. It is likely 160 that there is a file named something like \file{zone1970.tab} or 161 (older) \file{zone.tab} under that directory listing the locations 162 known as time-zone names (but not for example \code{EST5EDT}). See 163 also \url{https://en.wikipedia.org/wiki/Zone.tab}. 164 165 Where \R was configured with option \option{--with-internal-tzcode} 166 (the default on Windows: recommended on Solaris), the database at 167 \code{file.path(R.home("share"), "zoneinfo")} is used by default: file 168 \file{VERSION} in that directory states the version. That option is 169 also the default on macOS but there whichever is more recent of the 170 system database at \file{/var/db/timezone/zoneinfo} and that 171 distributed with \R is used by default. Environment variable 172 \env{TZDIR} can be used to point to a different \file{zoneinfo} 173 database: value \code{"internal"} indicates the database from the 174 \R sources and \code{"macOS"} indicates the system database. (Setting 175 either of those values would not be recognized by other software using 176 \env{TZDIR}.) 177 178 Setting \env{TZDIR} is also supported by the native services on some 179 OSes, e.g.\sspace{}Linux using \code{glibc} except in secure modes. 180 %% But not Linux with musl 181 182 Time zones given by name (\emph{via} environment variable \env{TZ}, in 183 \code{tz} arguments to functions such as \code{\link{as.POSIXlt}} and 184 perhaps the system time zone) are loaded from the currently selected 185 \file{zoneinfo} database. 186#ifdef windows 187 188 An attempt is made (once only per session) to map Windows' idea of the 189 current time zone to a location, following a version of 190 \url{http://unicode.org/repos/cldr/trunk/common/supplemental/windowsZones.xml} 191 with additional values deduced from the Windows Registry and documentation. 192 It can be overridden by setting the \env{TZ} environment variable 193 before any date-times are used in the session. 194#endif 195 196 Most platforms support time zones of the form \samp{Etc/GMT+n} and 197 \samp{Etc/GMT-n} (possibly also without prefix \samp{Etc/}), which 198 assume a fixed offset from UTC (hence no DST). Contrary to some 199 expectations (but consistent with names such as \samp{PST8PDT}), 200 negative offsets are times ahead of (east of) UTC, positive offsets 201 are times behind (west of) UTC. 202 203 Immediately prior to the advent of legislated time zones, most people 204 used time based on their longitude (or that of a nearby town), known 205 as \sQuote{Local Mean Time} and abbreviated as \samp{LMT} in the 206 databases: in many countries that was codified with a specific name 207 before the switch to a standard time. For example, Paris codified its 208 LMT as \sQuote{Paris Mean Time} in 1891 (to be used throughout 209 mainland France) and switched to \samp{GMT+0} in 1911. 210 211 %% it is a ksh script so could well pop up elsewhere. 212 Some systems (notably Linux) have a \command{tzselect} command which 213 allows the interactive selection of a supported time zone name. On 214 systems using \command{systemd} (notably Linux), the OS command 215 \command{timedatectl list-timezones} will list all available time zone 216 names. 217} 218 219\section{Warning}{ 220%% glibc and macOS have _POSIX_TZNAME_MAX and define it as 6. 221%% Earlier versions of R's code assumed 10, and it was discovered 222%% that some implemntations did not abbreviate unusual names, thereby 223%% exceeding this. 224%% Olson's tzcode has a limit of 255 and does not check: this has been 225%% corrected in R's copy. 226%% sysconf(_SC_TZNAME_MAX) might allow it to be checked: 227%% that gives 27 on macOS. However, seems it is dynamic on glibc. 228 There is a system-specific upper limit on the number of bytes in 229 (abbreviated) time-zone names which can be as low as 6 (as required by 230 POSIX). Some OSes allow the setting of time zones with names which 231 exceed their limit, and that can crash the \R session. 232 233 \code{OlsonNames} tries to find an Olson database in known locations. 234 It might not succeed (when it returns an empty vector with a warning) 235 and even if it does it might not locate the database used by the 236 date-time code linked into \R. Fortunately names are added rarely 237 and most databases are pretty complete. 238} 239 240\note{ 241 Since 2007 there has been considerable disruption over changes to the 242 timings of the DST transitions, originally aimed at energy 243 conservation. These often have short notice and time-zone databases 244 may not be up to date. (Morocco in 2013 announced a change to the end 245 of DST at \emph{a days} notice, and in 2015 North Korea gave imprecise 246 information about a change a week in advance.) 247 248 On platforms with case-insensitive file systems, time zone names will be 249 case-insensitive. They may or may not be on other platforms and so, 250 for example, \code{"gmt"} is valid on some platforms and not on others. 251 252 Note that except where replaced, the operation of time zones is an OS 253 service, and even where replaced a third-party database is used and 254 can be updated (see the section on \sQuote{Time zone names}). 255 Incorrect results will never be an \R issue, so please ensure that you 256 have the courtesy not to blame \R for them. 257} 258% Unlike Tony Plate and John Pfuntner 259 260#ifdef unix 261\section{How the system time zone is found}{ 262 This section is of background interest for users of a Unix-alike, but 263 may help if an \code{NA} value is returned unexpectedly. 264 265 Commercial Unixen such as Solaris and AIX set \env{TZ}, so the value 266 when \R is started is used. 267 268 All other common platforms (Linux, macOS, *BSD) use similar schemes, 269 either derived from \code{tzcode} (currently distributed from 270 \url{https://www.iana.org/time-zones}) or independently coded 271 (\code{glibc}, \code{musl-libc}). Such systems read the time-zone 272 information from a file \file{localtime}, usually under \file{/etc} 273 (but possibly under \file{/usr/local/etc} or 274 \file{/usr/local/etc/zoneinfo}). As the usual Linux manual page for 275 \code{localtime} says 276 277 \sQuote{Because the time zone identifier is extracted from the symlink 278 target name of \file{/etc/localtime}, this file may not be a normal 279 file or hardlink.} 280 281 Nevertheless, some Linux distributions (including the one from which 282 that quote was taken) or sysadmins have chosen to copy a time-zone file 283 to \file{localtime}. For a non-symlink, the ultimate fallback is to 284 compare that file to all files in the time-zone database. 285 286 Some Linux platforms provide two other mechanisms which are tried in 287 turn before looking at \file{/etc/localtime}. 288 \itemize{ 289 \item \sQuote{Modern} Linux systems use \code{systemd} which 290 provides mechanisms to set and retrieve the time zone (amongst other 291 things). There is a command \command{timedatectl} to give details. 292 (Unfortunately RHEL/Centos 6.x are not \sQuote{modern}.) 293 294 \item Debian-derived systems since \emph{ca} 2007 have supplied a 295 file \file{/etc/timezone}. Its format is undocumented but 296 empirically it contains a single line of text naming the time zone. 297 } 298 In each case a sanity check is performed that the time-zone name is the 299 name of a file in the time-zone database. (The systems probably use 300 the time-zone file (symlinked to) \file{/etc/localtime}, but the 301 \code{Sys.timezone} code does not check that is the same as the named 302 file in the database. This is deliberate as they may be from 303 different dates.) 304} 305#endif 306 307\seealso{ 308 \code{\link{Sys.time}}, \code{\link{as.POSIXlt}}. 309 310 \url{https://en.wikipedia.org/wiki/Time_zone} and 311 \url{https://data.iana.org/time-zones/tz-link.html} 312 for extensive sets of links. 313 314 \url{https://data.iana.org/time-zones/theory.html} for the 315 \sQuote{rules} of the Olson/IANA database. 316} 317 318\examples{ 319Sys.timezone() 320 321str(OlsonNames()) ## typically close to six hundred names, 322## typically some acronyms/aliases such as "UTC", "NZ", "MET", "Eire", ..., but 323## mostly pairs (and triplets) such as "Pacific/Auckland" 324table(sl <- grepl("/", OlsonNames())) 325OlsonNames()[ !sl ] # the simple ones 326head(Osl <- strsplit(OlsonNames()[sl], "/")) 327(tOS1 <- table(vapply(Osl, `[[`, "", 1))) # Continents, countries, ... 328table(lengths(Osl))# most are pairs, some triplets 329str(Osl[lengths(Osl) >= 3])# "America" South and North ... 330} 331\keyword{utilities} 332\keyword{chron} 333