lisp/filenotify.el

   1 ;;; filenotify.el --- watch files for changes on disk  -*- lexical-binding:t -*-
   2
   3 ;; Copyright (C) 2013-2015 Free Software Foundation, Inc.
   4
   5 ;; Author: Michael Albinus <michael.albinus@gmx.de>
   6
   7 ;; This file is part of GNU Emacs.
   8
   9 ;; GNU Emacs is free software: you can redistribute it and/or modify
  10 ;; it under the terms of the GNU General Public License as published by
  11 ;; the Free Software Foundation, either version 3 of the License, or
  12 ;; (at your option) any later version.
  13
  14 ;; GNU Emacs is distributed in the hope that it will be useful,
  15 ;; but WITHOUT ANY WARRANTY; without even the implied warranty of
  16 ;; MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  17 ;; GNU General Public License for more details.
  18
  19 ;; You should have received a copy of the GNU General Public License
  20 ;; along with GNU Emacs.  If not, see <http://www.gnu.org/licenses/>.
  21
  22 ;;; Commentary
  23
  24 ;; This package is an abstraction layer from the different low-level
  25 ;; file notification packages `inotify', `kqueue', `gfilenotify' and
  26 ;; `w32notify'.
  27
  28 ;;; Code:
  29
  30 (defconst file-notify--library
  31   (cond
  32    ((featurep 'inotify) 'inotify)
  33    ((featurep 'kqueue) 'kqueue)
  34    ((featurep 'gfilenotify) 'gfilenotify)
  35    ((featurep 'w32notify) 'w32notify))
  36   "Non-nil when Emacs has been compiled with file notification support.
  37 The value is the name of the low-level file notification package
  38 to be used for local file systems.  Remote file notifications
  39 could use another implementation.")
  40
  41 (defvar file-notify-descriptors (make-hash-table :test 'equal)
  42   "Hash table for registered file notification descriptors.
  43 A key in this hash table is the descriptor as returned from
  44 `inotify', `kqueue', `gfilenotify', `w32notify' or a file name
  45 handler.  The value in the hash table is a list
  46
  47   (DIR (FILE . CALLBACK) (FILE . CALLBACK) ...)
  48
  49 Several values for a given DIR happen only for `inotify', when
  50 different files from the same directory are watched.")
  51
  52 (defun file-notify--rm-descriptor (descriptor &optional what)
  53   "Remove DESCRIPTOR from `file-notify-descriptors'.
  54 DESCRIPTOR should be an object returned by `file-notify-add-watch'.
  55 If it is registered in `file-notify-descriptors', a stopped event is sent.
  56 WHAT is a file or directory name to be removed, needed just for `inotify'."
  57   (let* ((desc (if (consp descriptor) (car descriptor) descriptor))
  58          (file (if (consp descriptor) (cdr descriptor)))
  59          (registered (gethash desc file-notify-descriptors))
  60          (dir (car registered)))
  61
  62     (when (and (consp registered) (or (null what) (string-equal dir what)))
  63       ;; Send `stopped' event.
  64       (dolist (entry (cdr registered))
  65         (funcall (cdr entry)
  66                  `(,descriptor stopped
  67                    ,(or (and (stringp (car entry))
  68                              (expand-file-name (car entry) dir))
  69                         dir))))
  70
  71       ;; Modify `file-notify-descriptors'.
  72       (if (not file)
  73           (remhash desc file-notify-descriptors)
  74         (setcdr registered
  75                 (delete (assoc file (cdr registered)) (cdr registered)))
  76         (if (null (cdr registered))
  77             (remhash desc file-notify-descriptors)
  78           (puthash desc registered file-notify-descriptors))))))
  79
  80 ;; This function is used by `inotify', `kqueue', `gfilenotify' and
  81 ;; `w32notify' events.
  82 ;;;###autoload
  83 (defun file-notify-handle-event (event)
  84   "Handle file system monitoring event.
  85 If EVENT is a filewatch event, call its callback.  It has the format
  86
  87   (file-notify (DESCRIPTOR ACTIONS FILE [FILE1-OR-COOKIE]) CALLBACK)
  88
  89 Otherwise, signal a `file-notify-error'."
  90   (interactive "e")
  91   ;;(message "file-notify-handle-event %S" event)
  92   (if (and (eq (car event) 'file-notify)
  93            (>= (length event) 3))
  94       (funcall (nth 2 event) (nth 1 event))
  95     (signal 'file-notify-error
  96             (cons "Not a valid file-notify event" event))))
  97
  98 ;; Needed for `inotify' and `w32notify'.  In the latter case, COOKIE is nil.
  99 (defvar file-notify--pending-event nil
 100   "A pending file notification events for a future `renamed' action.
 101 It is a form ((DESCRIPTOR ACTION FILE [FILE1-OR-COOKIE]) CALLBACK).")
 102
 103 (defun file-notify--event-file-name (event)
 104   "Return file name of file notification event, or nil."
 105   (directory-file-name
 106    (expand-file-name
 107     (or  (and (stringp (nth 2 event)) (nth 2 event)) "")
 108     (car (gethash (car event) file-notify-descriptors)))))
 109
 110 ;; Only `gfilenotify' could return two file names.
 111 (defun file-notify--event-file1-name (event)
 112   "Return second file name of file notification event, or nil.
 113 This is available in case a file has been moved."
 114   (and (stringp (nth 3 event))
 115        (directory-file-name
 116         (expand-file-name
 117          (nth 3 event) (car (gethash (car event) file-notify-descriptors))))))
 118
 119 ;; Cookies are offered by `inotify' only.
 120 (defun file-notify--event-cookie (event)
 121   "Return cookie of file notification event, or nil.
 122 This is available in case a file has been moved."
 123   (nth 3 event))
 124
 125 ;; `inotify' returns the same descriptor when the file (directory)
 126 ;; uses the same inode.  We want to distinguish, and apply a virtual
 127 ;; descriptor which make the difference.
 128 (defun file-notify--descriptor (desc file)
 129   "Return the descriptor to be used in `file-notify-*-watch'.
 130 For `gfilenotify' and `w32notify' it is the same descriptor as
 131 used in the low-level file notification package."
 132   (if (and (natnump desc) (eq file-notify--library 'inotify))
 133       (cons desc
 134             (and (stringp file)
 135                  (car (assoc
 136                        (file-name-nondirectory file)
 137                        (gethash desc file-notify-descriptors)))))
 138     desc))
 139
 140 ;; The callback function used to map between specific flags of the
 141 ;; respective file notifications, and the ones we return.
 142 (defun file-notify-callback (event)
 143   "Handle an EVENT returned from file notification.
 144 EVENT is the cadr of the event in `file-notify-handle-event'
 145 \(DESCRIPTOR ACTIONS FILE [FILE1-OR-COOKIE])."
 146   (let* ((desc (car event))
 147          (registered (gethash desc file-notify-descriptors))
 148          (actions (nth 1 event))
 149          (file (file-notify--event-file-name event))
 150          file1 callback pending-event stopped)
 151
 152     ;; Make actions a list.
 153     (unless (consp actions) (setq actions (cons actions nil)))
 154
 155     ;; Loop over registered entries.  In fact, more than one entry
 156     ;; happens only for `inotify'.
 157     (dolist (entry (cdr registered))
 158
 159       ;; Check, that event is meant for us.
 160       (unless (setq callback (cdr entry))
 161         (setq actions nil))
 162
 163       ;; Loop over actions.  In fact, more than one action happens only
 164       ;; for `inotify' and `kqueue'.
 165       (dolist (action actions)
 166
 167         ;; Send pending event, if it doesn't match.
 168         (when (and file-notify--pending-event
 169                    ;; The cookie doesn't match.
 170                    (not (eq (file-notify--event-cookie
 171                              (car file-notify--pending-event))
 172                             (file-notify--event-cookie event)))
 173                    (or
 174                     ;; inotify.
 175                     (and (eq (nth 1 (car file-notify--pending-event))
 176                              'moved-from)
 177                          (not (eq action 'moved-to)))
 178                     ;; w32notify.
 179                     (and (eq (nth 1 (car file-notify--pending-event))
 180                              'renamed-from)
 181                          (not (eq action 'renamed-to)))))
 182           (setq pending-event file-notify--pending-event
 183                 file-notify--pending-event nil)
 184           (setcar (cdar pending-event) 'deleted))
 185
 186         ;; Map action.  We ignore all events which cannot be mapped.
 187         (setq action
 188               (cond
 189                ((memq action
 190                       '(attribute-changed changed created deleted renamed))
 191                 action)
 192                ((memq action '(moved rename))
 193                 (setq file1 (file-notify--event-file1-name event))
 194                 'renamed)
 195                ((eq action 'ignored)
 196                 (setq stopped t actions nil))
 197                ((memq action '(attrib link)) 'attribute-changed)
 198                ((memq action '(create added)) 'created)
 199                ((memq action '(modify modified write)) 'changed)
 200                ((memq action '(delete delete-self move-self removed)) 'deleted)
 201                ;; Make the event pending.
 202                ((memq action '(moved-from renamed-from))
 203                 (setq file-notify--pending-event
 204                       `((,desc ,action ,file ,(file-notify--event-cookie event))
 205                         ,callback))
 206                 nil)
 207                ;; Look for pending event.
 208                ((memq action '(moved-to renamed-to))
 209                 (if (null file-notify--pending-event)
 210                     'created
 211                   (setq file1 file
 212                         file (file-notify--event-file-name
 213                               (car file-notify--pending-event)))
 214                   ;; If the source is handled by another watch, we
 215                   ;; must fire the rename event there as well.
 216                   (when (not (equal (file-notify--descriptor desc file1)
 217                                     (file-notify--descriptor
 218                                      (caar file-notify--pending-event)
 219                                      (file-notify--event-file-name
 220                                       file-notify--pending-event))))
 221                     (setq pending-event
 222                           `((,(caar file-notify--pending-event)
 223                              renamed ,file ,file1)
 224                             ,(cadr file-notify--pending-event))))
 225                   (setq file-notify--pending-event nil)
 226                   'renamed))))
 227
 228         ;; Apply pending callback.
 229         (when pending-event
 230           (setcar
 231            (car pending-event)
 232            (file-notify--descriptor
 233             (caar pending-event)
 234             (file-notify--event-file-name file-notify--pending-event)))
 235           (funcall (cadr pending-event) (car pending-event))
 236           (setq pending-event nil))
 237
 238         ;; Check for stopped.
 239         ;;(message "file-notify-callback %S %S" file registered)
 240         (setq
 241          stopped
 242          (or
 243           stopped
 244           (and
 245            (memq action '(deleted renamed))
 246            (= (length (cdr registered)) 1)
 247            (string-equal
 248             (file-name-nondirectory file)
 249             (or (file-name-nondirectory (car registered))
 250                 (car (cadr registered)))))))
 251
 252         ;; Apply callback.
 253         (when (and action
 254                    (or
 255                     ;; If there is no relative file name for that watch,
 256                     ;; we watch the whole directory.
 257                     (null (nth 0 entry))
 258                     ;; File matches.
 259                     (string-equal
 260                      (nth 0 entry) (file-name-nondirectory file))
 261                     ;; File1 matches.
 262                     (and (stringp file1)
 263                          (string-equal
 264                           (nth 0 entry) (file-name-nondirectory file1)))))
 265           (if file1
 266               (funcall
 267                callback
 268                `(,(file-notify--descriptor desc file) ,action ,file ,file1))
 269             (funcall
 270              callback
 271              `(,(file-notify--descriptor desc file) ,action ,file)))))
 272
 273       ;; Modify `file-notify-descriptors'.
 274       (when stopped
 275         (file-notify--rm-descriptor
 276          (file-notify--descriptor desc file) file)))))
 277
 278 ;; `kqueue', `gfilenotify' and `w32notify' return a unique descriptor
 279 ;; for every `file-notify-add-watch', while `inotify' returns a unique
 280 ;; descriptor per inode only.
 281 (defun file-notify-add-watch (file flags callback)
 282   "Add a watch for filesystem events pertaining to FILE.
 283 This arranges for filesystem events pertaining to FILE to be reported
 284 to Emacs.  Use `file-notify-rm-watch' to cancel the watch.
 285
 286 The returned value is a descriptor for the added watch.  If the
 287 file cannot be watched for some reason, this function signals a
 288 `file-notify-error' error.
 289
 290 FLAGS is a list of conditions to set what will be watched for.  It can
 291 include the following symbols:
 292
 293   `change'           -- watch for file changes
 294   `attribute-change' -- watch for file attributes changes, like
 295                         permissions or modification time
 296
 297 If FILE is a directory, `change' watches for file creation or
 298 deletion in that directory.  This does not work recursively.
 299
 300 When any event happens, Emacs will call the CALLBACK function passing
 301 it a single argument EVENT, which is of the form
 302
 303   (DESCRIPTOR ACTION FILE [FILE1])
 304
 305 DESCRIPTOR is the same object as the one returned by this function.
 306 ACTION is the description of the event.  It could be any one of the
 307 following:
 308
 309   `created'           -- FILE was created
 310   `deleted'           -- FILE was deleted
 311   `changed'           -- FILE has changed
 312   `renamed'           -- FILE has been renamed to FILE1
 313   `attribute-changed' -- a FILE attribute was changed
 314   `stopped'           -- watching FILE has been stopped
 315
 316 FILE is the name of the file whose event is being reported."
 317   ;; Check arguments.
 318   (unless (stringp file)
 319     (signal 'wrong-type-argument `(,file)))
 320   (setq file (expand-file-name file))
 321   (unless (and (consp flags)
 322                (null (delq 'change (delq 'attribute-change (copy-tree flags)))))
 323     (signal 'wrong-type-argument `(,flags)))
 324   (unless (functionp callback)
 325     (signal 'wrong-type-argument `(,callback)))
 326
 327   (let* ((handler (find-file-name-handler file 'file-notify-add-watch))
 328          (dir (directory-file-name
 329                (if (file-directory-p file)
 330                    file
 331                  (file-name-directory file))))
 332         desc func l-flags registered entry)
 333
 334     (unless (file-directory-p dir)
 335       (signal 'file-notify-error `("Directory does not exist" ,dir)))
 336
 337     (if handler
 338         ;; A file name handler could exist even if there is no local
 339         ;; file notification support.
 340         (setq desc (funcall
 341                     handler 'file-notify-add-watch dir flags callback))
 342
 343       ;; Check, whether Emacs has been compiled with file notification
 344       ;; support.
 345       (unless file-notify--library
 346         (signal 'file-notify-error
 347                 '("No file notification package available")))
 348
 349       ;; Determine low-level function to be called.
 350       (setq func
 351             (cond
 352              ((eq file-notify--library 'inotify) 'inotify-add-watch)
 353              ((eq file-notify--library 'kqueue) 'kqueue-add-watch)
 354              ((eq file-notify--library 'gfilenotify) 'gfile-add-watch)
 355              ((eq file-notify--library 'w32notify) 'w32notify-add-watch)))
 356
 357       ;; Determine respective flags.
 358       (if (eq file-notify--library 'gfilenotify)
 359           (setq l-flags (append '(watch-mounts send-moved) flags))
 360         (when (memq 'change flags)
 361           (setq
 362            l-flags
 363            (cond
 364             ((eq file-notify--library 'inotify)
 365              '(create delete delete-self modify move-self move))
 366             ((eq file-notify--library 'kqueue)
 367              '(delete write extend rename))
 368             ((eq file-notify--library 'w32notify)
 369              '(file-name directory-name size last-write-time)))))
 370         (when (memq 'attribute-change flags)
 371           (push (cond
 372                  ((eq file-notify--library 'inotify) 'attrib)
 373                  ((eq file-notify--library 'kqueue) 'attrib)
 374                  ((eq file-notify--library 'w32notify) 'attributes))
 375                 l-flags)))
 376
 377       ;; Call low-level function.
 378       (setq desc (funcall func dir l-flags 'file-notify-callback)))
 379
 380     ;; Modify `file-notify-descriptors'.
 381     (setq file (unless (file-directory-p file) (file-name-nondirectory file))
 382           desc (if (consp desc) (car desc) desc)
 383           registered (gethash desc file-notify-descriptors)
 384           entry `(,file . ,callback))
 385     (unless (member entry (cdr registered))
 386       (puthash desc `(,dir ,entry . ,(cdr registered)) file-notify-descriptors))
 387
 388     ;; Return descriptor.
 389     (file-notify--descriptor desc file)))
 390
 391 (defun file-notify-rm-watch (descriptor)
 392   "Remove an existing watch specified by its DESCRIPTOR.
 393 DESCRIPTOR should be an object returned by `file-notify-add-watch'."
 394   (let* ((desc (if (consp descriptor) (car descriptor) descriptor))
 395          (file (if (consp descriptor) (cdr descriptor)))
 396          (registered (gethash desc file-notify-descriptors))
 397          (dir (car registered))
 398          (handler (and (stringp dir)
 399                        (find-file-name-handler dir 'file-notify-rm-watch))))
 400
 401     (when (stringp dir)
 402       ;; Call low-level function.
 403       (when (or (not file)
 404                 (and (= (length (cdr registered)) 1)
 405                      (assoc file (cdr registered))))
 406         (condition-case nil
 407             (if handler
 408                 ;; A file name handler could exist even if there is no local
 409                 ;; file notification support.
 410                 (funcall handler 'file-notify-rm-watch descriptor)
 411
 412               (funcall
 413                (cond
 414                 ((eq file-notify--library 'inotify) 'inotify-rm-watch)
 415                 ((eq file-notify--library 'kqueue) 'kqueue-rm-watch)
 416                 ((eq file-notify--library 'gfilenotify) 'gfile-rm-watch)
 417                 ((eq file-notify--library 'w32notify) 'w32notify-rm-watch))
 418                desc))
 419           (file-notify-error nil)))
 420
 421       ;; Modify `file-notify-descriptors'.
 422       (file-notify--rm-descriptor descriptor))))
 423
 424 (defun file-notify-valid-p (descriptor)
 425   "Check a watch specified by its DESCRIPTOR.
 426 DESCRIPTOR should be an object returned by `file-notify-add-watch'."
 427   (let* ((desc (if (consp descriptor) (car descriptor) descriptor))
 428          (file (if (consp descriptor) (cdr descriptor)))
 429          (registered (gethash desc file-notify-descriptors))
 430          (dir (car registered))
 431          handler)
 432
 433     (when (stringp dir)
 434       (setq handler (find-file-name-handler dir 'file-notify-valid-p))
 435
 436       (and (or ;; It is a directory.
 437                (not file)
 438                ;; The file is registered.
 439                (assoc file (cdr registered)))
 440            (if handler
 441                ;; A file name handler could exist even if there is no
 442                ;; local file notification support.
 443                (funcall handler 'file-notify-valid-p descriptor)
 444              (funcall
 445               (cond
 446                ((eq file-notify--library 'inotify) 'inotify-valid-p)
 447                ((eq file-notify--library 'kqueue) 'kqueue-valid-p)
 448                ((eq file-notify--library 'gfilenotify) 'gfile-valid-p)
 449                ((eq file-notify--library 'w32notify) 'w32notify-valid-p))
 450               desc))
 451            t))))
 452
 453 ;; The end:
 454 (provide 'filenotify)
 455
 456 ;;; filenotify.el ends here