Suppose that you visit a file and make changes in its buffer, and meanwhile the file itself is changed on disk. At this point, saving the buffer would overwrite the changes in the file. Occasionally this may be what you want, but usually it would lose valuable information. Emacs therefore checks the file's modification time using the functions described below before saving the file. (See File Attributes, for how to examine a file's modification time.)
This function compares what buffer (by default, the current-buffer) has recorded for the modification time of its visited file against the actual modification time of the file as recorded by the operating system. The two should be the same unless some other process has written the file since Emacs visited or saved it.
The function returns
tif the last actual modification time and Emacs's recorded modification time are the same,
nilotherwise. It also returns
tif the buffer has no recorded last modification time, that is if
visited-file-modtimewould return zero.
It always returns
tfor buffers that are not visiting a file, even if
visited-file-modtimereturns a non-zero value. For instance, it always returns
tfor dired buffers. It returns
tfor buffers that are visiting a file that does not exist and never existed, but
nilfor file-visiting buffers whose file has been deleted.
This function clears out the record of the last modification time of the file being visited by the current buffer. As a result, the next attempt to save this buffer will not complain of a discrepancy in file modification times.
This function is called in
set-visited-file-nameand other exceptional places where the usual test to avoid overwriting a changed file should not be done.
This function returns the current buffer's recorded last file modification time, as a list of the form
(high low microsec picosec
). (This is the same format that
file-attributesuses to return time values; see File Attributes.)
If the buffer has no recorded last modification time, this function returns zero. This case occurs, for instance, if the buffer is not visiting a file or if the time has been explicitly cleared by
clear-visited-file-modtime. Note, however, that
visited-file-modtimereturns a list for some non-file buffers too. For instance, in a Dired buffer listing a directory, it returns the last modification time of that directory, as recorded by Dired.
For a new buffer visiting a not yet existing file, high is −1 and low is 65535, that is, 2**16 − 1.
This function updates the buffer's record of the last modification time of the visited file, to the value specified by time if time is not
nil, and otherwise to the last modification time of the visited file.
If time is neither
nilnor zero, it should have the form
(high low microsec picosec
), the format used by
current-time(see Time of Day).
This function is useful if the buffer was not read from the file normally, or if the file itself has been changed for some known benign reason.
This function is used to ask a user how to proceed after an attempt to modify an buffer visiting file filename when the file is newer than the buffer text. Emacs detects this because the modification time of the file on disk is newer than the last save-time of the buffer. This means some other program has probably altered the file.
Depending on the user's answer, the function may return normally, in which case the modification of the buffer proceeds, or it may signal a
file-supersessionerror with data
), in which case the proposed buffer modification is not allowed.
This function is called automatically by Emacs on the proper occasions. It exists so you can customize Emacs by redefining it. See the file userlock.el for the standard definition.
See also the file locking mechanism in File Locks.