@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.
* 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
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
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
@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
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
@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})
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
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:
*** 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.
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
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
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:
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
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.
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);
`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
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