[Emacs-diffs] trunk r113488: * files.texi (Magic File Names): Add file-notify-add-watch,

[Michael Albinus]

------------------------------------------------------------
revno: 113488
revision-id: address@hidden
parent: address@hidden
committer: Michael Albinus <address@hidden>
branch nick: trunk
timestamp: Mon 2013-07-22 11:19:00 +0200
message:
  * 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.
modified:
  doc/lispref/ChangeLog          changelog-20091113204419-o5vbwnq5f7feedwu-6155
  doc/lispref/elisp.texi         elisp.texi-20091113204419-o5vbwnq5f7feedwu-6176
  doc/lispref/errors.texi        
errors.texi-20091113204419-o5vbwnq5f7feedwu-6177
  doc/lispref/files.texi         files.texi-20091113204419-o5vbwnq5f7feedwu-6179
  doc/lispref/os.texi            os.texi-20091113204419-o5vbwnq5f7feedwu-6205

=== modified file 'doc/lispref/ChangeLog'
--- a/doc/lispref/ChangeLog     2013-07-19 06:31:17 +0000
+++ b/doc/lispref/ChangeLog     2013-07-22 09:19:00 +0000
@@ -1,3 +1,16 @@
+2013-07-22  Michael Albinus  <address@hidden>
+
+       * 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  <address@hidden>
 
        * windows.texi (Display Action Functions): Mention next-window.

=== modified file 'doc/lispref/elisp.texi'
--- a/doc/lispref/elisp.texi    2013-07-06 01:39:21 +0000
+++ b/doc/lispref/elisp.texi    2013-07-22 09:19:00 +0000
@@ -1482,7 +1482,8 @@
 * 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

=== modified file 'doc/lispref/errors.texi'
--- a/doc/lispref/errors.texi   2013-01-01 09:11:05 +0000
+++ b/doc/lispref/errors.texi   2013-07-22 09:19:00 +0000
@@ -123,6 +123,11 @@
 @item file-supersession
 This is a subcategory of @code{file-error}.  @xref{Modification Time}.
 
address@hidden filenotify.el
address@hidden 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

=== modified file 'doc/lispref/files.texi'
--- a/doc/lispref/files.texi    2013-07-03 03:20:04 +0000
+++ b/doc/lispref/files.texi    2013-07-22 09:19:00 +0000
@@ -2772,16 +2772,18 @@
 @code{file-equal-p},
 @code{file-executable-p}, @code{file-exists-p},
 @code{file-in-directory-p},
address@hidden, @code{file-remote-p},
address@hidden,
 @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},
address@hidden, @code{file-notify-rm-watch},
address@hidden,
 @code{file-ownership-preserved-p},
 @code{file-readable-p}, @code{file-regular-p},
address@hidden,
address@hidden, @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 @@
 @address@hidden,
 @code{file-acl},
 @code{file-attributes},
address@hidden@discretionary{}{}{}ory-p},
address@hidden@discretionary{}{}{}tory-p},
 @code{file-equal-p},
 @code{file-executable-p}, @code{file-exists-p},
 @code{file-in-directory-p},
address@hidden, @code{file-remote-p},
address@hidden,
 @code{file-modes}, @code{file-name-all-completions},
 @code{file-name-as-directory},
 @code{file-name-completion},
 @code{file-name-directory},
 @address@hidden,
 @code{file-name-sans-versions}, @code{file-newer-than-file-p},
address@hidden, @code{file-notify-rm-watch},
address@hidden,
 @address@hidden,
 @code{file-readable-p}, @code{file-regular-p},
address@hidden,
address@hidden, @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},

=== modified file 'doc/lispref/os.texi'
--- a/doc/lispref/os.texi       2013-01-02 16:13:04 +0000
+++ b/doc/lispref/os.texi       2013-07-22 09:19:00 +0000
@@ -34,7 +34,8 @@
 * 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 @@
 @end group
 @end example
 
address@hidden Notifications
address@hidden Desktop Notifications
 @section Desktop Notifications
 @cindex desktop notifications
 
@@ -2510,6 +2511,163 @@
 specification prior to @samp{"1.0"}.
 @end defun
 
address@hidden File Notifications
address@hidden Notifications on File Changes
address@hidden 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,
address@hidden 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.
+
address@hidden file-notify-supported-p file
+This function returns non-nil if the filesystem pertaining to
address@hidden 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 address@hidden return value
+does not guarantee that changes on @var{file} will be notified.
address@hidden defun
+
address@hidden 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
address@hidden only.
+
+If the @var{file} cannot be watched for some reason, this function
+signals a @code{file-notify-error} error.
+
address@hidden is a list of conditions to set what will be watched for.
+It can include the following symbols:
+
address@hidden @code
address@hidden change
+watch for file changes
address@hidden attribute-change
+watch for file attribute changes, like permissions or modification
+time
address@hidden 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
+
address@hidden
+(@var{descriptor} @var{action} @var{file} address@hidden)
address@hidden lisp
+
address@hidden 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:
+
address@hidden @code
address@hidden created
address@hidden was created
address@hidden deleted
address@hidden was deleted
address@hidden changed
address@hidden has changed
address@hidden renamed
address@hidden has been renamed to @var{file1}
address@hidden attribute-changed
+a @var{file} attribute was changed
address@hidden table
+
address@hidden and @var{file1} are the name of the file(s) whose event is
+being reported.  For example:
+
address@hidden
address@hidden
+(require 'filenotify)
+     @result{} filenotify
address@hidden group
+
address@hidden
+(defun my-notify-callback (event)
+  (message "Event %S" event))
+     @result{} my-notify-callback
address@hidden group
+
address@hidden
+(file-notify-add-watch
+  "/tmp" '(change attribute-change) 'my-notify-callback)
+     @result{} 35025468
address@hidden group
+
address@hidden
+(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")
address@hidden group
+
address@hidden
+(write-region "bla" nil "/tmp/foo")
+     @result{} Event (35025468 created "/tmp/.#foo")
+        Event (35025468 changed "/tmp/foo") [2 times]
+        Event (35025468 deleted "/tmp/.#foo")
address@hidden group
+
address@hidden
+(set-file-modes "/tmp/foo" (default-file-modes))
+     @result{} Event (35025468 attribute-changed "/tmp/foo")
address@hidden group
address@hidden 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.
+
address@hidden
address@hidden
+(rename-file "/tmp/foo" "/tmp/bla")
+     @result{} Event (35025468 renamed "/tmp/foo" "/tmp/bla")
address@hidden group
+
address@hidden
+(file-notify-add-watch
+  "/var/tmp" '(change attribute-change) 'my-notify-callback)
+     @result{} 35025504
address@hidden group
+
address@hidden
+(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")
address@hidden group
address@hidden example
address@hidden defun
+
address@hidden file-notify-rm-watch descriptor
+Removes an existing file watch specified by its @var{descriptor}.
address@hidden should be an object returned by
address@hidden
address@hidden defun
 
 @node Dynamic Libraries
 @section Dynamically Loaded Libraries