procyberian/emacs
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

Merge from origin/emacs-28

Browse source 
dbb2dd6939 ; Fix wording of "File Notifications" in the ELisp manual
This commit is contained in:
Stefan Kangas 2022-04-21 06:30:28 +02:00
commit 75052a0fa6
1 changed files with 30 additions and 27 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

57
doc/lispref/os.texi
View file

@ -3113,21 +3113,21 @@ This function removes the tray notification given by its unique
@cindex watch, for filesystem events
Several operating systems support watching of filesystems for changes
of files. If configured properly, Emacs links a respective library
like @file{inotify}, @file{kqueue}, @file{gfilenotify}, or
@file{w32notify} statically. These libraries enable watching of
filesystems on the local machine.
to files or their attributes. If configured properly, Emacs links a
respective library like @file{inotify}, @file{kqueue},
@file{gfilenotify}, 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}
@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
unified interface. Lisp programs that want to receive file
notifications should always use this library in preference to the
native ones.
Since all these libraries emit different events upon notified file
changes, Emacs provides a special library @code{filenotify} 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} library functions and variables.
@defun file-notify-add-watch file flags callback
Add a watch for filesystem events pertaining to @var{file}. This
@ -3135,31 +3135,33 @@ 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.
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} only.
If the @var{file} cannot be watched for some reason, this function
signals a @code{file-notify-error} error.
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.
This is not detected by this function, and so a non-@code{nil} return
value does not guarantee that changes on @var{file} will be actually
notified.
@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
watch for changes in file's contents
@item attribute-change
watch for file attribute changes, like permissions or modification
watch for changes in file attributes, like permissions or modification
time
@end table
If @var{file} is a directory, @code{change} watches for file creation
or deletion in that directory. Some of the file notification backends
report also file changes. This does not work recursively.
and deletion in that directory. Some of the native file notification
libraries also report file changes in that case. 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
@ -3185,19 +3187,20 @@ reports attribute changes as well
@item attribute-changed
a @var{file} attribute was changed
@item stopped
watching @var{file} has been stopped
watching @var{file} has stopped
@end table
Note that the @file{w32notify} library does not report
@code{attribute-changed} events. When some file's attribute, like
permissions or modification time, has changed, this library reports a
@code{changed} event. Likewise, the @file{kqueue} library does not
report reliably file attribute changes when watching a directory.
reliably report file attribute changes when watching a directory.
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.
The @code{stopped} event means that watching the file has been
discontinued. 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 which makes
further watching impossible.
@var{file} and @var{file1} are the name of the file(s) whose event is
being reported. For example:
@ -3241,7 +3244,7 @@ being reported. For example:
@end group
@end example
Whether the action @code{renamed} is returned, depends on the used
Whether the action @code{renamed} is returned depends on the used
watch library. Otherwise, the actions @code{deleted} and
@code{created} could be returned in a random order.