Skip to main content

file-write-date

file-write-date Function

Syntax:

file-write-date pathspec → date

Arguments and Values:

pathspec—a pathname designator .

date—a universal time or nil.

Description:

Returns a universal time representing the time at which the file specified by pathspec was last written (or created), or returns nil if such a time cannot be determined.

Examples:

(with-open-file (s "noel.text" 
		   :direction :output :if-exists :error) 
  (format s "~&Dear Santa,~2%I was good this year. ~ 
Please leave lots of toys.~2%Love, Sue~ 
 
 
~2%attachments: milk, cookies~%") 
  (truename s)) 
→ #P"CUPID:/susan/noel.text" 
(with-open-file (s "noel.text") 
  (file-write-date s)) 
→ 2902600800

Affected By:

The host computer’s file system.

Exceptional Situations:

An error of type file-error is signaled if pathspec is wild.

An error of type file-error is signaled if the file system cannot perform the requested operation.

See Also:

Section 25.1.4.2 (Universal Time), Section 19.1.2 (Pathnames as Filenames)

Expanded Reference: file-write-date​

Getting the modification time of a file​

file-write-date returns the time a file was last written as a universal time, or nil if it cannot be determined.

(with-open-file (s "/tmp/cl-fwd-test.txt" :direction :output
                   :if-exists :supersede)
  (write-string "test data" s))

(file-write-date "/tmp/cl-fwd-test.txt")
;; => 3952684800  ; a universal time; implementation-dependent

Decoding the write date​

The returned universal time can be decoded with decode-universal-time to get human-readable date components.

(let ((date (file-write-date "/tmp/cl-fwd-test.txt")))
  (when date
    (multiple-value-bind (sec min hour day month year)
        (decode-universal-time date)
      (format nil "~4D-~2,'0D-~2,'0D ~2,'0D:~2,'0D:~2,'0D"
              year month day hour min sec))))
;; => "2025-04-15 10:30:00"  ; actual value depends on when file was written

Comparing file dates​

file-write-date is useful for determining which of two files is newer.

(let ((date1 (file-write-date "/tmp/cl-fwd-test.txt"))
      (date2 (file-write-date "/tmp/cl-fwd-test.txt")))
  (when (and date1 date2)
    (= date1 date2)))
=> T

Accepts streams and pathnames​

Like other file functions, it accepts strings, pathnames, and streams.

(with-open-file (s "/tmp/cl-fwd-test.txt")
  (integerp (file-write-date s)))
=> T