* files.texi (Magic File Names): Add file-notify-add-watch,

file-notify-rm-watch and file-notify-supported-p.  Move
file-remote-p down.

* errors.texi (Standard Errors): Add file-notify-error.

* os.texi (Desktop Notifications): Rename from Notifications.
(File Notifications): New node.

* elisp.texi (Top): Update menu for these changes.

diff --git a/doc/lispref/ChangeLog b/doc/lispref/ChangeLog
index 8b0dd6afa4e2adf3fd4136a9aef7d10fa3320927..342c7c57175c08b1618e63757592d8631f62dec8 100644 (file)
--- a/doc/lispref/ChangeLog
+++ b/doc/lispref/ChangeLog
@@ -1,3 +1,16 @@
+2013-07-22  Michael Albinus  <michael.albinus@gmx.de>
+
+       * files.texi (Magic File Names): Add file-notify-add-watch,
+       file-notify-rm-watch and file-notify-supported-p.  Move
+       file-remote-p down.
+
+       * errors.texi (Standard Errors): Add file-notify-error.
+
+       * os.texi (Desktop Notifications): Rename from Notifications.
+       (File Notifications): New node.
+
+       * elisp.texi (Top): Update menu for these changes.
+
 2013-07-19  Xue Fuqiao  <xfq.free@gmail.com>
 
        * windows.texi (Display Action Functions): Mention next-window.

diff --git a/doc/lispref/elisp.texi b/doc/lispref/elisp.texi
index 59bbdec02299302df7a2de453455bb5f5cf69715..4b8cc36b4eaef7b461db59c1a38bc05fcc1f033c 100644 (file)
--- a/doc/lispref/elisp.texi
+++ b/doc/lispref/elisp.texi
@@ -1482,7 +1482,8 @@ Operating System Interface
 * Batch Mode::              Running Emacs without terminal interaction.
 * Session Management::      Saving and restoring state with
                               X Session Management.
-* Notifications::           Desktop notifications.
+* Desktop Notifications::   Desktop notifications.
+* File Notifications::      File notifications.
 * Dynamic Libraries::       On-demand loading of support libraries.
 
 Starting Up Emacs

diff --git a/doc/lispref/errors.texi b/doc/lispref/errors.texi
index 3f3984e40d2b785cc15497bb06530a5b7dee8d85..264604470da6a283a9feda7b258add47ebe34dcb 100644 (file)
--- a/doc/lispref/errors.texi
+++ b/doc/lispref/errors.texi
@@ -123,6 +123,11 @@ This is a subcategory of @code{file-error}.  @xref{File Locks}.
 @item file-supersession
 This is a subcategory of @code{file-error}.  @xref{Modification Time}.
 
+@c filenotify.el
+@item file-notify-error
+This is a subcategory of @code{file-error}.  It happens, when a file
+could not be set to be watched for changes.  @xref{File Notifications}.
+
 @c net/ange-ftp.el
 @item ftp-error
 This is a subcategory of @code{file-error}, which results from

diff --git a/doc/lispref/files.texi b/doc/lispref/files.texi
index 951d55ac90fba6c1765f4a9571623ef9dd93db80..d2d327585c71c2cac37f4da17ad5cce50942019e 100644 (file)
--- a/doc/lispref/files.texi
+++ b/doc/lispref/files.texi
@@ -2772,16 +2772,18 @@ first, before handlers for jobs such as remote file access.
 @code{file-equal-p},
 @code{file-executable-p}, @code{file-exists-p},
 @code{file-in-directory-p},
-@code{file-local-copy}, @code{file-remote-p},
+@code{file-local-copy},
 @code{file-modes}, @code{file-name-all-completions},
 @code{file-name-as-directory},
 @code{file-name-completion},
 @code{file-name-directory},
 @code{file-name-nondirectory},
 @code{file-name-sans-versions}, @code{file-newer-than-file-p},
+@code{file-notify-add-watch}, @code{file-notify-rm-watch},
+@code{file-notify-supported-p},
 @code{file-ownership-preserved-p},
 @code{file-readable-p}, @code{file-regular-p},
