* 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 UTC
-(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
variable. @xref{System Environment}. For example, you can tell Emacs
-to default to universal time with @code{(setenv "TZ" "UTC0")}. If
+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
If it is @code{t}, the conversion uses Universal Time. If it is
@code{wall}, the conversion uses the system wall clock time. If it is
a string, the conversion uses the time zone rule equivalent to setting
-@env{TZ} to that string.
+@env{TZ} to that string. If it is an integer @var{offset}, the
+conversion uses a fixed time zone with the given offset and a numeric
+abbreviation on POSIX-compatible platforms and an unspecified abbreviation
+on MS-Windows. If it is a list (@var{offset} @var{abbr}), where
+@var{offset} is an integer number of seconds east of Universal Time
+and @var{abbr} is a string, the conversion uses a fixed time zone with
+the given offset and abbreviation.
+
+@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
Many 32-bit operating systems are limited to system times containing
32 bits of information in their seconds component; these systems
-typically handle only the times from 1901-12-13 20:45:52 UTC through
-2038-01-19 03:14:07 UTC@. However, 64-bit and some 32-bit operating
+typically handle only the times from 1901-12-13 20:45:52 through
+2038-01-19 03:14:07 Universal Time. However, 64-bit and some 32-bit operating
systems have larger seconds components, and can represent times far in
the past or future.
@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})
@item dst
@code{t} if daylight saving time is effect, otherwise @code{nil}.
@item utcoff
-An integer indicating the UTC offset in seconds, i.e., the number of
+An integer indicating the Universal Time offset in seconds, i.e., the number of
seconds east of Greenwich.
@end table
yourself before you call @code{encode-time}.
The optional argument @var{zone} defaults to the current time zone rule.
-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
-daylight saving time.
+@xref{Time Zone Rules}.
If you pass more than seven arguments to @code{encode-time}, the first
six are used as @var{seconds} through @var{year}, the last argument is
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:
representation of numbers, instead of the ordinary decimal digits. This
is allowed with most letters, all the ones that output numbers.
-If @var{universal} is non-@code{nil}, that means to describe the time as
-Universal Time; @code{nil} means describe it using what Emacs believes
-is the local time zone (see @code{current-time-zone}).
-
This function uses the C library function @code{strftime}
(@pxref{Formatting Calendar Time,,, libc, The GNU C Library Reference
Manual}) to do most of the work. In order to communicate with that