38.5 Time of Day

This section explains how to determine the current time and time zone.

Most of these functions represent time as a list of either four integers, (sec-high sec-low microsec picosec), or of three integers, (sec-high sec-low microsec), or of two integers, (sec-high sec-low). The integers sec-high and sec-low give the high and low bits of an integer number of seconds. This integer, high * 2**16 + low, is the number of seconds from the epoch (0:00 January 1, 1970 UTC) to the specified time. The third list element microsec, if present, gives the number of microseconds from the start of that second to the specified time. Similarly, the fourth list element picosec, if present, gives the number of picoseconds from the start of that microsecond to the specified time.

The return value of current-time represents time using four integers, as do the timestamps in the return value of file-attributes (see Definition of file-attributes). In function arguments, e.g., the time-value argument to current-time-string, two-, three-, and four-integer lists are accepted. You can convert times from the list representation into standard human-readable strings using current-time-string, or to other forms using the decode-time and format-time-string functions documented in the following sections.

Function: current-time-string &optional time-value

This function returns the current time and date as a human-readable string. The format does not vary for the initial part of the string, which contains the day of week, month, day of month, and time of day in that order: the number of characters used for these fields is always the same, so you can reliably use substring to extract them. You should count characters from the beginning of the string rather than from the end, as the year might not have exactly four digits, and additional information may some day be added at the end.

The argument time-value, if given, specifies a time to format (represented as a list of integers), instead of the current time.

(current-time-string)
     ⇒ "Wed Oct 14 22:21:05 1987"

Function: current-time

This function returns the current time, represented as a list of four integers (sec-high sec-low microsec picosec). These integers have trailing zeros on systems that return time with lower resolutions. On all current machines picosec is a multiple of 1000, but this may change as higher-resolution clocks become available.

Function: float-time &optional time-value

This function returns the current time as a floating-point number of seconds since the epoch. The optional argument time-value, if given, specifies a time (represented as a list of integers) to convert instead of the current time.

Warning: Since the result is floating point, it may not be exact. Do not use this function if precise time stamps are required.

Function: current-time-zone &optional time-value

This function returns a list describing the time zone that the user is in.

The value has the form (offset name). Here 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, 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 nil.

The argument time-value, if given, specifies a time (represented as a list of integers) to analyze instead of the current time.

The current time zone is determined by the TZ environment variable. See System Environment. For example, you can tell Emacs to use universal time with (setenv "TZ" "UTC0"). If TZ is not in the environment, Emacs uses a platform-dependent default time zone.