Skip to main content

get-universal-time, get-decoded-time

get-universal-time, get-decoded-time Function

Syntax:

get-universal-time ⟨no arguments⟩ → universal-time

get-decoded-time ⟨no arguments⟩

→ second, minute, hour, date, month, year, day, daylight-p, zone

Arguments and Values:

universal-time—a universal time.

second, minute, hour, date, month, year, day, daylight-p, zone—a decoded time.

Description:

get-universal-time returns the current time, represented as a universal time.

get-decoded-time returns the current time, represented as a decoded time.

Examples:

;; At noon on July 4, 1976 in Eastern Daylight Time. 
(get-decoded-time) → 0, 0, 12, 4, 7, 1976, 6, *true*, 5 
;; At exactly the same instant. 
(get-universal-time) → 2414332800 
;; Exactly five minutes later. 
(get-universal-time) → 2414333100 
;; The difference is 300 seconds (five minutes) 
(- \* \*\*) → 300

Affected By:

The time of day (i.e., the passage of time), the system clock’s ability to keep accurate time, and the accuracy of the system clock’s initial setting.

Exceptional Situations:

An error of type error might be signaled if the current time cannot be determined.

See Also:

decode-universal-time, encode-universal-time, Section 25.1.4 (Time)

Notes:

(get-decoded-time) ≡ (decode-universal-time (get-universal-time))

No implementation is required to have a way to verify that the time returned is correct. However, if an implementation provides a validity check (e.g., the failure to have properly initialized the system clock can be reliably detected) and that validity check fails, the implementation is strongly encouraged (but not required) to signal an error of type error (rather than, for example, returning a known-to-be-wrong value) that is correctable by allowing the user to interactively set the correct time.

Expanded Reference: get-universal-time, get-decoded-time​

Getting the current time as a universal time​

get-universal-time returns the current time as a single non-negative integer (seconds since midnight January 1, 1900 GMT).

(integerp (get-universal-time))
=> T

(> (get-universal-time) 0)
=> T

Getting the current time as decoded values​

get-decoded-time returns the current time as nine values: second, minute, hour, date, month, year, day-of-week, daylight-saving-time-p, and time-zone.

(multiple-value-bind (sec min hour day month year dow dst tz)
    (get-decoded-time)
  (stringp (format nil "~4D-~2,'0D-~2,'0D ~2,'0D:~2,'0D:~2,'0D"
                   year month day hour min sec)))
;; => T

Relationship between the two functions​

get-decoded-time is equivalent to calling decode-universal-time on the result of get-universal-time.

;; These are equivalent (modulo time passing between calls):
;; (get-decoded-time)
;; (decode-universal-time (get-universal-time))

Using universal time for timestamps​

Universal time is useful for recording timestamps in a compact format.

(let ((start (get-universal-time)))
  (sleep 1)
  (let ((elapsed (- (get-universal-time) start)))
    (>= elapsed 1)))
=> T