Next: Time Zone Rules, Previous: User Identification, Up: System Interface [Contents][Index]

### 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 four integers `(sec-high sec-low microsec picosec)`. This represents the number of seconds from the epoch (January 1, 1970 at 00:00 UTC), using the formula: high * 2**16 + low + micro * 10**âˆ’6 + pico * 10**âˆ’12. The return value of `current-time` represents time using this form, as do the timestamps in the return values of other functions such as `file-attributes` (see Definition of file-attributes). In some cases, functions may return two- or three-element lists, with omitted microsec and picosec components defaulting to zero.

Function arguments, e.g., the time argument to `current-time-string`, accept a more-general time value format, which can be a list of integers as above, or a single number for seconds since the epoch, or `nil` for the current time. You can convert a time value into a human-readable string using `current-time-string` and `format-time-string`, into a list of integers using `seconds-to-time`, and into other forms using `decode-time` and `float-time`. These functions are described in the following sections.

Function: current-time-string &optional time zone

  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, if given, specifies a time to format, instead of the current time. The optional argument zone defaults to the current time zone rule. See Time Zone Rules.

      (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

  This function returns the current time as a floating-point number of seconds since the epoch. The optional argument time, if given, specifies a time 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.

  `time-to-seconds` is an alias for this function.

Function: seconds-to-time time

  This function converts a time value to list-of-integer form. For example, if time is a number, `(time-to-seconds (seconds-to-time time))` equals the number unless overflow or rounding errors occur.

Next: Time Zone Rules, Previous: User Identification, Up: System Interface [Contents][Index]