[Emacs-diffs] /srv/bzr/emacs/trunk r107364: Update Files chapter in Lisp manual.

[Chong Yidong]

------------------------------------------------------------
revno: 107364
committer: Chong Yidong <address@hidden>
branch nick: trunk
timestamp: Tue 2012-02-21 21:24:48 +0800
message:
  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.
modified:
  admin/FOR-RELEASE
  doc/lispref/ChangeLog
  doc/lispref/elisp.texi
  doc/lispref/files.texi
  doc/lispref/vol1.texi
  doc/lispref/vol2.texi
  src/ChangeLog
  src/buffer.c
  src/fileio.c

=== modified file 'admin/FOR-RELEASE'
--- a/admin/FOR-RELEASE 2012-02-21 08:28:18 +0000
+++ b/admin/FOR-RELEASE 2012-02-21 13:24:48 +0000
@@ -83,8 +83,6 @@
 
 * DOCUMENTATION
 
-** Document XEmbed support
-
 ** Check the Emacs Tutorial.
 
 The first line of every tutorial must begin with text ending in a
@@ -193,7 +191,7 @@
 elisp.texi
 errors.texi       
 eval.texi         cyd
-files.texi        
+files.texi        cyd
 frames.texi       
 functions.texi    cyd
 hash.texi         cyd
@@ -229,10 +227,6 @@
 variables.texi    cyd
 windows.texi      
 
-* PLANNED ADDITIONS
-* pov-mode (waiting for a Free POV-Ray)
-** gas-mode ?
-
 
 Local variables:
 mode: outline

=== modified file 'doc/lispref/ChangeLog'
--- a/doc/lispref/ChangeLog     2012-02-19 05:54:33 +0000
+++ b/doc/lispref/ChangeLog     2012-02-21 13:24:48 +0000
@@ -1,3 +1,13 @@
+2012-02-21  Chong Yidong  <address@hidden>
+
+       * 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.
+
 2012-02-19  Chong Yidong  <address@hidden>
 
        * help.texi (Documentation, Documentation Basics, Help Functions):

=== modified file 'doc/lispref/elisp.texi'
--- a/doc/lispref/elisp.texi    2012-02-19 05:54:33 +0000
+++ b/doc/lispref/elisp.texi    2012-02-21 13:24:48 +0000
@@ -843,12 +843,11 @@
 * File Locks::              Locking and unlocking files, to prevent
                               simultaneous editing by two people.
 * Information about Files:: Testing existence, accessibility, size of files.
-* Changing Files::          Renaming files, changing protection, etc.
+* Changing Files::          Renaming files, changing permissions, etc.
 * File Names::              Decomposing and expanding file names.
 * Contents of Directories:: Getting a list of the files in a directory.
 * Create/Delete Dirs::      Creating and Deleting Directories.
-* Magic File Names::        Defining "magic" special handling
-                              for certain file names.
+* Magic File Names::        Special handling for certain file names.
 * Format Conversion::       Conversion to and from various file formats.
 
 Visiting Files

=== modified file 'doc/lispref/files.texi'
--- a/doc/lispref/files.texi    2012-02-10 08:08:23 +0000
+++ b/doc/lispref/files.texi    2012-02-21 13:24:48 +0000
@@ -8,9 +8,9 @@
 @comment  node-name,  next,  previous,  up
 @chapter Files
 
-  In Emacs, you can find, create, view, save, and otherwise work with
-files and file directories.  This chapter describes most of the
-file-related functions of Emacs Lisp, but a few others are described in
+  This chapter describes the Emacs Lisp functions and variables to
+find, create, view, save, and otherwise work with files and file
+directories.  A few other file-related functions are described in
 @ref{Buffers}, and those related to backups and auto-saving are
 described in @ref{Backups and Auto-Saving}.
 
@@ -18,8 +18,15 @@
 names.  A file name is actually a string.  Most of these functions
 expand file name arguments by calling @code{expand-file-name}, so that
 @file{~} is handled correctly, as are relative file names (including
address@hidden/}).  These functions don't recognize environment variable
-substitutions such as @samp{$HOME}.  @xref{File Name Expansion}.
address@hidden/}).  @xref{File Name Expansion}.
+
+  In addition, certain @dfn{magic} file names are handled specially.
+For example, when a remote file name is specified, Emacs accesses the
+file over the network via an appropriate protocol (@pxref{Remote
+Files,, Remote Files, emacs, The GNU Emacs Manual}).  This handling is
+done at a very low level, so you may assume that all the functions
+described in this chapter accept magic file names as file name
+arguments, except where noted.  @xref{Magic File Names}, for details.
 
   When file I/O functions signal Lisp errors, they usually use the
 condition @code{file-error} (@pxref{Handling Errors}).  The error
