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

* files.texi (Magic File Names): Add file-notify-add-watch,

Browse source 
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.
This commit is contained in:
Michael Albinus 2013-07-22 11:19:00 +02:00
parent fb83082013
commit 32813ea795
5 changed files with 189 additions and 8 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

13
doc/lispref/ChangeLog
View file

@ -1,3 +1,16 @@
2013-07-22 Michael Albinus <michael.albinus@gmx.de>
* 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 <xfq.free@gmail.com>
* windows.texi (Display Action Functions): Mention next-window.

3
doc/lispref/elisp.texi
View file

@ -1482,7 +1482,8 @@ Operating System Interface
* 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

5
doc/lispref/errors.texi
View file

@ -123,6 +123,11 @@ This is a subcategory of @code{file-error}. @xref{File Locks}.
@item file-supersession
This is a subcategory of @code{file-error}. @xref{Modification Time}.
@c filenotify.el
@item 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

14
doc/lispref/files.texi
View file

@ -2772,16 +2772,18 @@ first, before handlers for jobs such as remote file access.
@code{file-equal-p},
@code{file-executable-p}, @code{file-exists-p},
@code{file-in-directory-p},
@code{file-local-copy}, @code{file-remote-p},
@code{file-local-copy},
@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},
@code{file-notify-add-watch}, @code{file-notify-rm-watch},
@code{file-notify-supported-p},
@code{file-ownership-preserved-p},
@code{file-readable-p}, @code{file-regular-p},
@code{file-selinux-context},
@code{file-remote-p}, @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 @@ first, before handlers for jobs such as remote file access.
@code{file-accessible-direc@discretionary{}{}{}tory-p},
@code{file-acl},
@code{file-attributes},
@code{file-direct@discretionary{}{}{}ory-p},
@code{file-direc@discretionary{}{}{}tory-p},
@code{file-equal-p},
@code{file-executable-p}, @code{file-exists-p},
@code{file-in-directory-p},
@code{file-local-copy}, @code{file-remote-p},
@code{file-local-copy},
@code{file-modes}, @code{file-name-all-completions},
@code{file-name-as-directory},
@code{file-name-completion},
@code{file-name-directory},
@code{file-name-nondirec@discretionary{}{}{}tory},
@code{file-name-sans-versions}, @code{file-newer-than-file-p},
@code{file-notify-add-watch}, @code{file-notify-rm-watch},
@code{file-notify-supported-p},
@code{file-ownership-pre@discretionary{}{}{}served-p},
@code{file-readable-p}, @code{file-regular-p},
@code{file-selinux-context},
@code{file-remote-p}, @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},

162
doc/lispref/os.texi
View file

@ -34,7 +34,8 @@ terminal and the screen.
* 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 @@ Emacs is restarted by the session manager.
@end group
@end example
@node Notifications
@node Desktop Notifications
@section Desktop Notifications
@cindex desktop notifications
@ -2510,6 +2511,163 @@ If @var{SPEC_VERSION} is @code{nil}, the server supports a
specification prior to @samp{"1.0"}.
@end defun
@node File Notifications
@section Notifications on File Changes
@cindex 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,
@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
unique interface.
@defun file-notify-supported-p file
This function returns non-nil if the filesystem pertaining to
@var{file} 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 non-@code{nil} return value
does not guarantee that changes on @var{file} will be notified.
@end defun
@defun 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
@code{equal} only.
If the @var{file} cannot be watched for some reason, this function
signals a @code{file-notify-error} error.
@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
@item attribute-change
watch for file attribute changes, like permissions or modification
time
@end 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
@lisp
(@var{descriptor} @var{action} @var{file} [@var{file1}])
@end lisp
@var{descriptor} 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:
@table @code
@item created
@var{file} was created
@item deleted
@var{file} was deleted
@item changed
@var{file} has changed
@item renamed
@var{file} has been renamed to @var{file1}
@item attribute-changed
a @var{file} attribute was changed
@end table
@var{file} and @var{file1} are the name of the file(s) whose event is
being reported. For example:
@example
@group
(require 'filenotify)
@result{} filenotify
@end group
@group
(defun my-notify-callback (event)
(message "Event %S" event))
@result{} my-notify-callback
@end group
@group
(file-notify-add-watch
"/tmp" '(change attribute-change) 'my-notify-callback)
@result{} 35025468
@end group
@group
(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")
@end group
@group
(write-region "bla" nil "/tmp/foo")
@result{} Event (35025468 created "/tmp/.#foo")
Event (35025468 changed "/tmp/foo") [2 times]
Event (35025468 deleted "/tmp/.#foo")
@end group
@group
(set-file-modes "/tmp/foo" (default-file-modes))
@result{} Event (35025468 attribute-changed "/tmp/foo")
@end group
@end 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.
@example
@group
(rename-file "/tmp/foo" "/tmp/bla")
@result{} Event (35025468 renamed "/tmp/foo" "/tmp/bla")
@end group
@group
(file-notify-add-watch
"/var/tmp" '(change attribute-change) 'my-notify-callback)
@result{} 35025504
@end group
@group
(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")
@end group
@end example
@end defun
@defun file-notify-rm-watch descriptor
Removes an existing file watch specified by its @var{descriptor}.
@var{descriptor} should be an object returned by
@code{file-notify-add-watch}.
@end defun
@node Dynamic Libraries
@section Dynamically Loaded Libraries