-@code{file-selinux-context},
+@code{file-remote-p}, @code{file-selinux-context},
 @code{file-symlink-p}, @code{file-truename}, @code{file-writable-p},
 @code{find-backup-file-name},
 @c Not sure why it was here:   @code{find-file-noselect},@*
@@ -2820,20 +2822,22 @@ first, before handlers for jobs such as remote file access.
 @code{file-accessible-direc@discretionary{}{}{}tory-p},
 @code{file-acl},
 @code{file-attributes},
-@code{file-direct@discretionary{}{}{}ory-p},
+@code{file-direc@discretionary{}{}{}tory-p},
 @code{file-equal-p},
 @code{file-executable-p}, @code{file-exists-p},
 @code{file-in-directory-p},
-@code{file-local-copy}, @code{file-remote-p},
+@code{file-local-copy},
 @code{file-modes}, @code{file-name-all-completions},
 @code{file-name-as-directory},
 @code{file-name-completion},
 @code{file-name-directory},
 @code{file-name-nondirec@discretionary{}{}{}tory},
 @code{file-name-sans-versions}, @code{file-newer-than-file-p},
+@code{file-notify-add-watch}, @code{file-notify-rm-watch},
+@code{file-notify-supported-p},
 @code{file-ownership-pre@discretionary{}{}{}served-p},
 @code{file-readable-p}, @code{file-regular-p},
-@code{file-selinux-context},
+@code{file-remote-p}, @code{file-selinux-context},
 @code{file-symlink-p}, @code{file-truename}, @code{file-writable-p},
 @code{find-backup-file-name},
 @c Not sure why it was here:   @code{find-file-noselect},

diff --git a/doc/lispref/os.texi b/doc/lispref/os.texi
index b481c330f9fe4de0ef8f8704e61c4370e3a43409..fd52f55d816bb101ce9d513563e7cb62b0a0a143 100644 (file)
--- a/doc/lispref/os.texi
+++ b/doc/lispref/os.texi
@@ -34,7 +34,8 @@ terminal and the screen.
 * X11 Keysyms::         Operating on key symbols for X Windows.
 * Batch Mode::          Running Emacs without terminal interaction.
 * Session Management::  Saving and restoring state with X Session Management.
-* Notifications::       Desktop notifications.
+* Desktop Notifications:: Desktop notifications.
+* File Notifications::  File notifications.
 * Dynamic Libraries::   On-demand loading of support libraries.
 @end menu
 
@@ -2270,7 +2271,7 @@ Emacs is restarted by the session manager.
 @end group
 @end example
 
-@node Notifications
+@node Desktop Notifications
 @section Desktop Notifications
 @cindex desktop notifications
 
@@ -2510,6 +2511,163 @@ If @var{SPEC_VERSION} is @code{nil}, the server supports a
 specification prior to @samp{"1.0"}.
 @end defun
 
