new repository

1 files changed, 98 insertions, 0 deletions

diff --git a/devdocs/elisp/file-notifications.html b/devdocs/elisp/file-notifications.html
new file mode 100644
index 00000000..68dad667
--- /dev/null
+++ b/devdocs/elisp/file-notifications.html
@@ -0,0 +1,98 @@
+ <h3 class="section">Notifications on File Changes</h3>   <p>Several operating systems support watching of filesystems for changes to files or their attributes. If configured properly, Emacs links a respective library like <samp>inotify</samp>, <samp>kqueue</samp>, <samp>gfilenotify</samp>, or <samp>w32notify</samp> statically. These libraries enable watching of filesystems on the local machine. </p> <p>It is also possible to watch filesystems on remote machines, see <a href="https://www.gnu.org/software/emacs/manual/html_node/emacs/Remote-Files.html#Remote-Files">Remote Files</a> in <cite>The GNU Emacs Manual</cite>. This does not depend on one of the libraries linked to Emacs. </p> <p>Since all these libraries emit different events upon notified file changes, Emacs provides a special library <code>filenotify</code> which presents a unified interface to applications. Lisp programs that want to receive file notifications should always use this library in preference to the native ones. This section documents the <code>filenotify</code> library functions and variables. </p> <dl> <dt id="file-notify-add-watch">Function: <strong>file-notify-add-watch</strong> <em>file flags callback</em>
+</dt> <dd>
+<p>Add a watch for filesystem events pertaining to <var>file</var>. This arranges for filesystem events pertaining to <var>file</var> to be reported to Emacs. </p> <p>The returned value is a descriptor for the added watch. Its type depends on the underlying library, and in general cannot be assumed to be an integer as in the example below. It should be used for comparison by <code>equal</code> only. </p> <p>If the <var>file</var> cannot be watched for some reason, this function signals a <code>file-notify-error</code> error. </p> <p>Sometimes, mounted filesystems cannot be watched for file changes. This is not detected by this function, and so a non-<code>nil</code> return value does not guarantee that changes on <var>file</var> will be actually notified. </p> <p><var>flags</var> is a list of conditions to set what will be watched for. It can include the following symbols: </p> <dl compact> <dt><code>change</code></dt> <dd><p>watch for changes in file’s contents </p></dd> <dt><code>attribute-change</code></dt> <dd><p>watch for changes in file attributes, like permissions or modification time </p></dd> </dl> <p>If <var>file</var> is a directory, <code>change</code> watches for file creation and deletion in that directory. Some of the native file notification libraries also report file changes in that case. This does not work recursively. </p> <p>When any event happens, Emacs will call the <var>callback</var> function passing it a single argument <var>event</var>, which is of the form </p> <div class="lisp"> <pre class="lisp">(<var>descriptor</var> <var>action</var> <var>file</var> [<var>file1</var>])
+</pre>
+</div> <p><var>descriptor</var> is the same object as the one returned by this function. <var>action</var> is the description of the event. It could be any one of the following symbols: </p> <dl compact> <dt><code>created</code></dt> <dd><p><var>file</var> was created </p></dd> <dt><code>deleted</code></dt> <dd><p><var>file</var> was deleted </p></dd> <dt><code>changed</code></dt> <dd><p><var>file</var>’s contents has changed; with <samp>w32notify</samp> library, reports attribute changes as well </p></dd> <dt><code>renamed</code></dt> <dd><p><var>file</var> has been renamed to <var>file1</var> </p></dd> <dt><code>attribute-changed</code></dt> <dd><p>a <var>file</var> attribute was changed </p></dd> <dt><code>stopped</code></dt> <dd><p>watching <var>file</var> has stopped </p></dd> </dl> <p>Note that the <samp>w32notify</samp> library does not report <code>attribute-changed</code> events. When some file’s attribute, like permissions or modification time, has changed, this library reports a <code>changed</code> event. Likewise, the <samp>kqueue</samp> library does not reliably report file attribute changes when watching a directory. </p> <p>The <code>stopped</code> event means that watching the file has been discontinued. This could be because <code>file-notify-rm-watch</code> was called (see below), or because the file being watched was deleted, or due to another error reported from the underlying library which makes further watching impossible. </p> <p><var>file</var> and <var>file1</var> are the name of the file(s) whose event is being reported. For example: </p> <div class="example"> <pre class="example">(require 'filenotify)
+     ⇒ filenotify
+</pre>
+
+<pre class="example">(defun my-notify-callback (event)
+  (message "Event %S" event))
+     ⇒ my-notify-callback
+</pre>
+
+<pre class="example">(file-notify-add-watch
+  "/tmp" '(change attribute-change) 'my-notify-callback)
+     ⇒ 35025468
+</pre>
+
+<pre class="example">(write-region "foo" nil "/tmp/foo")
+     ⇒ Event (35025468 created "/tmp/.#foo")
+        Event (35025468 created "/tmp/foo")
+        Event (35025468 changed "/tmp/foo")
+        Event (35025468 deleted "/tmp/.#foo")
+</pre>
+
+<pre class="example">(write-region "bla" nil "/tmp/foo")
+     ⇒ Event (35025468 created "/tmp/.#foo")
+        Event (35025468 changed "/tmp/foo")
+        Event (35025468 deleted "/tmp/.#foo")
+</pre>
+
+<pre class="example">(set-file-modes "/tmp/foo" (default-file-modes) 'nofollow)
+     ⇒ Event (35025468 attribute-changed "/tmp/foo")
+</pre>
+</div> <p>Whether the action <code>renamed</code> is returned depends on the used watch library. Otherwise, the actions <code>deleted</code> and <code>created</code> could be returned in a random order. </p> <div class="example"> <pre class="example">(rename-file "/tmp/foo" "/tmp/bla")
+     ⇒ Event (35025468 renamed "/tmp/foo" "/tmp/bla")
+</pre>
+
+<pre class="example">(delete-file "/tmp/bla")
+     ⇒ Event (35025468 deleted "/tmp/bla")
+</pre>
+</div> </dd>
+</dl> <dl> <dt id="file-notify-rm-watch">Function: <strong>file-notify-rm-watch</strong> <em>descriptor</em>
+</dt> <dd><p>Removes an existing file watch specified by its <var>descriptor</var>. <var>descriptor</var> should be an object returned by <code>file-notify-add-watch</code>. </p></dd>
+</dl> <dl> <dt id="file-notify-valid-p">Function: <strong>file-notify-valid-p</strong> <em>descriptor</em>
+</dt> <dd>
+<p>Checks a watch specified by its <var>descriptor</var> for validity. <var>descriptor</var> should be an object returned by <code>file-notify-add-watch</code>. </p> <p>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</code> also makes it invalid. </p> <div class="example"> <pre class="example">(make-directory "/tmp/foo")
+     ⇒ Event (35025468 created "/tmp/foo")
+</pre>
+
+<pre class="example">(setq desc
+      (file-notify-add-watch
+        "/tmp/foo" '(change) 'my-notify-callback))
+     ⇒ 11359632
+</pre>
+
+<pre class="example">(file-notify-valid-p desc)
+     ⇒ t
+</pre>
+
+<pre class="example">(write-region "bla" nil "/tmp/foo/bla")
+     ⇒ Event (11359632 created "/tmp/foo/.#bla")
+        Event (11359632 created "/tmp/foo/bla")
+        Event (11359632 changed "/tmp/foo/bla")
+        Event (11359632 deleted "/tmp/foo/.#bla")
+</pre>
+
+<pre class="example">;; Deleting a file in the directory doesn't invalidate the watch.
+(delete-file "/tmp/foo/bla")
+     ⇒ Event (11359632 deleted "/tmp/foo/bla")
+</pre>
+
+<pre class="example">(write-region "bla" nil "/tmp/foo/bla")
+     ⇒ Event (11359632 created "/tmp/foo/.#bla")
+        Event (11359632 created "/tmp/foo/bla")
+        Event (11359632 changed "/tmp/foo/bla")
+        Event (11359632 deleted "/tmp/foo/.#bla")
+</pre>
+
+<pre class="example">;; Deleting the directory invalidates the watch.
+;; Events arrive for different watch descriptors.
+(delete-directory "/tmp/foo" 'recursive)
+     ⇒ Event (35025468 deleted "/tmp/foo")
+        Event (11359632 deleted "/tmp/foo/bla")
+        Event (11359632 deleted "/tmp/foo")
+        Event (11359632 stopped "/tmp/foo")
+</pre>
+
+<pre class="example">(file-notify-valid-p desc)
+     ⇒ nil
+</pre>
+</div> </dd>
+</dl><div class="_attribution">
+  <p class="_attribution-p">
+    Copyright &copy; 1990-1996, 1998-2022 Free Software Foundation, Inc. <br>Licensed under the GNU GPL license.<br>
+    <a href="https://www.gnu.org/software/emacs/manual/html_node/elisp/File-Notifications.html" class="_attribution-link">https://www.gnu.org/software/emacs/manual/html_node/elisp/File-Notifications.html</a>
+  </p>
+</div>