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