@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
@samp{../}). These functions don't recognize environment variable
substitutions such as @samp{$HOME}. @xref{File Name Expansion}.
+ When file I/O functions signal Lisp errors, they usually use the
+condition @code{file-error} (@pxref{Handling Errors}). The error
+message is in most cases obtained from the operating system, according
+to locale @code{system-message-locale}, and decoded using coding system
+@code{locale-coding-system} (@pxref{Locales}).
+
@menu
* Visiting Files:: Reading files into Emacs buffers for editing.
* Saving Buffers:: Writing changed buffers back into files.
@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
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
not treated specially.
@end defvar
-@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
it would not be advisable. @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
It uses @code{generate-new-buffer} (@pxref{Creating Buffers}).
@end defun
-@defun after-find-file &optional error warn
+@defun after-find-file &optional error warn noauto after-find-file-from-revert-buffer nomodes
This function sets the buffer major mode, and parses local variables
(@pxref{Auto Major Mode}). It is called by @code{find-file-noselect}
and by the default revert function (@pxref{Reverting}).
If @var{warn} is non-@code{nil}, then this function issues a warning
if an auto-save file exists and is more recent than the visited file.
+If @var{noauto} is non-@code{nil}, that says not to enable or disable
+Auto-Save mode. The mode remains enabled if it was enabled before.
+
+If @var{after-find-file-from-revert-buffer} is non-@code{nil}, that
+means this call was from @code{revert-buffer}. This has no direct
+effect, but some mode functions and hook functions check the value
+of this variable.
+
+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-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
@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
+@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
the buffer based on @var{filename}, appending a string like @samp{<2>}
if necessary to make a unique buffer name. It does most of this work by
calling @code{set-visited-file-name} (@pxref{Buffer File Name}) and
@code{save-buffer}.
+
+If @var{confirm} is non-@code{nil}, that means to ask for confirmation
+before overwriting an existing file.
@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:
@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.
-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
+@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 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.
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.
@end defvar
@c Emacs 19 feature
@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
-@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
or a nonexistent file in a directory where files cannot be created.
@end deffn
-@deffn Command write-region start end filename &optional append visit mustbenew
+@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}.
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.
to implement @code{file-precious-flag}; don't use it yourself unless you
really know what you're doing.
+The optional argument @var{lockname}, if non-@code{nil}, specifies the
+file name to use for purposes of locking and unlocking, overriding
+@var{filename} and @var{visit} for that purpose.
+
The function @code{write-region} converts the data which it writes to
the appropriate file formats specified by @code{buffer-file-format}.
@xref{Format Conversion}. It also calls the functions in the list
@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
These functions test for permission to access a file in specific ways.
@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, this is true if the
-file exists and you have execute permission on the containing
+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
@c Emacs 19 feature
@defun file-executable-p filename
This function returns @code{t} if a file named @var{filename} exists and
-you can execute it. It returns @code{nil} otherwise. On Unix, if the
-file is a directory, execute permission means you can check the
-existence and attributes of files inside the directory, and open those
-files if their modes permit.
+you can execute it. It returns @code{nil} otherwise. On Unix and
+GNU/Linux, if the file is a directory, execute permission means you can
+check the existence and attributes of files inside the directory, and
+open those files if their modes permit.
@end defun
@defun file-writable-p filename
@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.
may be a nonexistent file name.
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 Emacs 19 features
The @dfn{truename} of a file is the name that you get by following
-symbolic links until none remain, then simplifying away @samp{.}@: and
-@samp{..}@: appearing as components. Strictly speaking, a file need not
-have a unique truename; the number of distinct truenames a file has is
-equal to the number of hard links to the file. However, truenames are
-useful because they eliminate symbolic links as a cause of name
-variation.
+symbolic links at all levels until none remain, then simplifying away
+@samp{.}@: and @samp{..}@: appearing as name components. This results
+in a sort of canonical name for the file. A file does not always have a
+unique truename; the number of distinct truenames a file has is equal to
+the number of hard links to the file. However, truenames are useful
+because they eliminate symbolic links as a cause of name variation.
@defun file-truename filename
-The function @code{file-truename} returns the true name of the file
-@var{filename}. This is the name that you get by following symbolic
-links until none remain. The argument must be an absolute file name.
+The function @code{file-truename} returns the truename of the file
+@var{filename}. The argument must be an absolute file name.
@end defun
+@defun file-chase-links filename
+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.
+@end defun
+
+ To illustrate the difference between @code{file-chase-links} and
+@code{file-truename}, suppose that @file{/usr/foo} is a symbolic link to
+the directory @file{/home/foo}, and @file{/home/foo/hello} is an
+ordinary file (or at least, not a symbolic link) or nonexistent. Then
+we would have:
+
+@example
+(file-chase-links "/usr/foo/hello")
+ ;; @r{This does not follow the links in the parent directories.}
+ @result{} "/usr/foo/hello"
+(file-truename "/usr/foo/hello")
+ ;; @r{Assuming that @file{/home} is not a symbolic link.}
+ @result{} "/home/foo/hello"
+@end example
+
@xref{Buffer File Name}, for related information.
@node File Attributes
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)
+ @result{} (nil 1 2235 75
+ (8489 20284)
+ (8489 20284)
(8489 20285)
- 14906 "-rw-rw-rw-"
+ 14906 "-rw-rw-rw-"
nil 129500 -32252)
@end group
@end example
@samp{rm @var{filename}}. If the file has multiple names, it continues
to exist under the other names.
-A suitable kind of @code{file-error} error is signaled if the file
-does not exist, or is not deletable. (On Unix, a file is deletable if
-its directory is writable.)
+A suitable kind of @code{file-error} error is signaled if the file does
+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
@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. On Unix, 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.
+* 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-sans-versions filename
+@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. It returns @code{nil} for extensionless file
+names such as @file{foo}. 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{""}. If the last
+component of a file name begins with a @samp{.}, that @samp{.} doesn't
+count as the beginning of an extension, so, for example,
+@file{.emacs}'s ``extension'' is @code{nil}, not @samp{.emacs}.
+@end defun
+
+@defun file-name-sans-versions filename &optional keep-backup-version
This function returns @var{filename} with any file version numbers,
-backup version numbers, or trailing tildes deleted.
+backup version numbers, or trailing tildes discarded.
+
+If @var{keep-backup-version} is non-@code{nil}, then true file version
+numbers understood as such by the file system are discarded from the
+return value, but backup version numbers are kept.
@example
@group
@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,
+@samp{.} in the last name component, except if that @samp{.} is the
+first character of the file name's last component. 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"
+@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
+
+@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 (or
+backslash), 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
@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
To convert a directory name to its abbreviation, use this
function:
-@defun abbreviate-file-name dirname
+@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, 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
@end defun
@c Emacs 19 feature
-@defun file-relative-name filename directory
+@defun file-relative-name filename &optional directory
This function does the inverse of expansion---it tries to return a
relative name that is equivalent to @var{filename} when interpreted
-relative to @var{directory}.
+relative to @var{directory}. If @var{directory} is omitted or
+@code{nil}, it defaults to the current buffer's default directory.
On some operating systems, an absolute file name begins with a device
name. On such systems, @var{filename} has no relative equivalent based
(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}:
@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
@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
with @code{delete-file}. These special functions exist to create and
delete directories.
-@defun make-directory dirname
+@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.
@end defun
@defun delete-directory dirname
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{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-executable-p}, @code{file-exists-p},
@code{file-local-copy},
-@code{file-modes}, @code{file-name-all-completions},@*
+@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-visited-file-modtime}, @code{shell-command},
+@code{substitute-in-file-name},@*
@code{unhandled-file-name-directory},
@code{vc-registered},
@code{verify-visited-file-modtime},@*
@code{write-region}.
-@end ifinfo
+@end ifnottex
@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-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))
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