Commit ca509810 authored by Paul Eggert's avatar Paul Eggert
Browse files

Improve time zone documentation

* doc/lispref/os.texi (Time Zone Rules):
New section, mostly with material moved here from other sections.
* doc/emacs/cmdargs.texi (General Variables):
* doc/lispref/os.texi (Time Conversion, Time Parsing):
Xref new section.
* etc/NEWS, etc/PROBLEMS:
* lisp/org/org.el (org-timestamp-format):
* src/editfns.c (Fformat_time_string, Fdecode_time)
(Fencode_time, Fcurrent_time_string, Fcurrent_time_zone)
(Fset_time_zone_rule):
When documenting time zone rule strings, mention the TZ
environment variable in preference to mentioning the
sort-of-internal function set-time-zone-rule.
parent c23c965b
......@@ -634,8 +634,9 @@ to put temporary files (@pxref{Backup}). Emacs tries to use
@env{TMP}, then @env{TEMP}, and finally @file{c:/temp}.
@item TZ
@vindex TZ, environment variable
This specifies the current time zone and possibly also daylight
saving time information. On MS-DOS, if @env{TZ} is not set in the
This specifies the default time zone and possibly also daylight
saving time information. @xref{Time Zone Rules,,, elisp, The GNU
Emacs Lisp Reference Manual}. On MS-DOS, if @env{TZ} is not set in the
environment when Emacs starts, Emacs defines a default value as
appropriate for the country code returned by DOS@. On MS-Windows, Emacs
does not use @env{TZ} at all.
......
......@@ -19,6 +19,7 @@ terminal and the screen.
* System Environment:: Distinguish the name and kind of system.
* User Identification:: Finding the name and user id of the user.
* Time of Day:: Getting the current time.
* Time Zone Rules:: Rules for time zones and daylight saving time.
* Time Conversion:: Converting a time from numeric form to
calendrical data and vice versa.
* Time Parsing:: Converting a time from numeric form to text
......@@ -1262,7 +1263,7 @@ information may some day be added at the end.
The argument @var{time}, if given, specifies a time to format,
instead of the current time. The optional argument @var{zone}
defaults to the current time zone rule.
defaults to the current time zone rule. @xref{Time Zone Rules}.
@example
@group
......@@ -1299,26 +1300,9 @@ For example, if @var{time} is a number, @code{(time-to-seconds
or rounding errors occur.
@end defun
@defun current-time-zone &optional time zone
@cindex time zone, current
This function returns a list describing the time zone that the user is
in.
The value has the form @code{(@var{offset} @var{name})}. Here
@var{offset} is an integer giving the number of seconds ahead of Universal Time
(east of Greenwich). A negative value means west of Greenwich. The
second element, @var{name}, is a string giving the name of the time
zone. Both elements change when daylight saving time begins or ends;
if the user has specified a time zone that does not use a seasonal time
adjustment, then the value is constant through time.
If the operating system doesn't supply all the information necessary to
compute the value, the unknown elements of the list are @code{nil}.
The argument @var{time}, if given, specifies a time value to
analyze instead of the current time. The optional argument @var{zone}
defaults to the current time zone rule.
@end defun
@node Time Zone Rules
@section Time Zone Rules
@cindex time zone rules
@vindex TZ, environment variable
The default time zone is determined by the @env{TZ} environment
......@@ -1327,6 +1311,15 @@ to default to Universal Time with @code{(setenv "TZ" "UTC0")}. If
@env{TZ} is not in the environment, Emacs uses system wall clock time,
which is a platform-dependent default time zone.
The set of supported @env{TZ} strings is system-dependent. GNU and
many other systems support the tzdata database, e.g.,
@samp{"America/New_York"} specifies the time zone and daylight saving
time history for locations near New York City. GNU and most other
systems support POSIX-style @env{TZ} strings, e.g.,
@samp{"EST+5EDT,M4.1.0/2,M10.5.0/2"} specifies the rules used in New
York from 1987 through 2006. All systems support the string
@samp{"UTC0"} meaning Universal Time.
@cindex time zone rule
Functions that convert to and from local time accept an optional
@dfn{time zone rule} argument, which specifies the conversion's time
......@@ -1337,6 +1330,29 @@ If it is @code{t}, the conversion uses Universal Time. If it is
a string, the conversion uses the time zone rule equivalent to setting
@env{TZ} to that string.
@defun current-time-zone &optional time zone
@cindex time zone, current
This function returns a list describing the time zone that the user is
in.
The value has the form @code{(@var{offset} @var{abbr})}. Here
@var{offset} is an integer giving the number of seconds ahead of Universal Time
(east of Greenwich). A negative value means west of Greenwich. The
second element, @var{abbr}, is a string giving an abbreviation for the
time zone, e.g., @samp{"CST"} for China Standard Time or for
U.S. Central Standard Time. Both elements can change when daylight
saving time begins or ends; if the user has specified a time zone that
does not use a seasonal time adjustment, then the value is constant
through time.
If the operating system doesn't supply all the information necessary to
compute the value, the unknown elements of the list are @code{nil}.
The argument @var{time}, if given, specifies a time value to
analyze instead of the current time. The optional argument @var{zone}
defaults to the current time zone rule.
@end defun
@node Time Conversion
@section Time Conversion
@cindex calendrical information
......@@ -1361,8 +1377,8 @@ as traditional Gregorian years do; for example, the year number
@defun decode-time &optional time zone
This function converts a time value into calendrical information. If
you don't specify @var{time}, it decodes the current time, and similarly
@var{zone} defaults to the current time zone rule. The return
value is a list of nine elements, as follows:
@var{zone} defaults to the current time zone rule. @xref{Time Zone Rules}.
The return value is a list of nine elements, as follows:
@example
(@var{seconds} @var{minutes} @var{hour} @var{day} @var{month} @var{year} @var{dow} @var{dst} @var{utcoff})
......@@ -1409,6 +1425,7 @@ to stand for years above 1900, or years above 2000, you must alter them
yourself before you call @code{encode-time}.
The optional argument @var{zone} defaults to the current time zone rule.
@xref{Time Zone Rules}.
In addition to the usual time zone rule values, it can also be a list
(as you would get from @code{current-time-zone}) or an integer (as
from @code{decode-time}), applied without any further alteration for
......@@ -1452,8 +1469,8 @@ corresponding time value.
This function converts @var{time} (or the current time, if
@var{time} is omitted) to a string according to
@var{format-string}. The conversion uses the time zone rule @var{zone}
(or the current time zone rule, if omitted). The argument
@var{format-string}. The conversion uses the time zone rule @var{zone}, which
defaults to the current time zone rule. @xref{Time Zone Rules}. The argument
@var{format-string} may contain @samp{%}-sequences which say to
substitute parts of the time. Here is a table of what the
@samp{%}-sequences mean:
......
......@@ -1778,11 +1778,11 @@ quotation marks.
*** Time conversion functions now accept an optional ZONE argument
that specifies the time zone rules for conversion. ZONE is omitted or
nil for Emacs local time, t for Universal Time, 'wall' for system wall
clock time, or a string as in 'set-time-zone-rule' for a time zone
rule. The affected functions are 'current-time-string',
'current-time-zone', 'decode-time', and 'format-time-string'. The
function 'encode-time', which already accepted a simple time zone rule
argument, has been extended to accept all the new forms.
clock time, or a string as in the TZ environment variable. The
affected functions are 'current-time-string', 'current-time-zone',
'decode-time', and 'format-time-string'. The function 'encode-time',
which already accepted a simple time zone rule argument, has been
extended to accept all the new forms.
*** Incompatible change in the third argument of 'format-time-string'.
Previously, any non-nil argument was interpreted as specifying Universal Time.
......
......@@ -2220,11 +2220,11 @@ month names with consistent widths for some locales on some versions
of Windows. This is caused by a deficiency in the underlying system
library function.
** Problems with set-time-zone-rule function
** Non-US time zones.
The function set-time-zone-rule gives incorrect results for many
non-US timezones. This is due to over-simplistic handling of
daylight savings switchovers by the Windows libraries.
Many non-US time zones are implemented incorrectly. This is due to
over-simplistic handling of daylight savings switchovers by the
Windows libraries.
** Files larger than 4GB report wrong size in a 32-bit Windows build
......
......@@ -22674,7 +22674,7 @@ time-range, if possible.
 
The optional ZONE is omitted or nil for Emacs local time, t for
Universal Time, `wall' for system wall clock time, or a string as in
`set-time-zone-rule' for a time zone rule."
the TZ environment variable."
(format-time-string
format
(apply 'encode-time
......
......@@ -1969,10 +1969,10 @@ DEFUN ("format-time-string", Fformat_time_string, Sformat_time_string, 1, 3, 0,
doc: /* Use FORMAT-STRING to format the time TIME, or now if omitted.
TIME is specified as (HIGH LOW USEC PSEC), as returned by
`current-time' or `file-attributes'. The obsolete form (HIGH . LOW)
is also still accepted.
The optional ZONE is omitted or nil for Emacs local time, t for
Universal Time, `wall' for system wall clock time, or a string as in
`set-time-zone-rule' for a time zone rule.
is also still accepted. The optional ZONE is omitted or nil for Emacs
local time, t for Universal Time, `wall' for system wall clock time,
or a string as in the TZ environment variable.
The value is a copy of FORMAT-STRING, but with certain constructs replaced
by text that describes the specified date and time in TIME:
......@@ -2086,7 +2086,7 @@ as from `current-time' and `file-attributes', or nil to use the
current time. The obsolete form (HIGH . LOW) is also still accepted.
The optional ZONE is omitted or nil for Emacs local time, t for
Universal Time, `wall' for system wall clock time, or a string as in
`set-time-zone-rule' for a time zone rule.
the TZ environment variable.
The list has the following nine members: SEC is an integer between 0
and 60; SEC is 60 for a leap second, which only some operating systems
......@@ -2151,9 +2151,9 @@ DEFUN ("encode-time", Fencode_time, Sencode_time, 6, MANY, 0,
This is the reverse operation of `decode-time', which see.
The optional ZONE is omitted or nil for Emacs local time, t for
Universal Time, `wall' for system wall clock time, or a string as in
`set-time-zone-rule' for a time zone rule. It can also be a list (as
from `current-time-zone') or an integer (as from `decode-time')
applied without consideration for daylight saving time.
the TZ environment variable. It can also be a list (as from
`current-time-zone') or an integer (as from `decode-time') applied
without consideration for daylight saving time.
You can pass more than 7 arguments; then the first six arguments
are used as SECOND through YEAR, and the *last* argument is used as ZONE.
......@@ -2213,7 +2213,7 @@ but this is considered obsolete.
The optional ZONE is omitted or nil for Emacs local time, t for
Universal Time, `wall' for system wall clock time, or a string as in
`set-time-zone-rule' for a time zone rule. */)
the TZ environment variable. */)
(Lisp_Object specified_time, Lisp_Object zone)
{
time_t value = lisp_seconds_argument (specified_time);
......@@ -2290,7 +2290,7 @@ instead of using the current time. The argument should have the form
`current-time' and from `file-attributes'. SPECIFIED-TIME can also
have the form (HIGH . LOW), but this is considered obsolete.
Optional second arg ZONE is omitted or nil for the local time zone, or
a string as in `set-time-zone-rule'.
a string as in the TZ environment variable.
Some operating systems cannot provide all this information to Emacs;
in this case, `current-time-zone' returns a list containing nil for
......@@ -2331,8 +2331,11 @@ the data it can't find. */)
DEFUN ("set-time-zone-rule", Fset_time_zone_rule, Sset_time_zone_rule, 1, 1, 0,
doc: /* Set the Emacs local time zone using TZ, a string specifying a time zone rule.
If TZ is nil or `wall', use system wall clock time. If TZ is t, use
Universal Time. If TZ is an integer, treat it as in `encode-time'.
If TZ is nil or `wall', use system wall clock time; this differs from
the usual Emacs convention where nil means current local time. If TZ
is t, use Universal Time. If TZ is an integer, treat it as in
`encode-time'.
Instead of calling this function, you typically want something else.
To temporarily use a different time zone rule for just one invocation
......
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment