From: Michael Albinus Date: Mon, 22 Jul 2013 09:19:00 +0000 (+0200) Subject: * files.texi (Magic File Names): Add file-notify-add-watch, X-Git-Tag: emacs-24.3.90~173^2^2~42^2~45^2~387^2~1740 X-Git-Url: http://git.eshelyaron.com/gitweb/?a=commitdiff_plain;h=32813ea795271291c3734a737a399db98c9467b9;p=emacs.git * 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. --- diff --git a/doc/lispref/ChangeLog b/doc/lispref/ChangeLog index 8b0dd6afa4e..342c7c57175 100644 --- a/doc/lispref/ChangeLog +++ b/doc/lispref/ChangeLog @@ -1,3 +1,16 @@ +2013-07-22 Michael Albinus + + * 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 * windows.texi (Display Action Functions): Mention next-window. diff --git a/doc/lispref/elisp.texi b/doc/lispref/elisp.texi index 59bbdec0229..4b8cc36b4ea 100644 --- a/doc/lispref/elisp.texi +++ b/doc/lispref/elisp.texi @@ -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 diff --git a/doc/lispref/errors.texi b/doc/lispref/errors.texi index 3f3984e40d2..264604470da 100644 --- a/doc/lispref/errors.texi +++ b/doc/lispref/errors.texi @@ -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 diff --git a/doc/lispref/files.texi b/doc/lispref/files.texi index 951d55ac90f..d2d327585c7 100644 --- a/doc/lispref/files.texi +++ b/doc/lispref/files.texi @@ -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}, diff --git a/doc/lispref/os.texi b/doc/lispref/os.texi index b481c330f9f..fd52f55d816 100644 --- a/doc/lispref/os.texi +++ b/doc/lispref/os.texi @@ -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