@c -*-texinfo-*-
@c This is part of the GNU Emacs Lisp Reference Manual.
-@c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1998, 1999
-@c Free Software Foundation, Inc.
+@c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1998, 1999, 2004
+@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
@deffn Command find-file filename &optional wildcards
This command selects a buffer visiting the file @var{filename},
-using an existing buffer if there is one, and otherwise creating a
+using an existing buffer if there is one, and otherwise creating a
new buffer and reading the file into it. It also returns that buffer.
-The body of the @code{find-file} function is very simple and looks
-like this:
+Aside from some technical details, the body of the @code{find-file}
+function is basically equivalent to:
@example
-(switch-to-buffer (find-file-noselect filename))
+(switch-to-buffer (find-file-noselect filename nil nil wildcards))
@end example
@noindent
Visiting}). That function sets the buffer major mode, parses local
variables, warns the user if there exists an auto-save file more recent
than the file just visited, and finishes by running the functions in
-@code{find-file-hooks}.
+@code{find-file-hook}.
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-hooks} are not run in case of failure. What's
+@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}).
-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 deffn
@tindex find-file-wildcards
-@defvar 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
-match them. If this is @code{nil}, then wildcard characters are
-not treated specially.
-@end defvar
+match them (when invoked interactively or when their @var{wildcards}
+argument is non-@code{nil}). If this option is @code{nil}, then
+the @code{find-file} commands ignore their @var{wildcards} argument
+and never treat wildcard characters specially.
+@end defopt
-@defvar find-file-hooks
+@defvar find-file-hook
The value of this variable is a list of functions to be called after a
file is visited. The file's local-variables specification (if any) will
have been processed before the hooks are run. The buffer visiting the
file is current when the hook functions are run.
-This variable works just like a normal hook, but we think that renaming
-it would not be advisable. @xref{Hooks}.
+This variable is a normal hook. @xref{Hooks}.
@end defvar
-@defvar find-file-not-found-hooks
+@defvar find-file-not-found-functions
The value of this variable is a list of functions to be called when
@code{find-file} or @code{find-file-noselect} is passed a nonexistent
file name. @code{find-file-noselect} calls these functions as soon as
If @var{nomodes} is non-@code{nil}, that means don't alter the buffer's
major mode, don't process local variables specifications in the file,
-and don't run @code{find-file-hooks}. This feature is used by
+and don't run @code{find-file-hook}. This feature is used by
@code{revert-buffer} in some cases.
The last thing @code{after-find-file} does is call all the functions
-in the list @code{find-file-hooks}.
+in the list @code{find-file-hook}.
@end defun
@node Saving Buffers
With an argument of 16 or 64, reflecting 2 or 3 @kbd{C-u}'s, the
@code{save-buffer} function unconditionally backs up the previous
version of the file before saving it.
+
+@item
+With an argument of 0, unconditionally do @emph{not} make any backup file.
@end itemize
@end deffn
+@anchor{Definition of save-some-buffers}
@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{pred} argument controls which buffers to ask about.
+The optional @var{pred} argument controls which buffers to ask about
+(or to save silently if @var{save-silently-p} is non-@code{nil}).
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
value in a certain buffer, that means do offer to save that buffer.
@end deffn
+@anchor{Definition of write-file}
@deffn Command write-file filename &optional confirm
This function writes the current buffer into file @var{filename}, makes
the buffer visit that file, and marks it not modified. Then it renames
@code{save-buffer}.
If @var{confirm} is non-@code{nil}, that means to ask for confirmation
-before overwriting an existing file.
+before overwriting an existing file. Interactively, confirmation is
+required, unless the user supplies a prefix argument.
+
+If @var{filename} is an existing directory, or a symbolic link to one,
+@code{write-file} uses the name of the visited file, in directory
+@var{filename}. If the buffer is not visiting a file, it uses the
+buffer name instead.
@end deffn
Saving a buffer runs several hooks. It also performs format
conversion (@pxref{Format Conversion}), and may save text properties in
``annotations'' (@pxref{Saving Properties}).
-@defvar write-file-hooks
+@defvar write-file-functions
The value of this variable is a list of functions to be called before
writing out a buffer to its visited file. If one of them returns
non-@code{nil}, the file is considered already written and the rest of
the functions are not called, nor is the usual code for writing the file
executed.
-If a function in @code{write-file-hooks} returns non-@code{nil}, it
+If a function in @code{write-file-functions} returns non-@code{nil}, it
is responsible for making a backup file (if that is appropriate).
To do so, execute the following code:
@end example
You might wish to save the file modes value returned by
-@code{backup-buffer} and use that to set the mode bits of the file that
-you write. This is what @code{save-buffer} normally does.
+@code{backup-buffer} and use that (if non-@code{nil}) to set the mode
+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-hooks} are also responsible for
+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}).
-Do not make this variable buffer-local. To set up buffer-specific hook
-functions, use @code{write-contents-hooks} instead.
+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
+obtained. Thus the variable is marked as a permanent local, so that
+changing the major mode does not alter a buffer-local value. On the
+other hand, calling @code{set-visited-file-name} will reset it.
+If this is not what you want, you might like to use
+@code{write-contents-functions} instead.
Even though this is not a normal hook, you can use @code{add-hook} and
@code{remove-hook} to manipulate the list. @xref{Hooks}.
@end defvar
@c Emacs 19 feature
-@defvar local-write-file-hooks
-This works just like @code{write-file-hooks}, but it is intended to be
-made buffer-local in particular buffers, and used for hooks that pertain
-to the file name or the way the buffer contents were obtained.
-
-The variable is marked as a permanent local, so that changing the major
-mode does not alter a buffer-local value. This is convenient for
-packages that read ``file'' contents in special ways, and set up hooks
-to save the data in a corresponding way.
-@end defvar
-
-@c Emacs 19 feature
-@defvar write-contents-hooks
-This works just like @code{write-file-hooks}, but it is intended for
-hooks that pertain to the contents of the file, as opposed to hooks that
-pertain to where the file came from. Such hooks are usually set up by
-major modes, as buffer-local bindings for this variable.
+@defvar write-contents-functions
+This works just like @code{write-file-functions}, but it is intended for
+hooks that pertain to the contents of the buffer, as opposed to hooks that
+pertain to the file the buffers visits. Such hooks are usually set up by
+major modes, as buffer-local bindings for this variable. If any of the
+functions in this hook returns non-@code{nil}, the file is considered
+already written and the rest are not called and neither are the functions
+in @code{write-file-functions}.
This variable automatically becomes buffer-local whenever it is set;
-switching to a new major mode always resets this variable. When you use
-@code{add-hooks} to add an element to this hook, you should @emph{not}
-specify a non-@code{nil} @var{local} argument, since this variable is
-used @emph{only} buffer-locally.
+switching to a new major mode always resets this variable, but
+calling @code{set-visited-file-name} does not.
@end defvar
+@defopt before-save-hook
+This normal hook runs before a buffer is saved in its visited file,
+regardless of whether that is done normally or by one of the hooks
+described above. For instance, the @file{copyright.el} program uses
+this hook to make sure the file you are saving has the current year in
+its copyright notice.
+@end defopt
+
@c Emacs 19 feature
-@defvar after-save-hook
+@defopt after-save-hook
This normal hook runs after a buffer has been saved in its visited file.
One use of this hook is in Fast Lock mode; it uses this hook to save the
highlighting information in a cache file.
-@end defvar
+@end defopt
-@defvar file-precious-flag
+@defopt file-precious-flag
If this variable is non-@code{nil}, then @code{save-buffer} protects
against I/O errors while saving by writing the new file to a temporary
name instead of the name it is supposed to have, and then renaming it to
Some modes give this variable a non-@code{nil} buffer-local value
in particular buffers.
-@end defvar
+@end defopt
@defopt require-final-newline
This variable determines whether files may be written out that do
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-hooks}, does not perform automatic uncompression, and so
+@code{find-file-hook}, does not perform automatic uncompression, and so
on.
@end defun
An error is signaled if @var{filename} specifies a nonwritable file,
or a nonexistent file in a directory where files cannot be created.
+
+When called from Lisp, this function is completely equivalent to:
+
+@example
+(write-region start end filename t)
+@end example
@end deffn
@deffn Command write-region start end filename &optional append visit lockname mustbenew
This function writes the region delimited by @var{start} and @var{end}
in the current buffer into the file specified by @var{filename}.
+If @var{start} is @code{nil}, then the command writes the entire buffer
+contents (@emph{not} just the accessible portion) to the file and
+ignores @var{end}.
+
@c Emacs 19 feature
If @var{start} is a string, then @code{write-region} writes or appends
that string, rather than text from the buffer. @var{end} is ignored in
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.
-Starting in Emacs 21, if @var{mustbenew} is the symbol @code{excl},
+Starting in Emacs 21, if @var{mustbenew} is the symbol @code{excl},
then @code{write-region} does not ask for confirmation, but instead
it signals an error @code{file-already-exists} if the file already
exists.
files that the user does not need to know about.
@end deffn
+@anchor{Definition of with-temp-file}
@defmac with-temp-file file body...
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
The current buffer is restored even in case of an abnormal exit via
@code{throw} or error (@pxref{Nonlocal Exits}).
-See also @code{with-temp-buffer} in @ref{Current Buffer}.
+See also @code{with-temp-buffer} in @ref{Definition of
+with-temp-buffer,, The Current Buffer}.
@end defmac
@node File Locks
@cindex accessibility of a file
@cindex file accessibility
- These functions test for permission to access a file in specific ways.
+ These functions test for permission to access a file in specific
+ways. Unless explicitly stated otherwise, they recursively follow
+symbolic links for their file name arguments, at all levels (at the
+level of the file itself and at all levels of parent directories).
@defun file-exists-p filename
-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 itself.)
+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
+itself.)
If the file does not exist, or if fascist access control policies
prevent you from finding the attributes of the file, this function
returns @code{nil}.
+
+Directories are files, so @code{file-exists-p} returns @code{t} when
+given a directory name. However, symbolic links are treated
+specially; @code{file-exists-p} returns @code{t} for a symbolic link
+name only if the target file exists.
@end defun
@defun file-readable-p filename
@defun file-ownership-preserved-p filename
This function returns @code{t} if deleting the file @var{filename} and
-then creating it anew would keep the file's owner unchanged.
+then creating it anew would keep the file's owner unchanged. It also
+returns @code{t} for nonexistent files.
+
+If @var{filename} is a symbolic link, then, unlike the other functions
+discussed here, @code{file-ownership-preserved-p} does @emph{not}
+replace @var{filename} with its target. However, it does recursively
+follow symbolic links at all levels of parent directories.
@end defun
@defun file-newer-than-file-p filename1 filename2
@cindex file modification time
This function returns @code{t} if the file @var{filename1} is
newer than file @var{filename2}. If @var{filename1} does not
-exist, it returns @code{nil}. If @var{filename2} does not exist,
-it returns @code{t}.
+exist, it returns @code{nil}. If @var{filename1} does exist, but
+@var{filename2} does not, it returns @code{t}.
In the following example, assume that the file @file{aug-19} was written
on the 19th, @file{aug-20} was written on the 20th, and the file
@defun file-symlink-p filename
@cindex file symbolic links
-If the file @var{filename} is a symbolic link, the @code{file-symlink-p}
-function returns the file name to which it is linked. This may be the
-name of a text file, a directory, or even another symbolic link, or it
-may be a nonexistent file name.
+If the file @var{filename} is a symbolic link, the
+@code{file-symlink-p} function returns the (non-recursive) link target
+as a string. (Determining the file name that the link points to from
+the target is nontrivial.) First, this function recursively follows
+symbolic links at all levels of parent directories.
If the file @var{filename} is not a symbolic link (or there is no such file),
-@code{file-symlink-p} returns @code{nil}.
+@code{file-symlink-p} returns @code{nil}.
@example
@group
@c !!! file-symlink-p: should show output of ls -l for comparison
@end defun
+The next two functions recursively follow symbolic links at
+all levels for @var{filename}.
+
@defun file-directory-p filename
This function returns @code{t} if @var{filename} is the name of an
existing directory, @code{nil} otherwise.
@defun file-truename filename
The function @code{file-truename} returns the truename of the file
@var{filename}. The argument must be an absolute file name.
+
+This function does not expand environment variables. Only
+@code{substitute-in-file-name} does that. @xref{Definition of
+substitute-in-file-name}.
+
+If you may need to follow symbolic links preceding @samp{..}@:
+appearing as a name component, you should make sure to call
+@code{file-truename} without prior direct or indirect calls to
+@code{expand-file-name}, as otherwise the file name component
+immediately preceding @samp{..} will be ``simplified away'' before
+@code{file-truename} is called. To eliminate the need for a call to
+@code{expand-file-name}, @code{file-truename} handles @samp{~} in the
+same way that @code{expand-file-name} does. @xref{File Name
+Expansion,, Functions that Expand Filenames}.
@end defun
-@defun file-chase-links filename
+@defun file-chase-links filename &optional limit
This function follows symbolic links, starting with @var{filename},
until it finds a file name which is not the name of a symbolic link.
-Then it returns that file name.
+Then it returns that file name. This function does @emph{not} follow
+symbolic links at the level of parent directories.
+
+If you specify a number for @var{limit}, then after chasing through
+that many links, the function just returns what it has even if that is
+still a symbolic link.
@end defun
To illustrate the difference between @code{file-chase-links} and
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 @sc{suid} bit
+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.
+
@example
@group
(file-modes "~/junk/diffs")
@end example
@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.
+
@defun file-nlinks filename
This functions returns the number of names (i.e., hard links) that
file @var{filename} has. If the file does not exist, then this function
@end example
@end defun
-@defun file-attributes filename
+@anchor{Definition of file-attributes}
+@defun file-attributes filename &optional id-format
This function returns a list of attributes of file @var{filename}. If
the specified file cannot be opened, it returns @code{nil}.
+The optional parameter @var{id-format} specifies the preferred format
+of attributes @acronym{UID} and @acronym{GID} (see below)---the
+valid values are @code{'string} and @code{'integer}. The latter is
+the default, but we plan to change that, so you should specify a
+non-@code{nil} value for @var{id-format} if you use the returned
+@acronym{UID} or @acronym{GID}.
The elements of the list, in order, are:
(@pxref{Changing Files}).
@item
-The file's @sc{uid}.
+The file's @acronym{UID} as a string or an integer. If a string
+value cannot be looked up, the integer value is returned.
@item
-The file's @sc{gid}.
+The file's @acronym{GID} likewise.
@item
The time of last access, as a list of two integers.
as in @samp{ls -l}.
@item
-@code{t} if the file's @sc{gid} would change if file were
+@code{t} if the file's @acronym{GID} would change if file were
deleted and recreated; @code{nil} otherwise.
@item
holds the low 16 bits.
@item
-The file system number of the file system that the file is in. This
-element and the file's inode number together give enough information to
+The file system number of the file system that the file is in.
+Depending on the magnitude of the value, this can be either an integer
+or a cons cell, in the same manner as the inode number. This element
+and the file's inode number together give enough information to
distinguish any two files on the system---no two files can have the same
values for both of these numbers.
@end enumerate
@example
@group
-(file-attributes "files.texi")
- @result{} (nil 1 2235 75
- (8489 20284)
- (8489 20284)
+(file-attributes "files.texi" 'string)
+ @result{} (nil 1 "lh" "users"
+ (8489 20284)
+ (8489 20284)
(8489 20285)
- 14906 "-rw-rw-rw-"
+ 14906 "-rw-rw-rw-"
nil 129500 -32252)
@end group
@end example
has only one name (the name @file{files.texi} in the current default
directory).
-@item 2235
-is owned by the user with @sc{uid} 2235.
+@item "lh"
+is owned by the user with name "lh".
-@item 75
-is in the group with @sc{gid} 75.
+@item "users"
+is in the group with name "users".
@item (8489 20284)
was last accessed on Aug 19 00:09.
has a mode of read and write access for the owner, group, and world.
@item nil
-would retain the same @sc{gid} if it were recreated.
+would retain the same @acronym{GID} if it were recreated.
@item 129500
has an inode number of 129500.
is any other value.
@end itemize
-@defun add-name-to-file oldname newname &optional ok-if-already-exists
+The next four commands all recursively follow symbolic links at all
+levels of parent directories for their first argument, but, if that
+argument is itself a symbolic link, then only @code{copy-file}
+replaces it with its (recursive) target.
+
+@deffn Command add-name-to-file oldname newname &optional ok-if-already-exists
@cindex file with multiple names
@cindex file hard link
This function gives the file named @var{oldname} the additional name
by copying the file instead.
See also @code{file-nlinks} in @ref{File Attributes}.
-@end defun
+@end deffn
@deffn Command rename-file filename newname &optional ok-if-already-exists
This command renames the file @var{filename} as @var{newname}.
continues to have those names. In fact, adding the name @var{newname}
with @code{add-name-to-file} and then deleting @var{filename} has the
same effect as renaming, aside from momentary intermediate states.
-
-In an interactive call, this function prompts for @var{filename} and
-@var{newname} in the minibuffer; also, it requests confirmation if
-@var{newname} already exists.
@end deffn
@deffn Command copy-file oldname newname &optional ok-if-exists time
This command copies the file @var{oldname} to @var{newname}. An
-error is signaled if @var{oldname} does not exist.
+error is signaled if @var{oldname} does not exist. If @var{newname}
+names a directory, it copies @var{oldname} into that directory,
+preserving its final name component.
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.
-In an interactive call, this function prompts for @var{filename} and
-@var{newname} in the minibuffer; also, it requests confirmation if
-@var{newname} already exists.
+This function copies the file modes, too.
+
+In an interactive call, a prefix argument specifies a non-@code{nil}
+value for @var{time}.
+@end deffn
+
+@deffn Command make-symbolic-link filename newname &optional ok-if-exists
+@pindex ln
+@kindex file-already-exists
+This command makes a symbolic link to @var{filename}, named
+@var{newname}. This is like the shell command @samp{ln -s
+@var{filename} @var{newname}}.
+
+This function is not available on systems that don't support symbolic
+links.
@end deffn
@deffn Command delete-file filename
not exist, or is not deletable. (On Unix and GNU/Linux, a file is
deletable if its directory is writable.)
-See also @code{delete-directory} in @ref{Create/Delete Dirs}.
-@end deffn
-
-@deffn Command make-symbolic-link filename newname &optional ok-if-exists
-@pindex ln
-@kindex file-already-exists
-This command makes a symbolic link to @var{filename}, named
-@var{newname}. This is like the shell command @samp{ln -s
-@var{filename} @var{newname}}.
-
-In an interactive call, this function prompts for @var{filename} and
-@var{newname} in the minibuffer; also, it requests confirmation if
-@var{newname} already exists.
+If @var{filename} is a symbolic link, @code{delete-file} does not
+replace it with its target, but it does follow symbolic links at all
+levels of parent directories.
-This function is not available on systems that don't support symbolic
-links.
+See also @code{delete-directory} in @ref{Create/Delete Dirs}.
@end deffn
@defun define-logical-name varname string
-This function defines the logical name @var{name} to have the value
+This function defines the logical name @var{varname} to have the value
@var{string}. It is available only on VMS.
@end defun
@defun set-file-modes filename mode
-This function sets mode bits of @var{filename} to @var{mode} (which must
-be an integer). Only the low 12 bits of @var{mode} are used.
+This function sets mode bits of @var{filename} to @var{mode} (which
+must be an integer). Only the low 12 bits of @var{mode} are used.
+This function recursively follows symbolic links at all levels for
+@var{filename}.
@end defun
@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
This function returns the current default protection value.
@end defun
+@defun set-file-times filename &optional time
+This function sets the access and modification times of @var{filename}
+to @var{time}. The return value is @code{t} if the times are successfully
+set, otherwise it is @code{nil}. @var{time} defaults to the current
+time and must be in the format returned by @code{current-time}
+(@pxref{Time of Day}).
+@end defun
+
@cindex MS-DOS and file modes
@cindex file modes and MS-DOS
On MS-DOS, there is no such thing as an ``executable'' file mode bit.
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.
+* Relative File Names:: Some file names are relative to a current directory.
* Directory Names:: A directory's name as a directory
is different from its name as a file.
-* Relative File Names:: Some file names are relative to a current directory.
* File Name Expansion:: Converting relative file names to absolute ones.
* Unique File Names:: Generating names for temporary files.
* File Name Completion:: Finding the completions for a given file name.
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
found mostly in directory lists.
@defun file-name-directory filename
-This function returns the directory part of @var{filename} (or
-@code{nil} if @var{filename} does not include a directory part). On
-most systems, the function returns a string ending in a slash. On VMS,
-it returns a string ending in one of the three characters @samp{:},
+This function returns the directory part of @var{filename}, as a
+directory name (@pxref{Directory Names}), or @code{nil} if
+@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
+returns a string ending in one of the three characters @samp{:},
@samp{]}, or @samp{>}.
@example
@result{} "foo"
@end group
@group
+(file-name-nondirectory "lewis/")
+ @result{} ""
+@end group
+@group
;; @r{The following example is accurate only on VMS.}
(file-name-nondirectory "[X]FOO.TMP")
@result{} "FOO.TMP"
@end example
@end defun
+@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. The extension, in a file name, is the part that
+starts with the last @samp{.} in the last name component (minus
+any version/backup part).
+
+This function returns @code{nil} for extensionless file names such as
+@file{foo}. It returns @code{""} for null extensions, as in
+@file{foo.}. If the last component of a file name begins with a
+@samp{.}, that @samp{.} doesn't count as the beginning of an
+extension. Thus, @file{.emacs}'s ``extension'' is @code{nil}, not
+@samp{.emacs}.
+
+If @var{period} is non-@code{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
+
@defun file-name-sans-extension filename
-This function returns @var{filename} minus its ``extension,'' if any.
-The extension, in a file name, is the part that starts with the last
-@samp{.} in the last name component. For example,
+This function returns @var{filename} minus its extension, if any. The
+version/backup part, if present, is only removed if the file has an
+extension. For example,
@example
(file-name-sans-extension "foo.lose.c")
@result{} "foo.lose"
(file-name-sans-extension "big.hack/foo")
@result{} "big.hack/foo"
+(file-name-sans-extension "/my/home/.emacs")
+ @result{} "/my/home/.emacs"
+(file-name-sans-extension "/my/home/.emacs.el")
+ @result{} "/my/home/.emacs"
+(file-name-sans-extension "~/foo.el.~3~")
+ @result{} "~/foo"
+(file-name-sans-extension "~/foo.~3~")
+ @result{} "~/foo.~3~"
+@end example
+
+Note that the @samp{.~3~} in the two last examples is the backup part,
+not an extension.
+@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
+
+@node Relative File Names
+@subsection Absolute and Relative File Names
+@cindex absolute file name
+@cindex relative file name
+
+ All the directories in the file system form a tree starting at the
+root directory. A file name can specify all the directory names
+starting from the root of the tree; then it is called an @dfn{absolute}
+file name. Or it can specify the position of the file in the tree
+relative to a default directory; then it is called a @dfn{relative} file
+name. On Unix and GNU/Linux, an absolute file name starts with a slash
+or a tilde (@samp{~}), and a relative one does not. On MS-DOS and
+MS-Windows, an absolute file name starts with a slash or a backslash, or
+with a drive specification @samp{@var{x}:/}, where @var{x} is the
+@dfn{drive letter}. The rules on VMS are complicated.
+
+@defun file-name-absolute-p filename
+This function returns @code{t} if file @var{filename} is an absolute
+file name, @code{nil} otherwise. On VMS, this function understands both
+Unix syntax and VMS syntax.
+
+@example
+@group
+(file-name-absolute-p "~rms/foo")
+ @result{} t
+@end group
+@group
+(file-name-absolute-p "rms/foo")
+ @result{} nil
+@end group
+@group
+(file-name-absolute-p "/user/rms/foo")
+ @result{} t
+@end group
@end example
@end defun
@cindex directory name
@cindex file name of directory
- A @dfn{directory name} is the name of a directory. A directory is a
-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.
+ A @dfn{directory name} is the name of a directory. A directory is
+actually a kind of file, so 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 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
+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
described as being a directory name, a file name of a directory is not
-acceptable.
+acceptable. When @code{file-name-directory} returns a string, that is
+always a directory name.
The following two functions convert between directory names and file
names. They do nothing special with environment variable substitutions
-such as @samp{$HOME}, and the constructs @samp{~}, and @samp{..}.
+such as @samp{$HOME}, and the constructs @samp{~}, @samp{.} and @samp{..}.
@defun file-name-as-directory filename
This function returns a string representing @var{filename} in a form
@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
@end example
@end defun
+ Given a directory name, you can combine it with a relative file name
+using @code{concat}:
+
+@example
+(concat @var{dirname} @var{relfile})
+@end example
+
+@noindent
+Be sure to verify that the file name is relative before doing that.
+If you use an absolute file name, the results could be syntactically
+invalid or refer to the wrong file.
+
+ If you want to use a directory file name in making such a
+combination, you must first convert it to a directory name using
+@code{file-name-as-directory}:
+
+@example
+(concat (file-name-as-directory @var{dirfile}) @var{relfile})
+@end example
+
+@noindent
+Don't try concatenating a slash by hand, as in
+
+@example
+;;; @r{Wrong!}
+(concat @var{dirfile} "/" @var{relfile})
+@end example
+
+@noindent
+because this is not portable. Always use
+@code{file-name-as-directory}.
+
@cindex directory name abbreviation
Directory name abbreviations are useful for directories that are
normally accessed through symbolic links. Sometimes the users recognize
@code{(@var{from} . @var{to})}, and says to replace @var{from} with
@var{to} when it appears in a directory name. The @var{from} string is
actually a regular expression; it should always start with @samp{^}.
-The function @code{abbreviate-file-name} performs these substitutions.
+The @var{to} string should be an ordinary absolute directory name. Do
+not use @samp{~} to stand for a home directory in that string. The
+function @code{abbreviate-file-name} performs these substitutions.
You can set this variable in @file{site-init.el} to describe the
abbreviations appropriate for your site.
To convert a directory name to its abbreviation, use this
function:
-@defun abbreviate-file-name dirname
+@anchor{Definition of abbreviate-file-name}
+@defun abbreviate-file-name filename
This function applies abbreviations from @code{directory-abbrev-alist}
to its argument, and substitutes @samp{~} for the user's home
-directory.
-@end defun
-
-@node Relative File Names
-@subsection Absolute and Relative File Names
-@cindex absolute file name
-@cindex relative file name
-
- All the directories in the file system form a tree starting at the
-root directory. A file name can specify all the directory names
-starting from the root of the tree; then it is called an @dfn{absolute}
-file name. Or it can specify the position of the file in the tree
-relative to a default directory; then it is called a @dfn{relative} file
-name. On Unix and GNU/Linux, an absolute file name starts with a slash
-or a tilde (@samp{~}), and a relative one does not. On MS-DOS and
-MS-Windows, an absolute file name starts with a slash or a backslash, or
-with a drive specification @samp{@var{x}:/}, where @var{x} is the
-@dfn{drive letter}. The rules on VMS are complicated.
-
-@defun file-name-absolute-p filename
-This function returns @code{t} if file @var{filename} is an absolute
-file name, @code{nil} otherwise. On VMS, this function understands both
-Unix syntax and VMS syntax.
-
-@example
-@group
-(file-name-absolute-p "~rms/foo")
- @result{} t
-@end group
-@group
-(file-name-absolute-p "rms/foo")
- @result{} nil
-@end group
-@group
-(file-name-absolute-p "/user/rms/foo")
- @result{} t
-@end group
-@end example
+directory. You can use it for directory names and for file names,
+because it recognizes abbreviations even as part of the name.
@end defun
@node File Name Expansion
be expanded. Expansion also simplifies file names by eliminating
redundancies such as @file{./} and @file{@var{name}/../}.
+In the next two functions, the @var{directory} argument can be either
+a directory name or a directory file name. @xref{Directory Names}.
+
@defun expand-file-name filename &optional directory
This function converts @var{filename} to an absolute file name. If
@var{directory} is supplied, it is the default directory to start with
@end group
@end example
+If the part of the combined file name before the first slash is
+@samp{~}, it expands to the value of the @env{HOME} environment
+variable (usually your home directory). If the part before the first
+slash is @samp{~@var{user}} and if @var{user} is a valid login name,
+it expands to @var{user}'s home directory.
+
Filenames containing @samp{.} or @samp{..} are simplified to their
canonical form:
Note that @code{expand-file-name} does @emph{not} expand environment
variables; only @code{substitute-in-file-name} does that.
+
+Note also that @code{expand-file-name} does not follow symbolic links
+at any level. This results in a difference between the way
+@code{file-truename} and @code{expand-file-name} treat @samp{..}.
+Assuming that @samp{/tmp/bar} is a symbolic link to the directory
+@samp{/tmp/foo/bar} we get:
+
+@example
+@group
+(file-truename "/tmp/bar/../myfile")
+ @result{} "/tmp/foo/myfile"
+@end group
+@group
+(expand-file-name "/tmp/bar/../myfile")
+ @result{} "/tmp/myfile"
+@end group
+@end example
+
+If you may need to follow symbolic links preceding @samp{..}, you
+should make sure to call @code{file-truename} without prior direct or
+indirect calls to @code{expand-file-name}. @xref{Truenames}.
@end defun
@c Emacs 19 feature
(file-relative-name "/foo/bar" "/foo/")
@result{} "bar"
(file-relative-name "/foo/bar" "/hack/")
- @result{} "/foo/bar"
+ @result{} "../foo/bar"
@end example
@end defun
@end example
@end defvar
+@anchor{Definition of substitute-in-file-name}
@defun substitute-in-file-name filename
-This function replaces environment variables references in
-@var{filename} with the environment variable values. Following standard
-Unix shell syntax, @samp{$} is the prefix to substitute an environment
-variable value.
+This function replaces environment variable references in
+@var{filename} with the environment variable values. Following
+standard Unix shell syntax, @samp{$} is the prefix to substitute an
+environment variable value. If the input contains @samp{$$}, that is
+converted to @samp{$}; this gives the user a way to ``quote'' a
+@samp{$}.
The environment variable name is the series of alphanumeric characters
(including underscores) that follow the @samp{$}. If the character following
the @samp{$} is a @samp{@{}, then the variable name is everything up to the
matching @samp{@}}.
+Calling @code{substitute-in-file-name} on output produced by
+@code{substitute-in-file-name} tends to give incorrect results. For
+instance, use of @samp{$$} to quote a single @samp{$} won't work
+properly, and @samp{$} in an environment variable's value could lead
+to repeated substitution. Therefore, programs that call this function
+and put the output where it will be passed to this function need to
+double all @samp{$} characters to prevent subsequent incorrect
+results.
+
@c Wordy to avoid overfull hbox. --rjc 15mar92
Here we assume that the environment variable @code{HOME}, which holds
the user's home directory name, has value @samp{/xcssun/users/rms}.
@end group
@end example
-After substitution, if a @samp{~} or a @samp{/} appears following a
-@samp{/}, everything before the following @samp{/} is discarded:
+After substitution, if a @samp{~} or a @samp{/} appears immediately
+after another @samp{/}, the function discards everything before it (up
+through the immediately preceding @samp{/}).
@example
@group
The job of @code{make-temp-file} is to prevent two different users or
two different jobs from trying to use the exact same file name.
-@defun make-temp-file prefix &optional dir-flag
+@defun make-temp-file prefix &optional dir-flag suffix
@tindex make-temp-file
This function creates a temporary file and returns its name.
The name starts with @var{prefix}; it also contains a number that is
empty. At that point, you should write the intended contents into the
file.
-If @var{dir-flag} is non-@code{nil}, @code{make-temp-file} creates
-an empty directory instead of an empty file.
+If @var{dir-flag} is non-@code{nil}, @code{make-temp-file} creates an
+empty directory instead of an empty file. It returns the file name,
+not the directory name, of that directory. @xref{Directory Names}.
+
+If @var{suffix} is non-@code{nil}, @code{make-temp-file} adds it at
+the end of the file name.
To prevent conflicts among different libraries running in the same
Emacs, each Lisp program that uses @code{make-temp-file} should have its
This function generates a string that can be used as a unique file name.
The name starts with @var{string}, and contains a number that is
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. On MS-DOS,
-the @var{string} prefix can be truncated to fit into the 8+3 file-name
-limits.
+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
@defvar temporary-file-directory
environment variables, with a fall-back to a system-dependent name if
none of these variables is defined.
-Even if you do not use @code{make-temp-name} to choose the temporary
-file's name, you should still use this variable to decide which
-directory to put the file in. However, if you expect the file to be
-small, you should use @code{small-temporary-file-directory} first if
-that is non-@code{nil}.
+Even if you do not use @code{make-temp-file} to create the temporary
+file, you should still use this variable to decide which directory to
+put the file in. However, if you expect the file to be small, you
+should use @code{small-temporary-file-directory} first if that is
+non-@code{nil}.
@end defvar
@tindex small-temporary-file-directory
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}:
@example
@group
(file-name-all-completions "f" "")
- @result{} ("foo" "file~" "file.c.~2~"
+ @result{} ("foo" "file~" "file.c.~2~"
"file.c.~1~" "file.c")
@end group
@group
-(file-name-all-completions "fo" "")
+(file-name-all-completions "fo" "")
@result{} ("foo")
@end group
@end example
@defopt completion-ignored-extensions
@code{file-name-completion} usually ignores file names that end in any
string in this list. It does not ignore them when all the possible
-completions end in one of these suffixes or when a buffer showing all
-possible completions is displayed.@refill
+completions end in one of these suffixes. This variable has no effect
+on @code{file-name-all-completions}.@refill
A typical value might look like this:
@result{} (".o" ".elc" "~" ".dvi")
@end group
@end example
+
+If an element of @code{completion-ignored-extensions} ends in a slash
+@samp{/}, it signals a directory. The elements which do @emph{not} end
+in a slash will never match a directory; thus, the above value will not
+filter out a directory named @file{foo.elc}.
@end defopt
@node Standard File Names
@group
(directory-files "~lewis")
@result{} ("#foo#" "#foo.el#" "." ".."
- "dired-mods.el" "files.texi"
+ "dired-mods.el" "files.texi"
"files.texi.~1~")
@end group
@end example
that can be read.
@end defun
+@defun directory-files-and-attributes directory &optional full-name match-regexp nosort id-format
+This is similar to @code{directory-files} in deciding which files
+to report on and how to report their names. However, instead
+of returning a list of file names, it returns for each file a
+list @code{(@var{filename} . @var{attributes})}, where @var{attributes}
+is what @code{file-attributes} would return for that file.
+The optional argument @var{id-format} has the same meaning as the
+corresponding argument to @code{file-attributes} (@pxref{Definition
+of file-attributes}).
+@end defun
+
@defun file-name-all-versions file dirname
This function returns a list of all versions of the file named
-@var{file} in directory @var{dirname}.
+@var{file} in directory @var{dirname}. It is only available on VMS.
@end defun
@tindex file-expand-wildcards
This function inserts (in the current buffer) a directory listing for
directory @var{file}, formatted with @code{ls} according to
@var{switches}. It leaves point after the inserted text.
+@var{switches} may be a string of options, or a list of strings
+representing individual options.
The argument @var{file} may be either a directory name or a file
specification including wildcard characters. If @var{wildcard} is
MS-DOS and MS-Windows systems usually lack the standard Unix program
@code{ls}, so this function emulates the standard Unix program @code{ls}
with Lisp code.
+
+As a technical detail, when @var{switches} contains the long
+@samp{--dired} option, @code{insert-directory} treats it specially,
+for the sake of dired. However, the normally equivalent short
+@samp{-D} option is just passed on to @code{insert-directory-program},
+as any other option.
@end defun
@defvar insert-directory-program
@defun make-directory dirname &optional parents
This function creates a directory named @var{dirname}.
-If @var{parents} is non-@code{nil}, that means to create
-the parent directories first, if they don't already exist.
+If @var{parents} is non-@code{nil}, as is always the case in an
+interactive call, that means to create the parent directories first,
+if they don't already exist.
@end defun
@defun delete-directory dirname
@code{delete-file} does not work for files that are directories; you
must use @code{delete-directory} for them. If the directory contains
any files, @code{delete-directory} signals an error.
+
+This function only follows symbolic links at the level of parent
+directories.
@end defun
@node Magic File Names
the file name matches @var{regexp}, the primitives handle that file by
calling @var{handler}.
-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
-itself.) For example, if you do this:
+The first argument given to @var{handler} is the name of the
+primitive, as a symbol; the remaining arguments are the arguments that
+were passed to that primitive. (The first of these arguments is most
+often the file name itself.) For example, if you do this:
@example
(file-exists-p @var{filename})
(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}.
+
+If the specified file name matches more than one handler, the one
+whose match starts last in the file name gets precedence. This rule
+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:
@ifnottex
@noindent
-@code{add-name-to-file}, @code{copy-file}, @code{delete-directory},
+@code{access-file}, @code{add-name-to-file},
+@code{byte-compiler-base-file-name},@*
+@code{copy-file}, @code{delete-directory},
@code{delete-file},
@code{diff-latest-backup-file},
@code{directory-file-name},
@code{directory-files},
+@code{directory-files-and-attributes},
@code{dired-call-process},
-@code{dired-compress-file}, @code{dired-uncache},
+@code{dired-compress-file}, @code{dired-uncache},@*
@code{expand-file-name},
-@code{file-accessible-directory-p},@*
+@code{file-accessible-directory-p},
@code{file-attributes},
@code{file-directory-p},
-@code{file-executable-p}, @code{file-exists-p},@*
-@code{file-local-copy},
-@code{file-modes}, @code{file-name-all-completions},@*
+@code{file-executable-p}, @code{file-exists-p},
+@code{file-local-copy}, @code{file-remote-p},
+@code{file-modes}, @code{file-name-all-completions},
@code{file-name-as-directory},
@code{file-name-completion},
@code{file-name-directory},
@code{file-readable-p}, @code{file-regular-p}, @code{file-symlink-p},
@code{file-truename}, @code{file-writable-p},
@code{find-backup-file-name},
-@code{get-file-buffer},@*
+@code{find-file-noselect},@*
+@code{get-file-buffer},
@code{insert-directory},
-@code{insert-file-contents},
+@code{insert-file-contents},@*
@code{load}, @code{make-directory},
-@code{make-symbolic-link}, @code{rename-file}, @code{set-file-modes},
-@code{set-visited-file-modtime}, @code{shell-command},@*
+@code{make-directory-internal},
+@code{make-symbolic-link},@*
+@code{rename-file}, @code{set-file-modes}, @code{set-file-times},
+@code{set-visited-file-modtime}, @code{shell-command},
+@code{substitute-in-file-name},@*
@code{unhandled-file-name-directory},
@code{vc-registered},
@code{verify-visited-file-modtime},@*
@iftex
@noindent
@flushleft
-@code{add-name-to-file}, @code{copy-file}, @code{delete-directory},
+@code{access-file}, @code{add-name-to-file},
+@code{byte-com@discretionary{}{}{}piler-base-file-name},
+@code{copy-file}, @code{delete-directory},
@code{delete-file},
@code{diff-latest-backup-file},
@code{directory-file-name},
@code{directory-files},
+@code{directory-files-and-at@discretionary{}{}{}tributes},
@code{dired-call-process},
@code{dired-compress-file}, @code{dired-uncache},
@code{expand-file-name},
@code{file-attributes},
@code{file-direct@discretionary{}{}{}ory-p},
@code{file-executable-p}, @code{file-exists-p},
-@code{file-local-copy},
+@code{file-local-copy}, @code{file-remote-p},
@code{file-modes}, @code{file-name-all-completions},
@code{file-name-as-directory},
@code{file-name-completion},
@code{file-readable-p}, @code{file-regular-p}, @code{file-symlink-p},
@code{file-truename}, @code{file-writable-p},
@code{find-backup-file-name},
+@code{find-file-noselect},
@code{get-file-buffer},
@code{insert-directory},
@code{insert-file-contents},
@code{load}, @code{make-direc@discretionary{}{}{}tory},
-@code{make-symbolic-link}, @code{rename-file}, @code{set-file-modes},
+@code{make-direc@discretionary{}{}{}tory-internal},
+@code{make-symbolic-link},
+@code{rename-file}, @code{set-file-modes},
@code{set-visited-file-modtime}, @code{shell-command},
+@code{substitute-in-file-name},
@code{unhandled-file-name-directory},
@code{vc-regis@discretionary{}{}{}tered},
@code{verify-visited-file-modtime},
@dots{}
;; @r{Handle any operation we don't know about.}
(t (let ((inhibit-file-name-handlers
- (cons 'my-file-handler
+ (cons 'my-file-handler
(and (eq inhibit-file-name-operation operation)
inhibit-file-name-handlers)))
(inhibit-file-name-operation operation))
multiple handlers, and for operations that have two file names that may
each have handlers.
+@kindex safe-magic (@r{property})
+Handlers that don't really do anything special for actual access to the
+file---such as the ones that implement completion of host names for
+remote file names---should have a non-@code{nil} @code{safe-magic}
+property. For instance, Emacs normally ``protects'' directory names
+it finds in @code{PATH} from becoming magic, if they look like magic
+file names, by prefixing them with @samp{/:}. But if the handler that
+would be used for them has a non-@code{nil} @code{safe-magic}
+property, the @samp{/:} is not added.
+
@defvar inhibit-file-name-handlers
This variable holds a list of handlers whose use is presently inhibited
for a certain operation.
@end defun
@defun file-local-copy filename
-This function copies file @var{filename} to an ordinary non-magic file,
-if it isn't one already.
-
-If @var{filename} specifies a magic file name, which programs
-outside Emacs cannot directly read or write, this copies the contents to
-an ordinary file and returns that file's name.
+This function copies file @var{filename} to an ordinary non-magic file
+on the local machine, if it isn't on the local machine already. Magic
+file names should handle the @code{file-local-copy} operation if they
+refer to files on other machines. A magic file name that is used for
+other purposes than remote file access should not handle
+@code{file-local-copy}; then this function will treat the file as
+local.
+
+If @var{filename} is local, whether magic or not, this function does
+nothing and returns @code{nil}. Otherwise it returns the file name
+of the local copy file.
+@end defun
-If @var{filename} is an ordinary file name, not magic, then this function
-does nothing and returns @code{nil}.
+@defun file-remote-p filename
+This function returns @code{t} if @var{filename} is a remote file.
@end defun
@defun unhandled-file-name-directory filename
encoding functions for the formats listed in @code{buffer-file-format},
in the order of appearance in the list.
-@deffn Command format-write-file file format
-This command writes the current buffer contents into the file @var{file}
-in format @var{format}, and makes that format the default for future
-saves of the buffer. The argument @var{format} is a list of format
-names.
+@deffn Command format-write-file file format &optional confirm
+This command writes the current buffer contents into the file
+@var{file} in format @var{format}, and makes that format the default
+for future saves of the buffer. The argument @var{format} is a list
+of format names. Except for the @var{format} argument, this command
+is similar to @code{write-file}. In particular, @var{confirm} has the
+same meaning and interactive treatment as the corresponding argument
+to @code{write-file}. @xref{Definition of write-file}.
@end deffn
@deffn Command format-find-file file format
This variable specifies the format to use for auto-saving. Its value is
a list of format names, just like the value of
@code{buffer-file-format}; however, it is used instead of
-@code{buffer-file-format} for writing auto-save files. This variable is
-always buffer-local in all buffers.
+@code{buffer-file-format} for writing auto-save files. If the value
+is @code{t}, the default, auto-saving uses the same format as a
+regular save in the same buffer. This variable is always buffer-local
+in all buffers.
@end defvar
+
+@ignore
+ arch-tag: 141f74ce-6ae3-40dc-a6c4-ef83fc4ec35c
+@end ignore
HCoop / bpt / emacs.git / blobdiff