@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
@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
@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
@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
@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
@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