@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 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
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.
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 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-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 link target as a string.
+(Determining the file name that the link points to from the target is
+nontrivial.)
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
@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
@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.
+This function copies the file modes, too.
+
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.
@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
@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.
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. It returns @code{nil} for extensionless file
+names such as @file{foo}. 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{""}. 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 discarded.
(file-name-sans-extension "big.hack/foo")
@result{} "big.hack/foo"
(file-name-sans-extension "/my/home/.emacs")
- @result{} "/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
+Andrew Innes says that this
@c @defvar directory-sep-char
@c @tindex directory-sep-char
@end defvar
@end ignore
-@defun file-name-extension filename &optional period
-This function returns @var{filename}'s final ``extension,'' if any,
-after applying @code{file-name-sans-versions} to remove any
-version/backup part. 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}.
+@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
@node Directory Names
@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 (or backslash), 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
@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 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
@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.
+@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}.
@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
@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
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-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},@*
@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))
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 specal 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.