@@ -35,12 +42,11 @@
 * File Locks::               Locking and unlocking files, to prevent
                                simultaneous editing by two people.
 * Information about Files::  Testing existence, accessibility, size of files.
-* Changing Files::           Renaming files, changing protection, etc.
+* Changing Files::           Renaming files, changing permissions, etc.
 * File Names::               Decomposing and expanding file names.
 * Contents of Directories::  Getting a list of the files in a directory.
 * Create/Delete Dirs::       Creating and Deleting Directories.
-* Magic File Names::         Defining "magic" special handling
-                               for certain file names.
+* Magic File Names::         Special handling for certain file names.
 * Format Conversion::        Conversion to and from various file formats.
 @end menu
 
@@ -513,17 +519,15 @@
 and the length of the data inserted.  An error is signaled if
 @var{filename} is not the name of a file that can be read.
 
-The function @code{insert-file-contents} checks the file contents
-against the defined file formats, and converts the file contents if
-appropriate and also calls the functions in
-the list @code{after-insert-file-functions}.  @xref{Format Conversion}.
-Normally, one of the functions in the
+This function checks the file contents against the defined file
+formats, and converts the file contents if appropriate and also calls
+the functions in the list @code{after-insert-file-functions}.
address@hidden Conversion}.  Normally, one of the functions in the
 @code{after-insert-file-functions} list determines the coding system
 (@pxref{Coding Systems}) used for decoding the file's contents,
 including end-of-line conversion.  However, if the file contains null
-bytes, it is by default visited without any code conversions; see
address@hidden and Coding Systems, inhibit-null-byte-detection}, for how to
-control this behavior.
+bytes, it is by default visited without any code conversions.
address@hidden and Coding Systems, inhibit-null-byte-detection}.
 
 If @var{visit} is address@hidden, this function additionally marks the
 buffer as unmodified and sets up various fields in the buffer so that it
@@ -554,11 +558,9 @@
 @end defun
 
 @defun insert-file-contents-literally filename &optional visit beg end replace
-This function works like @code{insert-file-contents} except that it does
-not do format decoding (@pxref{Format Conversion}), does not do
-character code conversion (@pxref{Coding Systems}), does not run
address@hidden, does not perform automatic uncompression, and so
-on.
+This function works like @code{insert-file-contents} except that it
+does not run @code{find-file-hook}, and does not do format decoding,
+character code conversion, automatic uncompression, and so on.
 @end defun
 
 If you want to pass a file name to another process so that another
@@ -796,7 +798,7 @@
 to exist.  This does not mean you can necessarily read the file, only
 that you can find out its attributes.  (On Unix and GNU/Linux, this is
 true if the file exists and you have execute permission on the
-containing directories, regardless of the protection of the file
+containing directories, regardless of the permissions of the file
 itself.)
 
 If the file does not exist, or if fascist access control policies
@@ -1020,7 +1022,6 @@
 @subsection Truenames
 @cindex truename (of file)
 
address@hidden Emacs 19 features
   The @dfn{truename} of a file is the name that you get by following
 symbolic links at all levels until none remain, then simplifying away
 @samp{.}@: and @samp{..}@: appearing as name components.  This results
@@ -1030,9 +1031,9 @@
 because they eliminate symbolic links as a cause of name variation.
 
 @defun file-truename filename
