@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.
temporary buffer. Visiting the file is not necessary and takes longer.
@xref{Reading from Files}.
-@deffn Command find-file filename
+@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
new buffer and reading the file into it. It also returns that buffer.
@noindent
(See @code{switch-to-buffer} in @ref{Displaying Buffers}.)
+If @var{wildcards} is non-@code{nil}, which is always true in an
+interactive call, then @code{find-file} expands wildcard characters in
+@var{filename} and visits all the matching files.
+
When @code{find-file} is called interactively, it prompts for
@var{filename} in the minibuffer.
@end deffn
-@defun find-file-noselect filename &optional nowarn rawfile
+@defun find-file-noselect filename &optional nowarn rawfile wildcards
This function is the guts of all the file-visiting functions. It finds
or creates a buffer visiting the file @var{filename}, and returns it.
It uses an existing buffer if there is one, and otherwise creates a new
buffer and reads the file into it. You may make the buffer current or
display it in a window if you wish, but this function does not do so.
+If @var{wildcards} is non-@code{nil},
+then @code{find-file-noselect} expands wildcard
+characters in @var{filename} and visits all the matching files.
+
When @code{find-file-noselect} uses an existing buffer, it first
verifies that the file has not changed since it was last visited or
saved in that buffer. If the file has changed, then this function asks
This function displays warning or advisory messages in various peculiar
cases, unless the optional argument @var{nowarn} is non-@code{nil}. For
example, if it needs to create a buffer, and there is no file named
-@var{filename}, it displays the message @samp{New file} in the echo
+@var{filename}, it displays the message @samp{(New file)} in the echo
area, and leaves the buffer empty.
The @code{find-file-noselect} function normally calls
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 example
@end defun
-@deffn Command find-file-other-window filename
+@deffn Command find-file-other-window filename &optional wildcards
This command selects a buffer visiting the file @var{filename}, but
does so in a window other than the selected window. It may use another
existing window or split a window; see @ref{Displaying Buffers}.
@var{filename}.
@end deffn
-@deffn Command find-file-read-only filename
+@deffn Command find-file-read-only filename &optional wildcards
This command selects a buffer visiting the file @var{filename}, like
@code{find-file}, but it marks the buffer as read-only. @xref{Read Only
Buffers}, for related functions and variables.
@var{filename}.
@end deffn
+@tindex find-file-wildcards
+@defvar 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
+
@defvar find-file-hooks
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
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 reading the file got an error because the file does not exist, but
its directory does exist, the caller should pass a non-@code{nil} value
for @var{error}. In that case, @code{after-find-file} issues a warning:
-@samp{(New File)}. For more serious errors, the caller should usually not
+@samp{(New file)}. For more serious errors, the caller should usually not
call @code{after-find-file}.
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-hooks}. 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}.
@end defun
@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 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
against the defined file formats, and converts the file contents if
appropriate. @xref{Format Conversion}. It also calls the functions in
the list @code{after-insert-file-functions}; see @ref{Saving
-Properties}.
+Properties}. Normally, one of the functions in the
+@code{after-insert-file-functions} list determines the coding system
+(@pxref{Coding Systems}) used for decoding the file's contents.
If @var{visit} is non-@code{nil}, this function additionally marks the
buffer as unmodified and sets up various fields in the buffer so that it
@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
or a nonexistent file in a directory where files cannot be created.
@end deffn
-@deffn Command write-region start end filename &optional append visit confirm
+@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}.
@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.
+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{confirm} is non-@code{nil}, then @code{write-region} asks
+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},
+then @code{write-region} does not ask for confirmation, but instead
+it signals an error @code{file-already-exists} if the file already
+exists.
+
+The test for an existing file, when @var{mustbenew} is @code{excl}, uses
+a special system feature. At least for files on a local disk, there is
+no chance that some other program could create a file of the same name
+before Emacs does, without Emacs's noticing.
If @var{visit} is @code{t}, then Emacs establishes an association
between the buffer and the file: the buffer is then visiting that file.
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
arising by recording a @dfn{file lock} when a file is being modified.
Emacs can then detect the first attempt to modify a buffer visiting a
file that is locked by another Emacs job, and ask the user what to do.
+The file lock is really a file, a symbolic link with a special name,
+stored in the same directory as the file you are editing.
- File locks are not completely reliable when multiple machines can
-share file systems. When file locks do not work, it is possible for two
-users to make changes simultaneously, but Emacs can still warn the user
-who saves second. Also, the detection of modification of a buffer
-visiting a file changed on disk catches some cases of simultaneous
-editing; see @ref{Modification Time}.
+ When you access files using NFS, there may be a small probability that
+you and another user will both lock the same file ``simultaneously''.
+If this happens, it is possible for the two users to make changes
+simultaneously, but Emacs will still warn the user who saves second.
+Also, the detection of modification of a buffer visiting a file changed
+on disk catches some cases of simultaneous editing; see
+@ref{Modification Time}.
@defun file-locked-p filename
This function returns @code{nil} if the file @var{filename} is not
@end defun
@defun lock-buffer &optional filename
- This function locks the file @var{filename}, if the current buffer is
+This function locks the file @var{filename}, if the current buffer is
modified. The argument @var{filename} defaults to the current buffer's
visited file. Nothing is done if the current buffer is not visiting a
file, or is not modified.
does nothing if the current buffer is not visiting a file.
@end defun
+ File locking is not supported on some systems. On systems that do not
+support it, the functions @code{lock-buffer}, @code{unlock-buffer} and
+@code{file-locked-p} do nothing and return @code{nil}.
+
@defun ask-user-about-lock file other-user
This function is called when the user tries to modify @var{file}, but it
is locked by another user named @var{other-user}. The default
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. 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.
@defun file-regular-p filename
This function returns @code{t} if the file @var{filename} exists and is
-a regular file (not a directory, symbolic link, named pipe, terminal, or
+a regular file (not a directory, named pipe, terminal, or
other I/O device).
@end defun
@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
The time of last status change as a list of two integers (as above).
@item
-The size of the file in bytes.
+The size of the file in bytes. If the size is too large to fit in a
+Lisp integer, this is a floating point number.
@item
The file's modes, as a string of ten letters or dashes,
last had its inode changed on Aug 19 00:09.
@item 14906
-is 14906 characters long.
+is 14906 bytes long. (It may not contain 14906 characters, though,
+if some of the bytes belong to multibyte sequences.)
@item "-rw-rw-rw-"
has a mode of read and write access for the owner, group, and world.
@end example
This function is meaningless on operating systems where multiple names
-for one file are not allowed.
+for one file are not allowed. Some systems implement multiple names
+by copying the file instead.
See also @code{file-nlinks} in @ref{File Attributes}.
@end defun
@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
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 is not available on systems that don't support symbolic
+links.
@end deffn
@defun define-logical-name varname string
@defun set-default-file-modes mode
This function sets the default file protection for new files created by
Emacs and its subprocesses. Every file created with Emacs initially has
-this protection. On Unix, 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
@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.
-So Emacs considers a file executable if its name ends in @samp{.com},
-@samp{.bat} or @samp{.exe}. This is reflected in the values returned
-by @code{file-modes} and @code{file-attributes}.
+So Emacs considers a file executable if its name ends in one of the
+standard executable extensions, such as @file{.com}, @file{.bat},
+@file{.exe}, and some others. Files that begin with the Unix-standard
+@samp{#!} signature, such as shell and Perl scripts, are also considered
+as executable files. This is reflected in the values returned by
+@code{file-modes} and @code{file-attributes}. Directories are also
+reported with executable bit set, for compatibility with Unix.
@node File Names
@section File Names
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.
(or @dfn{file name within the directory}). Either part may be empty.
Concatenating these two parts reproduces the original file name.
- On Unix, 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.
+ On most systems, the directory part is everything up to and including
+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 Unix, only backup
-files have version numbers in their names. On VMS, every file has a
-version number, but most of the time the file name actually used in
-Emacs omits the version number, so that version numbers in Emacs are
+the name proper and the @dfn{version number}. On most systems, only
+backup files have version numbers in their names. On VMS, every file
+has a version number, but most of the time the file name actually used
+in Emacs omits the version number, so that version numbers in Emacs are
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
-Unix, the function returns a string ending in a slash. On VMS, it
-returns a string ending in one of the three characters @samp{:},
+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{:},
@samp{]}, or @samp{>}.
@example
@end example
@end defun
-@defun file-name-sans-versions filename
+@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
@end example
@end defun
+@ignore
+Andrew Innes says that this
+
+@c @defvar directory-sep-char
+@c @tindex directory-sep-char
+This variable holds the character that Emacs normally uses to separate
+file name components. The default value is @code{?/}, but on MS-Windows
+you can set it to @code{?\\}; then the functions that transform file names
+use backslashes in their output.
+
+File names using backslashes work as input to Lisp primitives even on
+MS-DOS and MS-Windows, even if @code{directory-sep-char} has its default
+value of @code{?/}.
+@end defvar
+@end ignore
+
+@defun file-name-extension filename &optional period
+This function returns @var{filename}'s final ``extension,'' if any,
+after applying @code{file-name-sans-versions} to remove any
+version/backup part. If @var{period} is non-nil, then the returned
+value includes the period that delimits the extension, and if
+@var{filename} has no extension, the value is @code{""}.
+@end defun
+
@node Directory Names
@comment node-name, next, previous, up
@subsection Directory Names
kind of file, and it has a file name, which is related to the directory
name but not identical to it. (This is not quite the same as the usual
Unix terminology.) These two different names for the same entity are
-related by a syntactic transformation. On Unix, this is simple: a
-directory name ends in a slash, whereas the directory's name as a file
-lacks that slash. On VMS, the relationship is more complicated.
+related by a syntactic transformation. On most systems, this is simple:
+a directory name ends in a slash (or backslash), whereas the directory's
+name as a file lacks that slash. On VMS, the relationship is more
+complicated.
The difference between a directory name and its name as a file is
subtle but crucial. When an Emacs variable or function argument is
@defun file-name-as-directory filename
This function returns a string representing @var{filename} in a form
-that the operating system will interpret as the name of a directory. In
-Unix, this means appending a slash to the string (if it does not already
-end in one). On VMS, the function converts a string of the form
+that the operating system will interpret as the name of a directory. On
+most systems, this means appending a slash to the string (if it does not
+already end in one). On VMS, the function converts a string of the form
@file{[X]Y.DIR.1} to the form @file{[X.Y]}.
@example
@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 Unix,
-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}.
+the operating system will interpret as the name of a file. On most
+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
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. The rules on VMS are
-complicated.
+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
@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
@code{expand-file-name} uses the default directory when its second
argument is @code{nil}.
-On Unix systems, the value is always a string ending with a slash.
+Aside from VMS, the value is always a string ending with a slash.
@example
@group
@subsection Generating Unique File Names
Some programs need to write temporary files. Here is the usual way to
-construct a name for such a file:
+construct a name for such a file, starting in Emacs 21:
@example
-(make-temp-name
- (expand-file-name @var{name-of-application}
- temporary-file-directory))
+(make-temp-file @var{name-of-application})
@end example
@noindent
-The job of @code{make-temp-name} is to prevent two different users or
-two different jobs from trying to use the exact same file name. This
-example uses the variable @code{temporary-file-directory} to decide
-where to put the temporary file. All Emacs Lisp programs should
-use @code{temporary-file-directory} for this purpose, to give the user
-a uniform way to specify the directory for all temporary files.
+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-name string
-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.
+@defun make-temp-file prefix &optional dir-flag
+@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
+different in each Emacs job. If @var{prefix} is a relative file name,
+it is expanded against @code{temporary-file-directory}.
@example
@group
-(make-temp-name "/tmp/foo")
+(make-temp-file "foo")
@result{} "/tmp/foo232J6v"
@end group
@end example
+When @code{make-temp-file} returns, the file has been created and 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.
+
To prevent conflicts among different libraries running in the same
-Emacs, each Lisp program that uses @code{make-temp-name} should have its
-own @var{string}. The number added to the end of @var{string}
+Emacs, each Lisp program that uses @code{make-temp-file} should have its
+own @var{prefix}. The number added to the end of @var{prefix}
distinguishes between the same application running in different Emacs
jobs. Additional added characters permit a large number of distinct
names even in one Emacs job.
+@end defun
+
+ The default directory for temporary files is controlled by the
+variable @code{temporary-file-directory}. This variable gives the user
+a uniform way to specify the directory for all temporary files. Some
+programs use @code{small-temporary-file-directory} instead, if that is
+non-@code{nil}. To use it, you should expand the prefix against
+the proper directory before calling @code{make-temp-file}.
+
+ In older Emacs versions where @code{make-temp-file} does not exist,
+you should use @code{make-temp-name} instead:
+
+@example
+(make-temp-name
+ (expand-file-name @var{name-of-application}
+ temporary-file-directory))
+@end example
+
+@defun make-temp-name string
+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.
@end defun
@defvar temporary-file-directory
-@cindex @code{TMPDIR} environment variable.
-@cindex @code{TMP} environment variable.
+@cindex @code{TMPDIR} environment variable
+@cindex @code{TMP} environment variable
+@cindex @code{TEMP} environment variable
This variable specifies the directory name for creating temporary files.
Its value should be a directory name (@pxref{Directory Names}), but it
is good for Lisp programs to cope if the value is a directory's file
@code{expand-file-name} is a good way to achieve that.
The default value is determined in a reasonable way for your operating
-system; on GNU and Unix systems it is based on the @code{TMP} and
-@code{TMPDIR} environment variables.
+system; it is based on the @code{TMPDIR}, @code{TMP} and @code{TEMP}
+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.
+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
+@defvar small-temporary-file-directory
+This variable (new in Emacs 21) specifies the directory name for
+creating certain temporary files, which are likely to be small.
+
+If you want to write a temporary file which is likely to be small, you
+should compute the directory like this:
+
+@example
+(make-temp-file
+ (expand-file-name @var{prefix}
+ (or small-temporary-file-directory
+ temporary-file-directory)))
+@end example
@end defvar
@node File Name Completion
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}:
@var{file} in directory @var{dirname}.
@end defun
+@tindex file-expand-wildcards
+@defun file-expand-wildcards pattern &optional full
+This function expands the wildcard pattern @var{pattern}, returning
+a list of file names that match it.
+
+If @var{pattern} is written as an absolute file name,
+the values are absolute also.
+
+If @var{pattern} is written as a relative file name, it is interpreted
+relative to the current default directory. The file names returned are
+normally also relative to the current default directory. However, if
+@var{full} is non-@code{nil}, they are absolute.
+@end defun
+
@defun insert-directory file switches &optional wildcard full-directory-p
This function inserts (in the current buffer) a directory listing for
directory @var{file}, formatted with @code{ls} according to
describe a directory itself as a file, rather than showing its
contents.)
-This function works by running a directory listing program whose name is
-in the variable @code{insert-directory-program}. If @var{wildcard} is
-non-@code{nil}, it also runs the shell specified by
+On most systems, this function works by running a directory listing
+program whose name is in the variable @code{insert-directory-program}.
+If @var{wildcard} is non-@code{nil}, it also runs the shell specified by
@code{shell-file-name}, to expand the wildcards.
+
+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.
@end defun
@defvar insert-directory-program
This variable's value is the program to run to generate a directory listing
-for the function @code{insert-directory}.
+for the function @code{insert-directory}. It is ignored on systems
+which generate the listing with Lisp code.
@end defvar
@node Create/Delete Dirs
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{delete-file},
@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{delete-file},
@code{diff-latest-backup-file},
@code{vc-regis@discretionary{}{}{}tered},
@code{verify-visited-file-modtime},
@code{write-region}.
+@end flushleft
@end iftex
Handlers for @code{insert-file-contents} typically need to clear the
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