From: Chong Yidong Date: Tue, 21 Feb 2012 13:24:48 +0000 (+0800) Subject: Update Files chapter in Lisp manual. X-Git-Tag: emacs-pretest-24.0.94~81 X-Git-Url: http://git.eshelyaron.com/gitweb/?a=commitdiff_plain;h=a59225b146620b11455b614244ceb6d02339a032;p=emacs.git 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. --- diff --git a/admin/FOR-RELEASE b/admin/FOR-RELEASE index d1150b6d60b..7ad484a535e 100644 --- a/admin/FOR-RELEASE +++ b/admin/FOR-RELEASE @@ -83,8 +83,6 @@ and change key bindings where necessary. The current list of modes: * 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 @@ edebug.texi elisp.texi errors.texi eval.texi cyd -files.texi +files.texi cyd frames.texi functions.texi cyd hash.texi cyd @@ -229,10 +227,6 @@ tips.texi variables.texi cyd windows.texi -* PLANNED ADDITIONS -* pov-mode (waiting for a Free POV-Ray) -** gas-mode ? - Local variables: mode: outline diff --git a/doc/lispref/ChangeLog b/doc/lispref/ChangeLog index ef8cbf04757..4c69a309ca8 100644 --- a/doc/lispref/ChangeLog +++ b/doc/lispref/ChangeLog @@ -1,3 +1,13 @@ +2012-02-21 Chong Yidong + + * 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 * help.texi (Documentation, Documentation Basics, Help Functions): diff --git a/doc/lispref/elisp.texi b/doc/lispref/elisp.texi index 14ad624da86..05245331af2 100644 --- a/doc/lispref/elisp.texi +++ b/doc/lispref/elisp.texi @@ -843,12 +843,11 @@ Files * 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 diff --git a/doc/lispref/files.texi b/doc/lispref/files.texi index cf093ba36cb..69e0003a46b 100644 --- a/doc/lispref/files.texi +++ b/doc/lispref/files.texi @@ -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 @@ described in @ref{Backups and Auto-Saving}. 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 -@samp{../}). These functions don't recognize environment variable -substitutions such as @samp{$HOME}. @xref{File Name Expansion}. +@samp{../}). @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 @@ to locale @code{system-message-locale}, and decoded using coding system * 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 @@ current buffer after point. It returns a list of the absolute file name 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}. +@xref{Format 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 -@ref{Lisp and Coding Systems, inhibit-null-byte-detection}, for how to -control this behavior. +bytes, it is by default visited without any code conversions. +@xref{Lisp and Coding Systems, inhibit-null-byte-detection}. If @var{visit} is non-@code{nil}, this function additionally marks the buffer as unmodified and sets up various fields in the buffer so that it @@ -554,11 +558,9 @@ with @code{insert-file-contents}, as long as @var{replace} and @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 -@code{find-file-hook}, 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 @@ This function returns @code{t} if a file named @var{filename} appears 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 @@ other I/O device). @subsection Truenames @cindex truename (of file) -@c 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 @@ the number of hard links to the file. However, truenames are useful 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 -@var{filename}. 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 @@ we would have: @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 -@cindex permission +@cindex file permissions +@cindex 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. +@cindex 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}. + +@xref{File 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 @@ This function recursively follows symbolic links at all levels. -rw-rw-rw- 1 lewis 0 3063 Oct 30 16:00 diffs @end group @end example + +@xref{Changing 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 @@ reported with executable bit set, for compatibility with Unix. @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 -@var{suffixes}. If it finds such a file, it returns the full -@dfn{absolute file name} of the file (@pxref{Relative File Names}); -otherwise it returns @code{nil}. +@var{suffixes}. If it finds such a file, it returns the file's +absolute file name (@pxref{Relative File Names}); otherwise it returns +@code{nil}. The optional argument @var{suffixes} gives the list of file-name suffixes to append to @var{filename} when searching. @@ -1337,24 +1338,23 @@ suffixes to append to @var{filename} when searching. 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}, -@code{load-file-rep-suffixes} and the return value of the function -@code{get-load-suffixes} (@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 -@code{load-path} (@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. - -The optional argument @var{predicate}, if non-@code{nil}, 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, -@code{locate-file} uses @code{file-readable-p} as the default -predicate. Useful non-default predicates include -@code{file-executable-p}, @code{file-directory-p}, and other -predicates described in @ref{Kinds of Files}. +Creation}) when looking for executable programs, or @code{load-path} +(@pxref{Library Search}) when looking for Lisp files. If +@var{filename} is absolute, @var{path} has no effect, but the suffixes +in @var{suffixes} are still tried. + +The optional argument @var{predicate}, if non-@code{nil}, 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, +@code{locate-file} uses @code{file-readable-p} as the predicate. +@xref{Kinds of Files}, for other useful predicates, e.g.@: +@code{file-executable-p} 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 @@ a list of one or more of these symbols. @defun executable-find program This function searches for the executable file of the named -@var{program} and returns the full absolute name of the executable, +@var{program} 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 -@code{exec-suffixes}. +in @code{exec-path}, and tries all the file-name extensions in +@code{exec-suffixes} (@pxref{Subprocess Creation}). +@end defun + +@defun 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 non-@code{nil}, it +specifies a file in the user's home directory, +@file{~/@var{old-name}}. If such a file exists, the return value is +the absolute name of that file, instead of the file specified by +@var{base-name}. 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 +@code{abbrev-file-name} is + +@example +(defcustom abbrev-file-name + (locate-user-emacs-file "abbrev_defs" ".abbrev_defs") + "Default name of file from which to read abbrevs." + @dots{} + :type 'file) +@end example @end defun @node Changing Files @@ -1378,8 +1404,8 @@ in @code{exec-path} and tries all the file-name extensions in @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 @@ no prefix argument is given, and @code{nil} otherwise. See also @code{delete-directory} in @ref{Create/Delete Dirs}. @end deffn +@cindex file permissions, setting +@cindex permissions, file +@cindex 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 +@var{filename} 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, + +@example +(set-file-modes #o644) +@end example + +@noindent +specifies that the file should be readable and writable for its owner, +readable for group members, and readable for all other users. +@xref{File Permissions,,, coreutils, The @sc{gnu} @code{Coreutils} +Manual}, for a description of mode bit specifications. Interactively, @var{mode} is read from the minibuffer using -@code{read-file-modes}, 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. +@code{read-file-modes} (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 -@var{filename}. +@xref{File Attributes}, for the function @code{file-modes}, which +returns the permissions of a file. @end deffn -@c 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, - -@example -(set-default-file-modes #o644) -@end 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 @@ mode bits of @var{base-file}. If @var{base-file} is omitted or @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 -@sc{gnu} @code{Coreutils} Manual}, for detailed description of -symbolic mode bits specifications. +@sc{gnu} @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 -@var{modes} into the equivalent numeric value. If the symbolic +This function converts a symbolic file mode specification in +@var{modes} 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 @@ programs use @code{small-temporary-file-directory} instead, if that is non-@code{nil}. 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: - -@example -(make-temp-name - (expand-file-name @var{name-of-application} - temporary-file-directory)) -@end example - -@defun 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. -@end defun - @defopt temporary-file-directory @cindex @code{TMPDIR} environment variable @cindex @code{TMP} environment variable @@ -2231,6 +2251,21 @@ should compute the directory like this: @end example @end defopt +@defun 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 +@var{base-name} to fit into the 8+3 file-name limits). + +@strong{Warning:} In most cases, you should not use this function; use +@code{make-temp-file} 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. +@end defun + @node File Name Completion @subsection File Name Completion @cindex file name completion subroutines @@ -2555,7 +2590,6 @@ no prefix argument is given, and @code{nil} otherwise. @section Making Certain File Names ``Magic'' @cindex magic file names -@c 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 @@ Remote Files, emacs, The GNU Emacs Manual}). 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, diff --git a/doc/lispref/vol1.texi b/doc/lispref/vol1.texi index 759c83dfe2b..addc4bd6d69 100644 --- a/doc/lispref/vol1.texi +++ b/doc/lispref/vol1.texi @@ -864,12 +864,11 @@ Files * 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 diff --git a/doc/lispref/vol2.texi b/doc/lispref/vol2.texi index c70dfd8c6f8..0f6b020db49 100644 --- a/doc/lispref/vol2.texi +++ b/doc/lispref/vol2.texi @@ -863,12 +863,11 @@ Files * 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 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 + + * 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 * .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",