-The function @code{file-truename} returns the truename of the file
address@hidden  If the argument is not an absolute file name,
-this function first expands it against @code{default-directory}.
+This function returns the truename of the file @var{filename}.  If the
+argument is not an absolute file name, this function first expands it
+against @code{default-directory}.
 
 This function does not expand environment variables.  Only
 @code{substitute-in-file-name} does that.  @xref{Definition of
@@ -1081,28 +1082,29 @@
 @comment  node-name,  next,  previous,  up
 @subsection Other Information about Files
 
-  This section describes the functions for getting detailed information
-about a file, other than its contents.  This information includes the
-mode bits that control access permission, the owner and group numbers,
-the number of names, the inode number, the size, and the times of access
-and modification.
+  This section describes the functions for getting detailed
+information about a file, other than its contents.  This information
+includes the mode bits that control access permissions, the owner and
+group numbers, the number of names, the inode number, the size, and
+the times of access and modification.
 
 @defun file-modes filename
address@hidden permission
address@hidden file permissions
address@hidden permissions, file
 @cindex file attributes
-This function returns the mode bits of @var{filename}, as an integer.
-The mode bits are also called the file permissions, and they specify
-access control in the usual Unix fashion.  If the low-order bit is 1,
-then the file is executable by all users, if the second-lowest-order bit
-is 1, then the file is writable by all users, etc.
-
-The highest value returnable is 4095 (7777 octal), meaning that
-everyone has read, write, and execute permission, that the @acronym{SUID} bit
-is set for both others and group, and that the sticky bit is set.
-
-If @var{filename} does not exist, @code{file-modes} returns @code{nil}.
-
-This function recursively follows symbolic links at all levels.
address@hidden file modes
+This function returns the @dfn{mode bits} describing the @dfn{file
+permissions} of @var{filename}, as an integer.  It recursively follows
+symbolic links in @var{filename} at all levels.  If @var{filename}
+does not exist, the return value is @code{nil}.
+
address@hidden Permissions,,, coreutils, The @sc{gnu} @code{Coreutils}
+Manual}, for a description of mode bits.  If the low-order bit is 1,
+then the file is executable by all users, if the second-lowest-order
+bit is 1, then the file is writable by all users, etc.  The highest
+value returnable is 4095 (7777 octal), meaning that everyone has read,
+write, and execute permission, that the @acronym{SUID} bit is set for
+both others and group, and that the sticky bit is set.
 
 @example
 @group
@@ -1124,12 +1126,15 @@
   -rw-rw-rw-  1 lewis 0 3063 Oct 30 16:00 diffs
 @end group
 @end example
+
address@hidden Files}, for functions that change file permissions,
+such as @code{set-file-modes}.
 @end defun
 
-If the @var{filename} argument to the next two functions is a symbolic
-link, then these function do @emph{not} replace it with its target.
-However, they both recursively follow symbolic links at all levels of
-parent directories.
+  If the @var{filename} argument to the next two functions is a
+symbolic link, then these function do @emph{not} replace it with its
+target.  However, they both recursively follow symbolic links at all
+levels of parent directories.
 
 @defun file-nlinks filename
 This functions returns the number of names (i.e., hard links) that
@@ -1316,20 +1321,16 @@
 @cindex find file in path
 
   This section explains how to search for a file in a list of
-directories (a @dfn{path}).  One example is when you need to look for
-a program's executable file, e.g., to find out whether a given program
-is installed on the user's system.  Another example is the search for
-Lisp libraries (@pxref{Library Search}).  Such searches generally need
-to try various possible file name extensions, in addition to various
-possible directories.  Emacs provides a function for such a
-generalized search for a file.
+directories (a @dfn{path}), or for an executable file in the standard
+list of executable file directories, or for an Emacs-specific user
+configuration file.
 
 @defun locate-file filename path &optional suffixes predicate
 This function searches for a file whose name is @var{filename} in a
 list of directories given by @var{path}, trying the suffixes in
address@hidden  If it finds such a file, it returns the full
address@hidden file name} of the file (@pxref{Relative File Names});
-otherwise it returns @code{nil}.
address@hidden  If it finds such a file, it returns the file's
+absolute file name (@pxref{Relative File Names}); otherwise it returns
address@hidden
 
 The optional argument @var{suffixes} gives the list of file-name
 suffixes to append to @var{filename} when searching.
@@ -1337,24 +1338,23 @@
 suffixes.  If @var{suffixes} is @code{nil}, or @code{("")}, then there
 are no suffixes, and @var{filename} is used only as-is.  Typical
 values of @var{suffixes} are @code{exec-suffixes} (@pxref{Subprocess
-Creation, exec-suffixes}), @code{load-suffixes},
address@hidden and the return value of the function
address@hidden (@pxref{Load Suffixes}).
+Creation}), @code{load-suffixes}, @code{load-file-rep-suffixes} and
+the return value of the function @code{get-load-suffixes} (@pxref{Load
+Suffixes}).
 
 Typical values for @var{path} are @code{exec-path} (@pxref{Subprocess
-Creation, exec-path}) when looking for executable programs or
address@hidden (@pxref{Library Search, load-path}) when looking for
-Lisp files.  If @var{filename} is absolute, @var{path} has no effect,
-but the suffixes in @var{suffixes} are still tried.
+Creation}) when looking for executable programs, or @code{load-path}
+(@pxref{Library Search}) when looking for Lisp files.  If
address@hidden is absolute, @var{path} has no effect, but the suffixes
+in @var{suffixes} are still tried.
 