+@node File Notifications
+@section Notifications on File Changes
+@cindex file notifications
+
+Several operating systems support watching of filesystems for changes
+of files.  If configured properly, Emacs links a respective library
+like @file{gfilenotify}, @file{inotify}, or  @file{w32notify}
+statically.  These libraries enable watching of filesystems on the
+local machine.
+
+It is also possible to watch filesystems on remote machines,
+@pxref{Remote Files,, Remote Files, emacs, The GNU Emacs Manual}
+This does not depend on one of the libraries linked to Emacs.
+
+Since all these libraries emit different events on notified file
+changes, there is the Emacs library @code{filenotify} which provides a
+unique interface.
+
+@defun file-notify-supported-p file
+This function returns non-nil if the filesystem pertaining to
+@var{file} could be watched.  This means, that Emacs is linked with a
+respective library (for local files), or Emacs has found an applicable
+file notification process on a remote machine.
+
+Sometimes, mounted filesystems cannot be watched for file changes.
+This is not detected by this function, a non-@code{nil} return value
+does not guarantee that changes on @var{file} will be notified.
+@end defun
+
+@defun file-notify-add-watch file flags callback
+Add a watch for filesystem events pertaining to @var{file}.  This
+arranges for filesystem events pertaining to @var{file} to be reported
+to Emacs.
+
+The returned value is a descriptor for the added watch.  Its type
+depends on the underlying library, it cannot be assumed to be an
+integer as in the example below.  It should be used for comparison by
+@code{equal} only.
+
+If the @var{file} cannot be watched for some reason, this function
+signals a @code{file-notify-error} error.
+
+@var{flags} is a list of conditions to set what will be watched for.
+It can include the following symbols:
+
+@table @code
+@item change
+watch for file changes
+@item attribute-change
+watch for file attribute changes, like permissions or modification
+time
+@end table
+
+If @var{file} is a directory, changes for all files in that directory
+will be notified.  This does not work recursively.
+
+When any event happens, Emacs will call the @var{callback} function
+passing it a single argument @var{event}, which is of the form
+
+@lisp
+(@var{descriptor} @var{action} @var{file} [@var{file1}])
+@end lisp
+
+@var{descriptor} is the same object as the one returned by this
+function.  @var{action} is the description of the event.  It could be
+any one of the following symbols:
+
+@table @code
+@item created
+@var{file} was created
+@item deleted
+@var{file} was deleted
+@item changed
+@var{file} has changed
+@item renamed
+@var{file} has been renamed to @var{file1}
+@item attribute-changed
+a @var{file} attribute was changed
+@end table
+
+@var{file} and @var{file1} are the name of the file(s) whose event is
+being reported.  For example:
+
+@example
+@group
+(require 'filenotify)
+     @result{} filenotify
+@end group
+
+@group
+(defun my-notify-callback (event)
+  (message "Event %S" event))
+     @result{} my-notify-callback
+@end group
+
+@group
+(file-notify-add-watch
+  "/tmp" '(change attribute-change) 'my-notify-callback)
+     @result{} 35025468
+@end group
+
+@group
+(write-region "foo" nil "/tmp/foo")
+     @result{} Event (35025468 created "/tmp/.#foo")
+        Event (35025468 created "/tmp/foo")
+        Event (35025468 changed "/tmp/foo")
+        Event (35025468 deleted "/tmp/.#foo")
+@end group
+
+@group
+(write-region "bla" nil "/tmp/foo")
+     @result{} Event (35025468 created "/tmp/.#foo")
+        Event (35025468 changed "/tmp/foo") [2 times]
+        Event (35025468 deleted "/tmp/.#foo")
+@end group
+
+@group
+(set-file-modes "/tmp/foo" (default-file-modes))
+     @result{} Event (35025468 attribute-changed "/tmp/foo")
+@end group
+@end example
+
+Whether the action @code{renamed} is returned, depends on the used
+watch library.  It can be expected, when a directory is watched, and
+both @var{file} and @var{file1} belong to this directory.  Otherwise,
+the actions @code{deleted} and @code{created} could be returned in a
+random order.
+
+@example
+@group
+(rename-file "/tmp/foo" "/tmp/bla")
+     @result{} Event (35025468 renamed "/tmp/foo" "/tmp/bla")
+@end group
+
+@group
+(file-notify-add-watch
+  "/var/tmp" '(change attribute-change) 'my-notify-callback)
+     @result{} 35025504
+@end group
+
+@group
+(rename-file "/tmp/bla" "/var/tmp/bla")
+     @result{} ;; gfilenotify
+        Event (35025468 renamed "/tmp/bla" "/var/tmp/bla")
+
+     @result{} ;; inotify
+        Event (35025504 created "/var/tmp/bla")
+        Event (35025468 deleted "/tmp/bla")
+@end group
+@end example
+@end defun
+
+@defun file-notify-rm-watch descriptor
+Removes an existing file watch specified by its @var{descriptor}.
+@var{descriptor} should be an object returned by
+@code{file-notify-add-watch}.
+@end defun
 
 @node Dynamic Libraries
 @section Dynamically Loaded Libraries