Document file notification `stopped' event

* doc/lispref/os.texi (File Notifications): Document `stopped event'.

1 files changed, 37 insertions, 0 deletions

diff --git a/doc/lispref/os.texi b/doc/lispref/os.texi
index 1925bd544e5..0160de82086 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
+@item 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.
+
+@example
+@group
+(setq desc (file-notify-add-watch
+             "/tmp/foo" '(change) 'my-notify-callback))
+     @result{} 35025468
+@end group
+
+@group
+(write-region "foo" nil "/tmp/foo")
+     @result{} Event (35025468 created "/tmp/foo")
+        Event (35025468 changed "/tmp/foo")
+@end group
+
+@group
+(file-notify-valid-p desc)
+     @result{} t
+@end group
+
+@group
+(delete-file "/tmp/foo")
+     @result{} Event (35025468 deleted "/tmp/foo")
+        Event (35025468 stopped "/tmp/foo")
+@end group
+
+@group
+(file-notify-valid-p desc)
+     @result{} nil
+@end group
+@end example
 @end defun
 
 @node Dynamic Libraries