-The optional argument @var{predicate}, if address@hidden, specifies
-the predicate function to use for testing whether a candidate file is
-suitable.  The predicate function is passed the candidate file name as
-its single argument.  If @var{predicate} is @code{nil} or unspecified,
address@hidden uses @code{file-readable-p} as the default
-predicate.  Useful non-default predicates include
address@hidden, @code{file-directory-p}, and other
-predicates described in @ref{Kinds of Files}.
+The optional argument @var{predicate}, if address@hidden, specifies a
+predicate function for testing whether a candidate file is suitable.
+The predicate is passed the candidate file name as its single
+argument.  If @var{predicate} is @code{nil} or omitted,
address@hidden uses @code{file-readable-p} as the predicate.
address@hidden of Files}, for other useful predicates, e.g.@:
address@hidden and @code{file-directory-p}.
 
 For compatibility, @var{predicate} can also be one of the symbols
 @code{executable}, @code{readable}, @code{writable}, @code{exists}, or
@@ -1363,11 +1363,37 @@
 
 @defun executable-find program
 This function searches for the executable file of the named
address@hidden and returns the full absolute name of the executable,
address@hidden and returns the absolute file name of the executable,
 including its file-name extensions, if any.  It returns @code{nil} if
 the file is not found.  The functions searches in all the directories
-in @code{exec-path} and tries all the file-name extensions in
address@hidden
+in @code{exec-path}, and tries all the file-name extensions in
address@hidden (@pxref{Subprocess Creation}).
address@hidden defun
+
address@hidden locate-user-emacs-file base-name &optional old-name
+This function returns an absolute file name for an Emacs-specific
+configuration or data file.  The argument @file{base-name} should be a
+relative file name.  The return value is the absolute name of a file
+in the directory specified by @code{user-emacs-directory}; if that
+directory does not exist, this function creates it.
+
+If the optional argument @var{old-name} is address@hidden, it
+specifies a file in the user's home directory,
address@hidden/@var{old-name}}.  If such a file exists, the return value is
+the absolute name of that file, instead of the file specified by
address@hidden  This argument is intended to be used by Emacs
+packages to provide backward compatibility.  For instance, prior to
+the introduction of @code{user-emacs-directory}, the abbrev file was
+located in @file{~/.abbrev_defs}, so the definition of
address@hidden is
+
address@hidden
+(defcustom abbrev-file-name
+  (locate-user-emacs-file "abbrev_defs" ".abbrev_defs")
+  "Default name of file from which to read abbrevs."
+  @dots{}
+  :type 'file)
address@hidden example
 @end defun
 
 @node Changing Files
@@ -1378,8 +1404,8 @@
 @cindex linking files
 @cindex setting modes of files
 
-  The functions in this section rename, copy, delete, link, and set the
-modes of files.
+  The functions in this section rename, copy, delete, link, and set
+the modes (permissions) of files.
 
   In the functions that have an argument @var{newname}, if a file by the
 name of @var{newname} already exists, the actions taken depend on the
@@ -1548,54 +1574,67 @@
 See also @code{delete-directory} in @ref{Create/Delete Dirs}.
 @end deffn
 
address@hidden file permissions, setting
address@hidden permissions, file
address@hidden file modes, setting
 @deffn Command set-file-modes filename mode
-This function sets mode bits of @var{filename} to @var{mode} (which
-must be an integer when the function is called non-interactively).
-Only the low 12 bits of @var{mode} are used.
+This function sets the @dfn{file mode} (or @dfn{file permissions}) of
address@hidden to @var{mode}.  It recursively follows symbolic links
+at all levels for @var{filename}.
+
+If called non-interactively, @var{mode} must be an integer.  Only the
+lowest 12 bits of the integer are used; on most systems, only the
+lowest 9 bits are meaningful.  You can use the Lisp construct for
+octal numbers to enter @var{mode}.  For example,
+
address@hidden
+(set-file-modes #o644)
address@hidden example
+
address@hidden
+specifies that the file should be readable and writable for its owner,
+readable for group members, and readable for all other users.
address@hidden Permissions,,, coreutils, The @sc{gnu} @code{Coreutils}
+Manual}, for a description of mode bit specifications.
 
 Interactively, @var{mode} is read from the minibuffer using
address@hidden, which accepts mode bits either as a number or
-as a character string representing the mode bits symbolically.  See
-the description of @code{read-file-modes} below for the supported
-forms of symbolic notation for mode bits.
address@hidden (see below), which lets the user type in either
+an integer or a string representing the permissions symbolically.
 
-This function recursively follows symbolic links at all levels for
address@hidden
address@hidden Attributes}, for the function @code{file-modes}, which
+returns the permissions of a file.
 @end deffn
 
