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.
This commit is contained in:
Paul Eggert
parent
c23c965bb9
commit
ca50981001
6 changed files with 70 additions and 49 deletions
|
|
@ -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:
|
||||
|
|
|
|||
10
etc/NEWS
10
etc/NEWS
|
|
@ -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
|
||||
|
|
|
|||
Loading…
Add table
Reference in a new issue