* files.texi (Magic File Names): New defopt remote-file-name-inhibit-cache.

doc/lispref/ChangeLog

+2010-10-03  Michael Albinus  <michael.albinus@gmx.de>
+
+	* files.texi (Magic File Names): New defopt
+	remote-file-name-inhibit-cache.
+
 2010-10-02  Glenn Morris  <rgm@gnu.org>
 
 	* os.texi (Killing Emacs): Hook now runs in batch mode.

doc/lispref/files.texi

@@ -2857,6 +2857,34 @@ non-magic directory to serve as its current directory, and this function
 is a good way to come up with one.
 @end defun
 
+@defopt remote-file-name-inhibit-cache
+Whether to use the remote file-name cache for read access.
+
+File attributes of remote files are cached for better performance.  If
+they are changed out of Emacs' control, the cached values become
+invalid, and must be reread.
+
+When set to @code{nil}, cached values are always used.  This shall be
+set with care.  When set to @code{t}, cached values are never used.
+ALthough this is the safest value, it could result in performance
+degradation.
+
+A compromise is to set it to a positive number.  This means that
+cached values are used for that amount of seconds since they were
+cached.
+
+In case a remote file is checked regularly, it might be reasonable to
+let-bind this variable to a value less then the time period between
+two checks.  Example:
+
+@example
+(defun display-time-file-nonempty-p (file)
+  (let ((remote-file-name-inhibit-cache (- display-time-interval 5)))
+    (and (file-exists-p file)
+         (< 0 (nth 7 (file-attributes (file-chase-links file)))))))
+@end example
+@end defopt
+
 @node Format Conversion
 @section File Format Conversion