address@hidden Emacs 19 feature
 @defun set-default-file-modes mode
 @cindex umask
-This function sets the default file protection for new files created by
-Emacs and its subprocesses.  Every file created with Emacs initially has
-this protection, or a subset of it (@code{write-region} will not give a
-file execute permission even if the default file protection allows
-execute permission).  On Unix and GNU/Linux, the default protection is
-the bitwise complement of the ``umask'' value.
-
-The argument @var{mode} must be an integer.  On most systems, only the
-low 9 bits of @var{mode} are meaningful.  You can use the Lisp construct
-for octal numbers to enter @var{mode}; for example,
-
address@hidden
-(set-default-file-modes #o644)
address@hidden example
-
-Saving a modified version of an existing file does not count as creating
-the file; it preserves the existing file's mode, whatever that is.  So
-the default file protection has no effect.
+This function sets the default file permissions for new files created
+by Emacs and its subprocesses.  Every file created with Emacs
+initially has these permissions, or a subset of them
+(@code{write-region} will not grant execute permissions even if the
+default file permissions allow execution).  On Unix and GNU/Linux, the
+default permissions are given by the bitwise complement of the
+``umask'' value.
+
+The argument @var{mode} should be an integer which specifies the
+permissions, similar to @code{set-file-modes} above.  Only the lowest
+9 bits are meaningful.
+
+The default file permissions have no effect when you save a modified
+version of an existing file; saving a file preserves its existing
+permissions.
 @end defun
 
 @defun default-file-modes
-This function returns the current default protection value.
+This function returns the default file permissions, as an integer.
 @end defun
 
 @defun read-file-modes &optional prompt base-file
-This function reads file mode bits from the minibuffer.  The optional
-argument @var{prompt} specifies a non-default prompt.  Second optional
-argument @var{base-file} is the name of a file on whose permissions to
-base the mode bits that this function returns, if what the user types
-specifies mode bits relative to permissions of an existing file.
+This function reads a set of file mode bits from the minibuffer.  The
+first optional argument @var{prompt} specifies a non-default prompt.
+Second second optional argument @var{base-file} is the name of a file
+on whose permissions to base the mode bits that this function returns,
+if what the user types specifies mode bits relative to permissions of
+an existing file.
 
 If user input represents an octal number, this function returns that
 number.  If it is a complete symbolic specification of mode bits, as
@@ -1607,16 +1646,16 @@
 @code{nil}, the function uses @code{0} as the base mode bits.  The
 complete and relative specifications can be combined, as in
 @code{"u+r,g+rx,o+r,g-w"}.  @xref{File Permissions,,, coreutils, The
address@hidden @code{Coreutils} Manual}, for detailed description of
-symbolic mode bits specifications.
address@hidden @code{Coreutils} Manual}, for a description of file mode
+specifications.
 @end defun
 
 @defun file-modes-symbolic-to-number modes &optional base-modes
-This subroutine converts a symbolic specification of file mode bits in
address@hidden into the equivalent numeric value.  If the symbolic
+This function converts a symbolic file mode specification in
address@hidden into the equivalent integer value.  If the symbolic
 specification is based on an existing file, that file's mode bits are
 taken from the optional argument @var{base-modes}; if that argument is
-omitted or @code{nil}, it defaults to zero, i.e.@: no access rights at
+omitted or @code{nil}, it defaults to 0, i.e.@: no access rights at
 all.
 @end defun
 
@@ -2175,25 +2214,6 @@
 address@hidden  To use it, you should expand the prefix against
 the proper directory before calling @code{make-temp-file}.
 
-  In older Emacs versions where @code{make-temp-file} does not exist,
-you should use @code{make-temp-name} instead:
-
address@hidden
-(make-temp-name
- (expand-file-name @var{name-of-application}
-                   temporary-file-directory))
address@hidden example
-
address@hidden make-temp-name string
-This function generates a string that can be used as a unique file
-name.  The name starts with @var{string}, and has several random
-characters appended to it, which are different in each Emacs job.  It
-is like @code{make-temp-file} except that it just constructs a name,
-and does not create a file.  Another difference is that @var{string}
-should be an absolute file name.  On MS-DOS, this function can
-truncate the @var{string} prefix to fit into the 8+3 file-name limits.
address@hidden defun
-
 @defopt temporary-file-directory
 @cindex @code{TMPDIR} environment variable
 @cindex @code{TMP} environment variable
