File Notifications (GNU Emacs Lisp Reference Manual)

40.20 ファイル変更による通知

いくつかのオペレーティングシステムはファイル変更にたいするファイルシステムの監視をサポートします。正しく設定されていれば、Emacsはinotify、kqueue、gfilenotify、w32notifyのようなライブラリーを静的にリンクします。これらのライブラリーによりローカルマシン上でのファイルシステムの監視が有効になります。

リモートマシン上のファイルシステムの監視も可能です。Remote Files in The GNU Emacs Manualを参照してください。これはEmacsにリンク済みのライブラリーのいずれかに依存する訳ではありません。

通知されたファイル変更によりこれらすべてのライブラリーは異なるイベントを発行するので、Emacsは一意な参照を提供するライブラリーfilenotifyを提供しています。ファイル通知を受け取りたいLispプログラムは、ネイティブのライブラリーよりこのライブラリーを優先する必要があります:

Function: file-notify-add-watch file flags callback

fileに関するファイルシステムイベントの監視を追加する。これはfileに関するファイルシステムイベントがEmacsに報告されるように取り計らう。

リターン値は追加された監視ディスクリプター(descriptor)。タイプは背景にあるライブラリーに依存しており、以下の例に示すとおり整数とみなすことはできない。比較にはequalを使用すること。

何らかの理由によりfileが監視不可能なら、この関数はエラーfile-notify-errorをシグナルする。

マウントされたファイルシステムでファイル変更を監視できないことがある。これはこの関数により検出されないので、非nilのリターン値がfileの変更の通知を保証するものではない。

flagsは何を監視するかセットするためのコンディションのリスト。以下のシンボルを含めることができる:

change: ファイル変更を監視。
attribute-change: パーミッションや変更時刻のようなファイル属性の変更を監視。

fileがディレクトリーならディレクトリー内のすべてのファイルの変更が通知される。これは再帰的に機能しない。

Emacsは何らかのイベント発生時には以下の形式のeventを単一の引数として関数callbackを呼び出す:

(descriptor action file [file1])

descriptorはこの関数がリターンするオブジェクトと同じ。actionはイベントを示し、以下のシンボルのいずれか:

created: fileが作成された。
deleted: fileが削除された。
changed: fileの内容が変更された。w32notifyライブラリーでは属性の変更でも同様に報告される。
renamed: fileがfile1にリネームされた。
attribute-changed: fileの属性が変更された。
stopped: 監視中のfileが削除された。

w32notifyライブラリーはattribute-changedイベントを報告しないことに注意。このライブラリーはパーミッションや変更時刻のようなファイル属性が何か変更された際にはchangedイベントを報告する。同じようにkqueueライブラリーでは、ディレクトリー監視時にはファイル属性変更の報告に信頼性がない。

stoppedイベントはファイル監視の停止を報告する。これはfile-notify-rm-watchの呼び出された(以下参照)、監視中のファイルが削除された、または背後にあるライブラリーから別のエラーが報告された可能性がある。

fileとfile1はイベントが報告されたファイルの名前。たとえば:

(require 'filenotify)
     ⇒ filenotify

(defun my-notify-callback (event)
  (message "Event %S" event))
     ⇒ my-notify-callback

(file-notify-add-watch
  "/tmp" '(change attribute-change) 'my-notify-callback)
     ⇒ 35025468

(write-region "foo" nil "/tmp/foo")
     ⇒ Event (35025468 created "/tmp/.#foo")
        Event (35025468 created "/tmp/foo")
        Event (35025468 changed "/tmp/foo")
        Event (35025468 deleted "/tmp/.#foo")

(write-region "bla" nil "/tmp/foo")
     ⇒ Event (35025468 created "/tmp/.#foo")
        Event (35025468 changed "/tmp/foo")
        Event (35025468 deleted "/tmp/.#foo")

(set-file-modes "/tmp/foo" (default-file-modes))
     ⇒ Event (35025468 attribute-changed "/tmp/foo")

アクションrenamedがリターンされるかどうかは使用する監視ライブラリーに依存する。それ以外ではdeletedとcreatedのアクションがランダムな順にリターンされる。

(rename-file "/tmp/foo" "/tmp/bla")
     ⇒ Event (35025468 renamed "/tmp/foo" "/tmp/bla")

(delete-file "/tmp/bla")
     ⇒ Event (35025468 deleted "/tmp/bla")

Function: file-notify-rm-watch descriptor: descriptorに指定された既存のファイル監視を削除する。descriptorはfile-notify-add-watchがリターンしたオブジェクトであること。

Function: file-notify-valid-p descriptor

descriptorで指定された監視の有効性をチェックする。descriptorはfile-notify-add-watchがリターンしたオブジェクトであること。

監視するファイルやディレクトリーの削除や別の理由による監視スレッドの異常exitにより監視が無効になる可能性がある。file-notify-rm-watchの呼び出しで削除することにより監視も無効になる。

(make-directory "/tmp/foo")
     ⇒ Event (35025468 created "/tmp/foo")

(setq desc
      (file-notify-add-watch
        "/tmp/foo" '(change) 'my-notify-callback))
     ⇒ 11359632

(file-notify-valid-p desc)
     ⇒ t

(write-region "bla" nil "/tmp/foo/bla")
     ⇒ Event (11359632 created "/tmp/foo/.#bla")
        Event (11359632 created "/tmp/foo/bla")
        Event (11359632 changed "/tmp/foo/bla")
        Event (11359632 deleted "/tmp/foo/.#bla")

;; ディレクトリーのファイル削除では監視は無効にならない
(delete-file "/tmp/foo/bla")
     ⇒ Event (11359632 deleted "/tmp/foo/bla")

(write-region "bla" nil "/tmp/foo/bla")
     ⇒ Event (11359632 created "/tmp/foo/.#bla")
        Event (11359632 created "/tmp/foo/bla")
        Event (11359632 changed "/tmp/foo/bla")
        Event (11359632 deleted "/tmp/foo/.#bla")

;; ディレクトリー削除により監視は無効になる
;; 別の監視ディスクリプターからイベントが到着
(delete-directory "/tmp/foo" 'recursive)
     ⇒ Event (35025468 deleted "/tmp/foo")
        Event (11359632 deleted "/tmp/foo/bla")
        Event (11359632 deleted "/tmp/foo")
        Event (11359632 stopped "/tmp/foo")

(file-notify-valid-p desc)
     ⇒ nil