---

I.2.1.1 Lisp Timestamp

Many functions return Lisp timestamp values that count seconds, and that can represent absolute time by counting seconds since the epoch of 1970-01-01 00:00:00 UTC.

Traditionally Lisp timestamps were integer pairs. Things have changed and now programs ordinarily should not depend on the current default form. You can use the time-convert function to convert it to the needed form.

Three Forms of Lisp Timestamp Values

Each of these represents a number of seconds.

integer

simplest, but cannot represent subsecond timestamps

pair of integers

‘(ticks . hz)’ This represents ‘ticks/hz’ seconds. A common value for ‘hz’ is 1000000000, for a nanosecond-resolution clock.

list of 4 integers

‘(high low micro pico)’

• This represents the number of seconds using the formula:
  • ‘high * 2**16 + low + micro * 10**-6 + pico * 10**-12’
• ‘low’ – 0 ≤ low < 65536
• ‘micro’ – 0 ≤ micro < 1000000
• ‘pico’ – 0 ≤ pico ≤ 1000000 (multiple of 1000s)

More General Time Value Formats

Function arguments accept a more general time value format.

• ‘NIL’ representing the current time
• Lisp timestamp
• Truncated Lisp timestamp; missing values are zero;
  • ‘(high low micro)’ or
  • ‘(high low)’
• floating-point number representing seconds

Conversion of Lisp Timestamp Values into Calendrical and Other Forms

Time values can be converted to and from calendrical and other forms. Some of these conversions rely on operating system functions that limit the range of possible time values.

• human-readable string – format-time-string
• Lisp timestamp – time-convert
• other forms – decode-time, float-time