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