@c -*-texinfo-*-
@c This is part of the GNU Emacs Lisp Reference Manual.
-@c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1998, 1999, 2002, 2003,
-@c 2004, 2005, 2006 Free Software Foundation, Inc.
+@c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1998, 1999, 2001,
+@c 2002, 2003, 2004, 2005, 2006, 2007, 2008 Free Software Foundation, Inc.
@c See the file elisp.texi for copying conditions.
@setfilename ../info/files
@node Files, Backups and Auto-Saving, Documentation, Top
@end deffn
@defun find-file-noselect filename &optional nowarn rawfile wildcards
-This function is the guts of all the file-visiting functions. It finds
-or creates a buffer visiting the file @var{filename}, and returns it.
-It uses an existing buffer if there is one, and otherwise creates a new
-buffer and reads the file into it. You may make the buffer current or
-display it in a window if you wish, but this function does not do so.
-
-If @var{wildcards} is non-@code{nil},
-then @code{find-file-noselect} expands wildcard
-characters in @var{filename} and visits all the matching files.
-
-When @code{find-file-noselect} uses an existing buffer, it first
-verifies that the file has not changed since it was last visited or
-saved in that buffer. If the file has changed, then this function asks
-the user whether to reread the changed file. If the user says
-@samp{yes}, any changes previously made in the buffer are lost.
+This function is the guts of all the file-visiting functions. It
+returns a buffer visiting the file @var{filename}. You may make the
+buffer current or display it in a window if you wish, but this
+function does not do so.
+
+The function returns an existing buffer if there is one; otherwise it
+creates a new buffer and reads the file into it. When
+@code{find-file-noselect} uses an existing buffer, it first verifies
+that the file has not changed since it was last visited or saved in
+that buffer. If the file has changed, this function asks the user
+whether to reread the changed file. If the user says @samp{yes}, any
+edits previously made in the buffer are lost.
+
+Reading the file involves decoding the file's contents (@pxref{Coding
+Systems}), including end-of-line conversion, and format conversion
+(@pxref{Format Conversion}). If @var{wildcards} is non-@code{nil},
+then @code{find-file-noselect} expands wildcard characters in
+@var{filename} and visits all the matching files.
This function displays warning or advisory messages in various peculiar
cases, unless the optional argument @var{nowarn} is non-@code{nil}. For
If the optional argument @var{rawfile} is non-@code{nil}, then
@code{after-find-file} is not called, and the
-@code{find-file-not-found-functions} are not run in case of failure. What's
-more, a non-@code{nil} @var{rawfile} value suppresses coding system
-conversion (@pxref{Coding Systems}) and format conversion (@pxref{Format
-Conversion}).
+@code{find-file-not-found-functions} are not run in case of failure.
+What's more, a non-@code{nil} @var{rawfile} value suppresses coding
+system conversion and format conversion.
The @code{find-file-noselect} function usually returns the buffer that
is visiting the file @var{filename}. But, if wildcards are actually
@var{filename}.
@end deffn
-@tindex find-file-wildcards
@defopt find-file-wildcards
If this variable is non-@code{nil}, then the various @code{find-file}
commands check for wildcard characters and visit all the files that
@node Saving Buffers
@section Saving Buffers
+@cindex saving buffers
When you edit a file in Emacs, you are actually working on a buffer
that is visiting that file---that is, the contents of the file are
bits of the file that you write. This is what @code{save-buffer}
normally does. @xref{Making Backups,, Making Backup Files}.
-The hook functions in @code{write-file-functions} are also responsible for
-encoding the data (if desired): they must choose a suitable coding
-system (@pxref{Lisp and Coding Systems}), perform the encoding
-(@pxref{Explicit Encoding}), and set @code{last-coding-system-used} to
-the coding system that was used (@pxref{Encoding and I/O}).
+The hook functions in @code{write-file-functions} are also responsible
+for encoding the data (if desired): they must choose a suitable coding
+system and end-of-line conversion (@pxref{Lisp and Coding Systems}),
+perform the encoding (@pxref{Explicit Encoding}), and set
+@code{last-coding-system-used} to the coding system that was used
+(@pxref{Encoding and I/O}).
If you set this hook locally in a buffer, it is assumed to be
associated with the file or the way the contents of the buffer were
@node Reading from Files
@comment node-name, next, previous, up
@section Reading from Files
+@cindex reading from files
You can copy a file from the disk and insert it into a buffer
using the @code{insert-file-contents} function. Don't use the user-level
the list @code{after-insert-file-functions}; see @ref{Saving
Properties}. 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.
+(@pxref{Coding Systems}) used for decoding the file's contents,
+including end-of-line conversion.
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
@node Writing to Files
@comment node-name, next, previous, up
@section Writing to Files
+@cindex writing to files
You can write the contents of a buffer, or part of a buffer, directly
to a file on disk using the @code{append-to-file} and
@node File Locks
@section File Locks
@cindex file locks
+@cindex lock file
When two users edit the same file at the same time, they are likely
to interfere with each other. Emacs tries to prevent this situation
stored in the same directory as the file you are editing.
When you access files using NFS, there may be a small probability that
-you and another user will both lock the same file ``simultaneously''.
+you and another user will both lock the same file ``simultaneously.''
If this happens, it is possible for the two users to make changes
simultaneously, but Emacs will still warn the user who saves second.
Also, the detection of modification of a buffer visiting a file changed
@node Information about Files
@section Information about Files
+@cindex file, information about
The functions described in this section all operate on strings that
designate file names. With a few exceptions, all the functions have
(@pxref{Changing Files}).
@item
-The file's @acronym{UID} as a string or an integer. If a string
-value cannot be looked up, the integer value is returned.
+The file's @acronym{UID}, normally as a string. However, if it does
+not correspond to a named user, the value is an integer or a floating
+point number.
@item
-The file's @acronym{GID} likewise.
+The file's @acronym{GID}, likewise.
@item
The time of last access, as a list of two integers.
@item
The time of last modification as a list of two integers (as above).
+@cindex modification time of file
@item
The time of last status change as a list of two integers (as above).
@node Locating Files
@subsection How to Locate Files in Standard Places
-@cindex locate files
-@cindex find files
+@cindex locate file in path
+@cindex find file in path
This section explains how to search for a file in a list of
-directories. 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
+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
a list of one or more of these symbols.
@end defun
-@cindex find executable program
@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,
@node Changing Files
@section Changing File Names and Attributes
-@cindex renaming files
+@c @cindex renaming files Duplicates rename-file
@cindex copying files
@cindex deleting files
@cindex linking files
same effect as renaming, aside from momentary intermediate states.
@end deffn
-@deffn Command copy-file oldname newname &optional ok-if-exists time mustbenew
+@deffn Command copy-file oldname newname &optional ok-if-exists time preserve-uid-gid
This command copies the file @var{oldname} to @var{newname}. An
error is signaled if @var{oldname} does not exist. If @var{newname}
names a directory, it copies @var{oldname} into that directory,
If @var{time} is non-@code{nil}, then this function gives the new file
the same last-modified time that the old one has. (This works on only
some operating systems.) If setting the time gets an error,
-@code{copy-file} signals a @code{file-date-error} error.
+@code{copy-file} signals a @code{file-date-error} error. In an
+interactive call, a prefix argument specifies a non-@code{nil} value
+for @var{time}.
This function copies the file modes, too.
-In an interactive call, a prefix argument specifies a non-@code{nil}
-value for @var{time}.
-
-The argument @var{mustbenew} controls whether an existing file can be
-overwritten. It works like the similarly-named argument of
-@code{write-region} (@pxref{Writing to Files, mustbenew}).
+If argument @var{preserve-uid-gid} is @code{nil}, we let the operating
+system decide the user and group ownership of the new file (this is
+usually set to the user running Emacs). If @var{preserve-uid-gid} is
+non-@code{nil}, we attempt to copy the user and group ownership of the
+file. This works only on some operating systems, and only if you have
+the correct permissions to do so.
@end deffn
@deffn Command make-symbolic-link filename newname &optional ok-if-exists
@var{filename} does not include a directory part.
On GNU and Unix systems, a string returned by this function always
-ends in a slash. On MSDOS it can also end in a colon. On VMS, it
+ends in a slash. On MS-DOS it can also end in a colon. On VMS, it
returns a string ending in one of the three characters @samp{:},
@samp{]}, or @samp{>}.
@end defun
@defun file-name-extension filename &optional period
-This function returns @var{filename}'s final ``extension'', if any,
+This function returns @var{filename}'s final ``extension,'' if any,
after applying @code{file-name-sans-versions} to remove any
version/backup part. The extension, in a file name, is the part that
starts with the last @samp{.} in the last name component (minus
Andrew Innes says that this
@c @defvar directory-sep-char
-@c @tindex directory-sep-char
This variable holds the character that Emacs normally uses to separate
file name components. The default value is @code{?/}, but on MS-Windows
you can set it to @code{?\\}; then the functions that transform file names
same as the usual Unix terminology.) These two different names for
the same entity are related by a syntactic transformation. On GNU and
Unix systems, this is simple: a directory name ends in a slash,
-whereas the directory's name as a file lacks that slash. On MSDOS and
+whereas the directory's name as a file lacks that slash. On MS-DOS and
VMS, the relationship is more complicated.
The difference between a directory name and its name as a file is
@end group
@end example
+In some cases, a leading @samp{..} component can remain in the output:
+
+@example
+@group
+(expand-file-name "../home" "/")
+ @result{} "/../home"
+@end group
+@end example
+
+@noindent
+This is for the sake of filesystems that have the concept of a
+``superroot'' above the root directory @file{/}. On other filesystems,
+@file{/../} is interpreted exactly the same as @file{/}.
+
Note that @code{expand-file-name} does @emph{not} expand environment
variables; only @code{substitute-in-file-name} does that.
two different jobs from trying to use the exact same file name.
@defun make-temp-file prefix &optional dir-flag suffix
-@tindex make-temp-file
This function creates a temporary file and returns its name. Emacs
creates the temporary file's name by adding to @var{prefix} some
random characters that are different in each Emacs job. The result is
non-@code{nil}.
@end defvar
-@tindex small-temporary-file-directory
@defvar small-temporary-file-directory
This variable specifies the directory name for
creating certain temporary files, which are likely to be small.
@cindex completion, file name
This section describes low-level subroutines for completing a file
-name. For other completion functions, see @ref{Completion}.
+name. For higher level functions, see @ref{Reading File Names}.
@defun file-name-all-completions partial-filename directory
This function returns a list of all possible completions for a file
@end example
@end defun
-@defun file-name-completion filename directory
+@defun file-name-completion filename directory &optional predicate
This function completes the file name @var{filename} in directory
@var{directory}. It returns the longest prefix common to all file names
-in directory @var{directory} that start with @var{filename}.
+in directory @var{directory} that start with @var{filename}. If
+@var{predicate} is non-@code{nil} then it ignores possible completions
+that don't satisfy @var{predicate}, after calling that function
+with one argument, the expanded absolute file name.
If only one match exists and @var{filename} matches it exactly, the
function returns @code{t}. The function returns @code{nil} if directory
If @var{match-regexp} is non-@code{nil}, this function returns only
those file names that contain a match for that regular expression---the
-other file names are excluded from the list.
+other file names are excluded from the list. On case-insensitive
+filesystems, the regular expression matching is case-insensitive.
@c Emacs 19 feature
If @var{nosort} is non-@code{nil}, @code{directory-files} does not sort
@var{file} in directory @var{dirname}. It is only available on VMS.
@end defun
-@tindex file-expand-wildcards
@defun file-expand-wildcards pattern &optional full
This function expands the wildcard pattern @var{pattern}, returning
a list of file names that match it.
@node Create/Delete Dirs
@section Creating and Deleting Directories
+@cindex creating and deleting directories
@c Emacs 19 features
Most Emacs Lisp file-manipulation functions get errors when used on
is chosen so that handlers for jobs such as uncompression are handled
first, before handlers for jobs such as remote file access.
-Here are the operations that a magic file name handler gets to handle:
+ Here are the operations that a magic file name handler gets to handle:
@ifnottex
@noindent
possibly others to be added in the future. It need not implement all
these operations itself---when it has nothing special to do for a
certain operation, it can reinvoke the primitive, to handle the
-operation ``in the usual way''. It should always reinvoke the primitive
+operation ``in the usual way.'' It should always reinvoke the primitive
for an operation it does not recognize. Here's one way to do this:
@smallexample
functions, so that they won't be loaded except when they have real
work to do.
+ Simply deferring all operations to the usual primitives does not
+work. For instance, if the file name handler applies to
+@code{file-exists-p}, then it must handle @code{load} itself, because
+the usual @code{load} code won't work properly in that case. However,
+if the handler uses the @code{operations} property to say it doesn't
+handle @code{file-exists-p}, then it need not handle @code{load}
+nontrivially.
+
@defvar inhibit-file-name-handlers
This variable holds a list of handlers whose use is presently inhibited
for a certain operation.
If @var{to-fn} is a string, it is a shell command; Emacs runs the
command as a filter to perform the conversion.
-If @var{to-fn} is a function, it is called with two arguments, @var{begin}
-and @var{end}, which specify the part of the buffer it should convert.
-There are two ways it can do the conversion:
+If @var{to-fn} is a function, it is called with three arguments:
+@var{begin} and @var{end}, which specify the part of the buffer it
+should convert, and @var{buffer}, which specifies which buffer. There
+are two ways it can do the conversion:
@itemize @bullet
@item