あるファイルにアクセスしてそのバッファに変更を加え、その間にディスク上のファイル自体が変更されたとします。このとき、バッファを保存すると、ファイルへの変更内容が上書きされてしまいます。場合によってはこれが意図した動作であることもありますが、通常は貴重な情報が失われることになります。そのため、Emacsはファイルを保存する前に、以下に説明する関数を用いてファイルの更新日時を確認します。（ファイルの更新日時の確認方法については、ファイル属性を参照してください。）
この関数は、buffer（デフォルトでは current-buffer）が記録している訪問済みファイルの更新日時と、オペレーティングシステムが記録している実際のファイルの更新日時を比較します。Emacsがファイルを訪問または保存して以降、他のプロセスがファイルに書き込みを行っていない限り、両者は一致するはずです。
この関数は、直近の実際の変更時刻とEmacsが記録している変更時刻が一致する場合はtを、そうでない場合はnilを返します。また、バッファに記録された直近の変更時刻がない場合、すなわちvisited-file-modtimeが0を返す場合には、tを返します。
visited-file-modtime が 0
以外の値を返す場合でも、ファイルを参照していないバッファに対しては常に t
を返します。例えば、dired バッファに対しては常に t
を返します。存在しない、あるいは最初から存在しなかったファイルを参照しているバッファに対しては t
を返し、ファイルが削除されたファイル参照バッファに対しては nil を返します。
この関数は、現在のバッファが参照しているファイルの最終変更時刻の記録をクリアします。これにより、次にこのバッファを保存しようとする際に、ファイルの変更時刻の不一致に関するエラーが発生しなくなります。
この関数は、set-visited-file-name
や、変更済みファイルの上書きを回避するための通常のチェックを行うべきではないその他の例外的な箇所で呼び出されます。
この関数は、現在のバッファに記録されている最終ファイル更新日時を、Lispのタイムスタンプとして返します（Time of Dayを参照）。
バッファに最終変更時刻が記録されていない場合、この関数は0を返します。例えば、バッファがファイルを参照していない場合や、clear-visited-file-modtimeによって時刻が明示的にクリアされた場合などにこのケースが発生します。ただし、visited-file-modtimeはファイル以外の一部のバッファに対してもタイムスタンプを返す点に注意してください。例えば、ディレクトリを一覧表示するDiredバッファでは、Diredによって記録されたそのディレクトリの最終変更時刻を返します。
バッファが存在しないファイルを参照している場合、この関数は-1を返します。
この関数は、バッファの参照ファイルの最終変更時刻のレコードを、time が nil でない場合は time
で指定された値に、そうでない場合は参照ファイルの最終変更時刻に更新します。
time が nil でも visited-file-modtime が返す整数フラグでもない場合、それは Lisp
の時刻値であるはずです（Time of Day を参照）。
この関数は、バッファがファイルから正常に読み込まれなかった場合や、既知の無害な理由でファイル自体が変更された場合に有用です。
この関数は、ファイルがバッファのテキストよりも新しい場合に、ファイル filename を参照するバッファを変更しようとした後、ユーザーにどのように対処すべきかを尋ねるために使用されます。Emacs がこれを検知できるのは、ディスク上のファイルの更新日時が最後の保存時刻よりも新しく、かつ内容が変更されているためです。これは、おそらく他のプログラムがファイルを変更したことを意味します。
ユーザーの回答に応じて、関数が正常に戻り、その場合はバッファの変更が続行されるか、あるいはデータ (filename) を伴う file-supersession エラーが通知され、その場合は提案されたバッファの変更は許可されません。
この関数は、適切なタイミングでEmacsによって自動的に呼び出されます。この関数が存在するのは、これを再定義することでEmacsをカスタマイズできるようにするためです。標準的な定義については、ファイル userlock.el を参照してください。
ファイルロックのファイルロック機構も参照してください。