[Emacs-diffs] master 80dd76a: Document file notification `stopped' event

[Michael Albinus]

branch: master
commit 80dd76a8e5d08b35c50589fb1ce7ef6a43ee74ab
Author: Michael Albinus <address@hidden>
Commit: Michael Albinus <address@hidden>

    Document file notification `stopped' event
    
    * doc/lispref/os.texi (File Notifications): Document `stopped event'.
---
 doc/lispref/os.texi |   37 +++++++++++++++++++++++++++++++++++++
 etc/NEWS            |   11 ++++++++---
 2 files changed, 45 insertions(+), 3 deletions(-)

diff --git a/doc/lispref/os.texi b/doc/lispref/os.texi
index 1925bd5..0160de8 100644
--- a/doc/lispref/os.texi
+++ b/doc/lispref/os.texi
@@ -2632,6 +2632,8 @@ reports attribute changes as well
 @var{file} has been renamed to @var{file1}
 @item attribute-changed
 a @var{file} attribute was changed
address@hidden stopped
+watching @var{file} has been stopped
 @end table
 
 Note that the @file{w32notify} library does not report
@@ -2639,6 +2641,11 @@ Note that the @file{w32notify} library does not report
 permissions or modification time, has changed, this library reports a
 @code{changed} event.
 
+The @code{stopped} event reports, that watching the file has been
+stopped.  This could be because @code{file-notify-rm-watch} was called
+(see below), or because the file being watched was deleted, or due to
+another error reported from the underlying library.
+
 @var{file} and @var{file1} are the name of the file(s) whose event is
 being reported.  For example:
 
@@ -2708,6 +2715,36 @@ A watch can become invalid if the file or directory it 
watches is
 deleted, or if the watcher thread exits abnormally for any other
 reason.  Removing the watch by calling @code{file-notify-rm-watch}
 also makes it invalid.
+
address@hidden
address@hidden
+(setq desc (file-notify-add-watch
+             "/tmp/foo" '(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 changed "/tmp/foo")
address@hidden group
+
address@hidden
+(file-notify-valid-p desc)
+     @result{} t
address@hidden group
+
address@hidden
+(delete-file "/tmp/foo")
+     @result{} Event (35025468 deleted "/tmp/foo")
+        Event (35025468 stopped "/tmp/foo")
address@hidden group
+
address@hidden
+(file-notify-valid-p desc)
+     @result{} nil
address@hidden group
address@hidden example
 @end defun
 
 @node Dynamic Libraries
diff --git a/etc/NEWS b/etc/NEWS
index 381e7c8..f5b06f9 100644
--- a/etc/NEWS
+++ b/etc/NEWS
@@ -843,10 +843,15 @@ be added to the archive.
 ** Autorevert: dired buffers are also auto-reverted via file
 notifications, if Emacs is compiled with file notification support.
 
+** File Notifications
+
++++
+*** The new event `stopped' signals, that a file notification watch is
+not active any longer.
+
 +++
-** File Notifications: the new function `file-notify-valid-p' checks,
-whether a file notification descriptor still corresponds to an
-activate watch.
+*** The new function `file-notify-valid-p' checks, whether a file
+notification descriptor still corresponds to an activate watch.
 
 ** Dired