Update Files chapter in Lisp manual.

* doc/lispref/files.texi (Files): Mention magic file names as arguments.
(Reading from Files): Copyedits.
(File Attributes): Mention how to change file modes.
(Changing Files): Use standard "file permissions" terminology.
Add xref to File Attributes node.
(Locating Files): Document locate-user-emacs-file.
(Unique File Names): Recommend against using make-temp-name.

* src/buffer.c (Fget_file_buffer): Protect against invalid file
handler return value.

* src/fileio.c (Vfile_name_handler_alist): Doc fix.

3 files changed, 31 insertions, 13 deletions

diff --git a/src/ChangeLog b/src/ChangeLog
index bd376e9b855..c5e898684a8 100644
--- a/src/ChangeLog
+++ b/src/ChangeLog
@@ -1,3 +1,10 @@
+2012-02-21  Chong Yidong  <cyd@gnu.org>
+
+        * fileio.c (Vfile_name_handler_alist): Doc fix.
+
+        * buffer.c (Fget_file_buffer): Protect against invalid file
+        handler return value.
+
 2012-02-20  Paul Eggert  <eggert@cs.ucla.edu>
 
         * .gdbinit (xreload): Don't assume EMACS_INT fits in 'long'
diff --git a/src/buffer.c b/src/buffer.c
index a6f61a1936a..71a5e199c6f 100644
--- a/src/buffer.c
+++ b/src/buffer.c
@@ -272,7 +272,11 @@ See also `find-buffer-visiting'.  */)
      call the corresponding file handler.  */
   handler = Ffind_file_name_handler (filename, Qget_file_buffer);
   if (!NILP (handler))
-    return call2 (handler, Qget_file_buffer, filename);
+    {
+      Lisp_Object handled_buf = call2 (handler, Qget_file_buffer,
+                                       filename);
+      return BUFFERP (handled_buf) ? handled_buf : Qnil;
+    }
 
   for (tail = Vbuffer_alist; CONSP (tail); tail = XCDR (tail))
     {
diff --git a/src/fileio.c b/src/fileio.c
index 1fd5ebed651..839dc07b6ce 100644
--- a/src/fileio.c
+++ b/src/fileio.c
@@ -5640,18 +5640,25 @@ of file names regardless of the current language environment.  */);
         make_pure_c_string ("Cannot set file date"));
 
   DEFVAR_LISP ("file-name-handler-alist", Vfile_name_handler_alist,
-               doc: /* *Alist of elements (REGEXP . HANDLER) for file names handled specially.
-If a file name matches REGEXP, then all I/O on that file is done by calling
-HANDLER.
-
-The first argument given to HANDLER is the name of the I/O primitive
-to be handled; the remaining arguments are the arguments that were
-passed to that primitive.  For example, if you do
-    (file-exists-p FILENAME)
-and FILENAME is handled by HANDLER, then HANDLER is called like this:
-    (funcall HANDLER 'file-exists-p FILENAME)
-The function `find-file-name-handler' checks this list for a handler
-for its argument.  */);
+               doc: /* Alist of elements (REGEXP . HANDLER) for file names handled specially.
+If a file name matches REGEXP, all I/O on that file is done by calling
+HANDLER.  If a file name matches more than one handler, the handler
+whose match starts last in the file name gets precedence.  The
+function `find-file-name-handler' checks this list for a handler for
+its argument.
+
+HANDLER should be a function.  The first argument given to it is the
+name of the I/O primitive to be handled; the remaining arguments are
+the arguments that were passed to that primitive.  For example, if you
+do (file-exists-p FILENAME) and FILENAME is handled by HANDLER, then
+HANDLER is called like this:
+
+  (funcall HANDLER 'file-exists-p FILENAME)
+
+Note that HANDLER must be able to handle all I/O primitives; if it has
+nothing special to do for a primitive, it should reinvoke the
+primitive to handle the operation \"the usual way\".
+See Info node `(elisp)Magic File Names' for more details.  */);
   Vfile_name_handler_alist = Qnil;
 
   DEFVAR_LISP ("set-auto-coding-function",