@c -*-texinfo-*-
@c This is part of the GNU Emacs Lisp Reference Manual.
-@c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1998 Free Software Foundation, Inc.
+@c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1998, 1999
+@c Free Software Foundation, Inc.
@c See the file elisp.texi for copying conditions.
@setfilename ../info/files
@node Files, Backups and Auto-Saving, Documentation, Top
conversion (@pxref{Coding Systems}) and format conversion (@pxref{Format
Conversion}).
-The @code{find-file-noselect} function returns the buffer that is
-visiting the file @var{filename}.
+The @code{find-file-noselect} function usually returns the buffer that
+is visiting the file @var{filename}. But, if wildcards are actually
+used and expanded, it returns a list of buffers that are visiting the
+various files.
@example
@group
@end itemize
@end deffn
-@deffn Command save-some-buffers &optional save-silently-p exiting
+@deffn Command save-some-buffers &optional save-silently-p pred
This command saves some modified file-visiting buffers. Normally it
asks the user about each buffer. But if @var{save-silently-p} is
non-@code{nil}, it saves all the file-visiting buffers without querying
the user.
-The optional @var{exiting} argument, if non-@code{nil}, requests this
-function to offer also to save certain other buffers that are not
-visiting files. These are buffers that have a non-@code{nil}
-buffer-local value of @code{buffer-offer-save}. (A user who says @samp{yes} to
-saving one of these is asked to specify a file name to use.) The
-@code{save-buffers-kill-emacs} function passes a non-@code{nil} value
-for this argument.
+The optional @var{pred} argument controls which buffers to ask about.
+If it is @code{nil}, that means to ask only about file-visiting buffers.
+If it is @code{t}, that means also offer to save certain other non-file
+buffers---those that have a non-@code{nil} buffer-local value of
+@code{buffer-offer-save}. (A user who says @samp{yes} to saving a
+non-file buffer is asked to specify the file name to use.) The
+@code{save-buffers-kill-emacs} function passes the value @code{t} for
+@var{pred}.
+
+If @var{pred} is neither @code{t} nor @code{nil}, then it should be
+a function of no arguments. It will be called in each buffer to decide
+whether to offer to save that buffer. If it returns a non-@code{nil}
+value in a certain buffer, that means do offer to save that buffer.
@end deffn
@deffn Command write-file filename &optional confirm
@end defun
@defun insert-file-contents-literally filename &optional visit beg end replace
-@tindex insert-file-contents-literally
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
this case.
If @var{append} is non-@code{nil}, then the specified text is appended
-to the existing file contents (if any).
+to the existing file contents (if any). Starting in Emacs 21, if
+@var{append} is an integer, then @code{write-region} seeks to that byte
+offset from the start of the file and writes the data from there.
If @var{mustbenew} is non-@code{nil}, then @code{write-region} asks
for confirmation if @var{filename} names an existing file.
@end deffn
@defmac with-temp-file file body...
-@tindex with-temp-file
The @code{with-temp-file} macro evaluates the @var{body} forms with a
temporary buffer as the current buffer; then, at the end, it writes the
buffer contents into file @var{file}. It kills the temporary buffer
@end defun
@defun access-file filename string
-@tindex access-file
This function opens file @var{filename} for reading, then closes it and
returns @code{nil}. However, if the open fails, it signals an error
using @var{string} as the error message text.
@defun set-default-file-modes mode
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. On Unix and GNU/Linux, the default protection is the
-bitwise complement of the ``umask'' value.
+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.
+low 9 bits of @var{mode} are meaningful. You can use the Lisp construct
+for octal character codes to enter @var{mode}; for example,
+
+@example
+(set-default-file-modes ?\644)
+@end example
Saving a modified version of an existing file does not count as creating
-the file; it does not change the file's mode, and does not use the
-default file protection.
+the file; it preserves the existing file's mode, whatever that is. So
+the default file protection has no effect.
@end defun
@defun default-file-modes
can operate on file names that do not refer to an existing file or
directory.
- On VMS, all these functions understand both VMS file-name syntax and
-Unix syntax. This is so that all the standard Lisp libraries can
-specify file names in Unix syntax and work properly on VMS without
-change. On MS-DOS and MS-Windows, these functions understand MS-DOS or
-MS-Windows file-name syntax as well as Unix syntax.
+ On MS-DOS and MS-Windows, these functions (like the function that
+actually operate on files) accept MS-DOS or MS-Windows file-name syntax,
+where backslashes separate the components, as well as Unix syntax; but
+they always return Unix syntax. On VMS, these functions (and the ones
+that operate on files) understand both VMS file-name syntax and Unix
+syntax. This enables Lisp programs to specify file names in Unix syntax
+and work properly on all systems without change.
@menu
* File Name Components:: The directory part of a file name, and the rest.
Concatenating these two parts reproduces the original file name.
On most systems, the directory part is everything up to and including
-the last slash; the nondirectory part is the rest. The rules in VMS
-syntax are complicated.
+the last slash (backslash is also allowed in input on MS-DOS or
+MS-Windows); the nondirectory part is the rest. The rules in VMS syntax
+are complicated.
For some purposes, the nondirectory part is further subdivided into
the name proper and the @dfn{version number}. On most systems, only
@end example
@end defun
+@ignore
+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
+use backslashes in their output.
+
+File names using backslashes work as input to Lisp primitives even on
+MS-DOS and MS-Windows, even if @code{directory-sep-char} has its default
+value of @code{?/}.
+@end defvar
+@end ignore
+
+@defun file-name-extension filename &optional period
+This function returns @var{filename}'s final ``extension,'' if any,
+after applying @code{file-name-sans-versions} to remove any
+version/backup part. If @var{period} is non-nil, then the returned
+value includes the period that delimits the extension, and if
+@var{filename} has no extension, the value is @code{""}.
+@end defun
+
@node Directory Names
@comment node-name, next, previous, up
@subsection Directory Names
kind of file, and it has a file name, which is related to the directory
name but not identical to it. (This is not quite the same as the usual
Unix terminology.) These two different names for the same entity are
-related by a syntactic transformation. On most systems, this is simple: a
-directory name ends in a slash, whereas the directory's name as a file
-lacks that slash. On VMS, the relationship is more complicated.
+related by a syntactic transformation. On most systems, this is simple:
+a directory name ends in a slash (or backslash), whereas the directory's
+name as a file lacks that slash. On VMS, the relationship is more
+complicated.
The difference between a directory name and its name as a file is
subtle but crucial. When an Emacs variable or function argument is
@defun directory-file-name dirname
This function returns a string representing @var{dirname} in a form that
the operating system will interpret as the name of a file. On most
-systems, this means removing the final slash from the string. On VMS,
-the function converts a string of the form @file{[X.Y]} to
-@file{[X]Y.DIR.1}.
+systems, this means removing the final slash (or backslash) from the
+string. On VMS, the function converts a string of the form @file{[X.Y]}
+to @file{[X]Y.DIR.1}.
@example
@group
(file-relative-name "/foo/bar" "/foo/")
@result{} "bar"
(file-relative-name "/foo/bar" "/hack/")
- @result{} "/foo/bar"
+ @result{} "../foo/bar"
@end example
@end defun
information.
The argument @var{partial-filename} must be a file name containing no
-directory part and no slash. The current buffer's default directory is
-prepended to @var{directory}, if @var{directory} is not absolute.
+directory part and no slash (or backslash on some systems). The current
+buffer's default directory is prepended to @var{directory}, if
+@var{directory} is not absolute.
In the following example, suppose that @file{~rms/lewis} is the current
default directory, and has five files whose names begin with @samp{f}:
The first argument given to @var{handler} is the name of the primitive;
the remaining arguments are the arguments that were passed to that
-operation. (The first of these arguments is typically the file name
+primitive. (The first of these arguments is most often the file name
itself.) For example, if you do this:
@example
(funcall @var{handler} 'file-exists-p @var{filename})
@end example
+When a function takes two or more arguments that must be file names,
+it checks each of those names for a handler. For example, if you do
+this:
+
+@example
+(expand-file-name @var{filename} @var{dirname})
+@end example
+
+@noindent
+then it checks for a handler for @var{filename} and then for a handler
+for @var{dirname}. In either case, the @var{handler} is called like
+this:
+
+@example
+(funcall @var{handler} 'expand-file-name @var{filename} @var{dirname})
+@end example
+
+@noindent
+The @var{handler} then needs to figure out whether to handle
+@var{filename} or @var{dirname}.
+
Here are the operations that a magic file name handler gets to handle:
-@ifinfo
+@ifnottex
@noindent
@code{add-name-to-file}, @code{copy-file}, @code{delete-directory},
@code{delete-file},
@code{vc-registered},
@code{verify-visited-file-modtime},@*
@code{write-region}.
-@end ifinfo
+@end ifnottex
@iftex
@noindent
@flushleft
A flag, @code{t} if the encoding function modifies the buffer, and
@code{nil} if it works by returning a list of annotations.
-@item mode
-A mode function to call after visiting a file converted from this
-format.
+@item mode-fn
+A minor-mode function to call after visiting a file converted from this
+format. The function is called with one argument, the integer 1;
+that tells a minor-mode function to enable the mode.
@end table
The function @code{insert-file-contents} automatically recognizes file