@@ -2231,6 +2251,21 @@
 @end example
 @end defopt
 
address@hidden make-temp-name base-name
+This function generates a string that can be used as a unique file
+name.  The name starts with @var{base-name}, and has several random
+characters appended to it, which are different in each Emacs job.  It
+is like @code{make-temp-file} except that (i) it just constructs a
+name, and does not create a file, and (ii) @var{base-name} should be
+an absolute file name (on MS-DOS, this function can truncate
address@hidden to fit into the 8+3 file-name limits).
+
address@hidden:} In most cases, you should not use this function; use
address@hidden instead!  This function is susceptible to a race
+condition, between the @code{make-temp-name} call and the creation of
+the file, which in some cases may cause a security hole.
address@hidden defun
+
 @node File Name Completion
 @subsection File Name Completion
 @cindex file name completion subroutines
@@ -2555,7 +2590,6 @@
 @section Making Certain File Names ``Magic''
 @cindex magic file names
 
address@hidden Emacs 19 feature
   You can implement special handling for certain file names.  This is
 called making those names @dfn{magic}.  The principal use for this
 feature is in implementing remote file names (@pxref{Remote Files,,
@@ -2564,7 +2598,7 @@
   To define a kind of magic file name, you must supply a regular
 expression to define the class of names (all those that match the
 regular expression), plus a handler that implements all the primitive
-Emacs file operations for file names that do match.
+Emacs file operations for file names that match.
 
 @vindex file-name-handler-alist
   The variable @code{file-name-handler-alist} holds a list of handlers,

=== modified file 'doc/lispref/vol1.texi'
--- a/doc/lispref/vol1.texi     2012-02-19 05:54:33 +0000
+++ b/doc/lispref/vol1.texi     2012-02-21 13:24:48 +0000
@@ -864,12 +864,11 @@
 * File Locks::              Locking and unlocking files, to prevent
                               simultaneous editing by two people.
 * Information about Files:: Testing existence, accessibility, size of files.
-* Changing Files::          Renaming files, changing protection, etc.
+* Changing Files::          Renaming files, changing permissions, etc.
 * File Names::              Decomposing and expanding file names.
 * Contents of Directories:: Getting a list of the files in a directory.
 * Create/Delete Dirs::      Creating and Deleting Directories.
-* Magic File Names::        Defining "magic" special handling
-                              for certain file names.
+* Magic File Names::        Special handling for certain file names.
 * Format Conversion::       Conversion to and from various file formats.
 
 Visiting Files

=== modified file 'doc/lispref/vol2.texi'
--- a/doc/lispref/vol2.texi     2012-02-19 05:54:33 +0000
+++ b/doc/lispref/vol2.texi     2012-02-21 13:24:48 +0000
@@ -863,12 +863,11 @@
 * File Locks::              Locking and unlocking files, to prevent
                               simultaneous editing by two people.
 * Information about Files:: Testing existence, accessibility, size of files.
-* Changing Files::          Renaming files, changing protection, etc.
+* Changing Files::          Renaming files, changing permissions, etc.
 * File Names::              Decomposing and expanding file names.
 * Contents of Directories:: Getting a list of the files in a directory.
 * Create/Delete Dirs::      Creating and Deleting Directories.
-* Magic File Names::        Defining "magic" special handling
-                              for certain file names.
+* Magic File Names::        Special handling for certain file names.
 * Format Conversion::       Conversion to and from various file formats.
 
 Visiting Files

=== modified file 'src/ChangeLog'
--- a/src/ChangeLog     2012-02-21 00:07:53 +0000
+++ b/src/ChangeLog     2012-02-21 13:24:48 +0000
@@ -1,3 +1,10 @@
+2012-02-21  Chong Yidong  <address@hidden>
+
+       * 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  <address@hidden>
 
        * .gdbinit (xreload): Don't assume EMACS_INT fits in 'long'

=== modified file 'src/buffer.c'
--- a/src/buffer.c      2012-02-07 06:34:52 +0000
+++ b/src/buffer.c      2012-02-21 13:24:48 +0000
@@ -272,7 +272,11 @@
      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))
     {

=== modified file 'src/fileio.c'
--- a/src/fileio.c      2012-02-19 09:58:23 +0000
+++ b/src/fileio.c      2012-02-21 13:24:48 +0000
@@ -5640,18 +5640,25 @@
        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",