This chapter describes the Emacs Lisp functions and variables to find, create, view, save, and otherwise work with files and directories. A few other file-related functions are described in Buffers, and those related to backups and auto-saving are described in Backups and Auto-Saving.
Many of the file functions take one or more arguments that are file
names. A file name is a string. Most of these functions expand file
name arguments using the function expand-file-name, so that
~ is handled correctly, as are relative file names (including
../ and the empty string). See Functions that Expand Filenames.
In addition, certain magic file names are handled specially. For example, when a remote file name is specified, Emacs accesses the file over the network via an appropriate protocol. See Remote Files in The GNU Emacs Manual. This handling is done at a very low level, so you may assume that all the functions described in this chapter accept magic file names as file name arguments, except where noted. See Making Certain File Names “Magic”, for details.
When file I/O functions signal Lisp errors, they usually use the
condition file-error (see Writing Code to Handle Errors). The error
message is in most cases obtained from the operating system, according
to locale system-messages-locale, and decoded using coding system
locale-coding-system (see Locales).
Visiting a file means reading a file into a buffer. Once this is done, we say that the buffer is visiting that file, and call the file the visited file of the buffer.
A file and a buffer are two different things. A file is information recorded permanently in the computer (unless you delete it). A buffer, on the other hand, is information inside of Emacs that will vanish at the end of the editing session (or when you kill the buffer). When a buffer is visiting a file, it contains information copied from the file. The copy in the buffer is what you modify with editing commands. Changes to the buffer do not change the file; to make the changes permanent, you must save the buffer, which means copying the altered buffer contents back into the file.
Despite the distinction between files and buffers, people often refer to a file when they mean a buffer and vice-versa. Indeed, we say, “I am editing a file”, rather than, “I am editing a buffer that I will soon save as a file of the same name”. Humans do not usually need to make the distinction explicit. When dealing with a computer program, however, it is good to keep the distinction in mind.
This section describes the functions normally used to visit files. For historical reasons, these functions have names starting with ‘find-’ rather than ‘visit-’. See Buffer File Name, for functions and variables that access the visited file name of a buffer or that find an existing buffer by its visited file name.
In a Lisp program, if you want to look at the contents of a file but
not alter it, the fastest way is to use insert-file-contents in a
temporary buffer. Visiting the file is not necessary and takes longer.
See Reading from Files.
This command selects a buffer visiting the file 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.
Aside from some technical details, the body of the find-file
function is basically equivalent to:
(switch-to-buffer (find-file-noselect filename nil nil wildcards))
(See switch-to-buffer in Switching to a Buffer in a Window.)
If wildcards is non-nil, which is always true in an
interactive call, then find-file expands wildcard characters in
filename and visits all the matching files.
When find-file is called interactively, it prompts for
filename in the minibuffer.
This command visits filename, like find-file does, but it
does not perform any format conversions (see File Format Conversion),
character code conversions (see Coding Systems), or end-of-line
conversions (see End of line conversion).
The buffer visiting the file is made unibyte, and its major mode is
Fundamental mode, regardless of the file name. File local variable
specifications in the file (see File Local Variables) are
ignored, and automatic decompression and adding a newline at the end
of the file due to require-final-newline (see require-final-newline) are also disabled.
Note that if Emacs already has a buffer visiting the same file
non-literally, it will not visit the same file literally, but instead
just switch to the existing buffer. If you want to be sure of
accessing a file’s contents literally, you should create a temporary
buffer and then read the file contents into it using
insert-file-contents-literally (see Reading from Files).
This function is the guts of all the file-visiting functions. It returns a buffer visiting the file filename. You may make the buffer current or display it in a window if you wish, but this function does not do so.
The function returns an existing buffer if there is one; otherwise it
creates a new buffer and reads the file into it. When
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 (unless nowarn is non-nil, see below). If the
file has changed, this function asks the user whether to reread the
changed file. If the user says ‘yes’, any edits previously made in
the buffer are lost.
Reading the file involves decoding the file’s contents (see Coding Systems), including end-of-line conversion, and format conversion
(see File Format Conversion). If wildcards is non-nil,
then find-file-noselect expands wildcard characters in
filename and visits all the matching files.
This function displays warning or advisory messages in various peculiar
cases, unless the optional argument nowarn is non-nil. For
example, if it needs to create a buffer, and there is no file named
filename, it displays the message ‘(New file)’ in the echo
area, and leaves the buffer empty. The verification of the file’s last
change is also bypassed if nowarn is non-nil.
The find-file-noselect function normally calls
after-find-file after reading the file (see Subroutines of 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
find-file-hook.
If the optional argument rawfile is non-nil, then
after-find-file is not called, and the
find-file-not-found-functions are not run in case of failure.
What’s more, a non-nil rawfile value suppresses coding
system conversion and format conversion.
The find-file-noselect function usually returns the buffer that
is visiting the file filename. But, if wildcards are actually
used and expanded, it returns a list of buffers that are visiting the
various files.
(find-file-noselect "/etc/fstab")
⇒ #<buffer fstab>
This command selects a buffer visiting the file filename, but does so in a window other than the selected window. It may use another existing window or split a window; see Switching to a Buffer in a Window.
When this command is called interactively, it prompts for filename.
This command selects a buffer visiting the file filename, like
find-file, but it marks the buffer as read-only. See Read-Only Buffers, for related functions and variables.
When this command is called interactively, it prompts for filename.
If this variable is non-nil, then the various find-file
commands check for wildcard characters and visit all the files that
match them (when invoked interactively or when their wildcards
argument is non-nil). If this option is nil, then
the find-file commands ignore their wildcards argument
and never treat wildcard characters specially.
The value of this variable is a list of functions to be called after a file is visited. The file’s local-variables specification (if any) will have been processed before the hooks are run. The buffer visiting the file is current when the hook functions are run.
This variable is a normal hook. See Hooks.
The value of this variable is a list of functions to be called when
find-file or find-file-noselect is passed a nonexistent
file name. find-file-noselect calls these functions as soon as
it detects a nonexistent file. It calls them in the order of the list,
until one of them returns non-nil. buffer-file-name is
already set up.
This is not a normal hook because the values of the functions are used, and in many cases only some of the functions are called.
This buffer-local variable, if set to a non-nil value, makes
save-buffer behave as if the buffer were visiting its file
literally, i.e., without conversions of any kind. The command
find-file-literally sets this variable’s local value, but other
equivalent functions and commands can do that as well, e.g., to avoid
automatic addition of a newline at the end of the file. This variable
is permanent local, so it is unaffected by changes of major modes.
The find-file-noselect function uses two important subroutines
which are sometimes useful in user Lisp code: create-file-buffer
and after-find-file. This section explains how to use them.
This function creates a suitably named buffer for visiting filename, and returns it. It uses filename (sans directory) as the name if that name is free; otherwise, it appends a string such as ‘<2>’ to get an unused name. See also Creating Buffers. Note that the uniquify library affects the result of this function. See Uniquify in The GNU Emacs Manual.
Please note: create-file-buffer does not
associate the new buffer with a file and does not select the buffer.
It also does not use the default major mode.
(create-file-buffer "foo")
⇒ #<buffer foo>
(create-file-buffer "foo")
⇒ #<buffer foo<2>>
(create-file-buffer "foo")
⇒ #<buffer foo<3>>
This function is used by find-file-noselect.
It uses generate-new-buffer (see Creating Buffers).
This function sets the buffer major mode, and parses local variables
(see How Emacs Chooses a Major Mode). It is called by find-file-noselect
and by the default revert function (see 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-nil value
for error. In that case, after-find-file issues a warning:
‘(New file)’. For more serious errors, the caller should usually not
call after-find-file.
If warn is non-nil, then this function issues a warning
if an auto-save file exists and is more recent than the visited file.
If noauto is non-nil, that says not to enable or disable
Auto-Save mode. The mode remains enabled if it was enabled before.
If after-find-file-from-revert-buffer is non-nil, that
means this call was from revert-buffer. This has no direct
effect, but some mode functions and hook functions check the value
of this variable.
If nomodes is non-nil, that means don’t alter the buffer’s
major mode, don’t process local variables specifications in the file,
and don’t run find-file-hook. This feature is used by
revert-buffer in some cases.
The last thing after-find-file does is call all the functions
in the list find-file-hook.
When you edit a file in Emacs, you are actually working on a buffer
that is visiting that file—that is, the contents of the file are
copied into the buffer and the copy is what you edit. Changes to the
buffer do not change the file until you save the buffer, which
means copying the contents of the buffer into the file. Buffers which
are not visiting a file can still be “saved”, in a sense, using
functions in the buffer-local write-contents-functions hook.
This function saves the contents of the current buffer in its visited file if the buffer has been modified since it was last visited or saved. Otherwise it does nothing.
save-buffer is responsible for making backup files. Normally,
backup-option is nil, and save-buffer makes a backup
file only if this is the first save since visiting the file. Other
values for backup-option request the making of backup files in
other circumstances:
save-buffer function marks this version of the file to be
backed up when the buffer is next saved.
save-buffer function unconditionally backs up the previous
version of the file before saving it.
This command saves some modified file-visiting buffers. Normally it
asks the user about each buffer. But if save-silently-p is
non-nil, it saves all the file-visiting buffers without
querying the user.
The optional pred argument provides a predicate that controls
which buffers to ask about (or to save silently if
save-silently-p is non-nil). If pred is
nil, that means to use the value of
save-some-buffers-default-predicate instead of pred. If
the result is nil, it means ask only about file-visiting
buffers. If it is t, that means also offer to save certain
other non-file buffers—those that have a non-nil buffer-local
value of buffer-offer-save (see Killing Buffers). A user
who says ‘yes’ to saving a non-file buffer is asked to specify
the file name to use. The save-buffers-kill-emacs function
passes the value t for pred.
If the predicate is neither t nor 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-nil
value in a certain buffer, that means do offer to save that buffer.
This function writes the current buffer into file filename, makes
the buffer visit that file, and marks it not modified. Then it renames
the buffer based on filename, appending a string like ‘<2>’
if necessary to make a unique buffer name. It does most of this work by
calling set-visited-file-name (see Buffer File Name) and
save-buffer.
If confirm is non-nil, that means to ask for confirmation
before overwriting an existing file. Interactively, confirmation is
required, unless the user supplies a prefix argument.
If filename is a directory name (see Directory Names),
write-file uses the name of the visited file, in directory
filename. If the buffer is not visiting a file, it uses the
buffer name instead.
Saving a buffer runs several hooks. It also performs format
conversion (see File Format Conversion). Note that these hooks,
described below, are only run by save-buffer, they are not run
by other primitives and functions that write buffer text to files, and
in particular auto-saving (see Auto-Saving) doesn’t run these
hooks.
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-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 write-file-functions returns non-nil, it
is responsible for making a backup file (if that is appropriate).
To do so, execute the following code:
(or buffer-backed-up (backup-buffer))
You might wish to save the file modes value returned by
backup-buffer and use that (if non-nil) to set the mode
bits of the file that you write. This is what save-buffer
normally does. See Making Backup Files.
The hook functions in write-file-functions are also responsible
for encoding the data (if desired): they must choose a suitable coding
system and end-of-line conversion (see Coding Systems in Lisp),
perform the encoding (see Explicit Encoding and Decoding), and set
last-coding-system-used to the coding system that was used
(see Encoding and I/O).
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 set-visited-file-name will reset it.
If this is not what you want, you might like to use
write-contents-functions instead.
Even though this is not a normal hook, you can use add-hook and
remove-hook to manipulate the list. See Hooks.
This works just like write-file-functions, but it is intended
for hooks that pertain to the buffer’s contents, not to the particular
visited file or its location, and can be used to create arbitrary save
processes for buffers that aren’t visiting files at all. 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,
but calling set-visited-file-name does not.
If any of the functions in this hook returns non-nil, the file
is considered already written and the rest are not called and neither
are the functions in write-file-functions.
When using this hook to save buffers that are not visiting files (for
instance, special-mode buffers), keep in mind that, if the function
fails to save correctly and returns a nil value,
save-buffer will go on to prompt the user for a file to save
the buffer in. If this is undesirable, consider having the function
fail by raising an error.
This normal hook runs before a buffer is saved in its visited file, regardless of whether that is done normally or by one of the hooks described above. For instance, the copyright.el program uses this hook to make sure the file you are saving has the current year in its copyright notice.
This normal hook runs after a buffer has been saved in its visited file.
If this variable is non-nil, then save-buffer protects
against I/O errors while saving by writing the new file to a temporary
name instead of the name it is supposed to have, and then renaming it to
the intended name after it is clear there are no errors. This procedure
prevents problems such as a lack of disk space from resulting in an
invalid file.
As a side effect, backups are necessarily made by copying. See Backup by Renaming or by Copying?. Yet, at the same time, saving a precious file always breaks all hard links between the file you save and other file names.
Some modes give this variable a non-nil buffer-local value
in particular buffers.
This variable determines whether files may be written out that do
not end with a newline. If the value of the variable is
t, then save-buffer silently adds a newline at the end
of the buffer whenever it does not already end in one. If the value
is visit, Emacs adds a missing newline just after it visits the
file. If the value is visit-save, Emacs adds a missing newline
both on visiting and on saving. For any other non-nil value,
save-buffer asks the user whether to add a newline each time
the case arises.
If the value of the variable is nil, then save-buffer
doesn’t add newlines at all. nil is the default value, but a few
major modes set it to t in particular buffers.
See also the function set-visited-file-name (see Buffer File Name).
To copy the contents of a file into a buffer, use the function
insert-file-contents. (Don’t use the command
insert-file in a Lisp program, as that sets the mark.)
This function inserts the contents of file filename into the current buffer after point. It returns a list of the absolute file name and the length of the data inserted. An error is signaled if filename does not name a file that can be read, or names a directory.
This function checks the file contents against the defined file
formats, and converts the file contents if appropriate and also calls
the functions in the list after-insert-file-functions.
See File Format Conversion. Normally, one of the functions in the
after-insert-file-functions list determines the coding system
(see Coding Systems) used for decoding the file’s contents,
including end-of-line conversion. However, if the file contains null
bytes, it is by default visited without any code conversions.
See inhibit-null-byte-detection.
If visit is non-nil, this function additionally marks the
buffer as unmodified and sets up various fields in the buffer so that it
is visiting the file filename: these include the buffer’s visited
file name and its last save file modtime. This feature is used by
find-file-noselect and you probably should not use it yourself.
If beg and end are non-nil, they should be numbers
that are byte offsets specifying the portion of the file to insert.
In this case, visit must be nil. For example,
(insert-file-contents filename nil 0 500)
inserts the characters coded by the first 500 bytes of a file.
If beg or end happens to be in the middle of a character’s
multibyte sequence, Emacs’s character code conversion will insert one
or more eight-bit characters (a.k.a. “raw bytes”)
(see Character Sets) into the buffer. If you want to read part of
a file this way, we recommend to bind coding-system-for-read to
a suitable value around the call to this function (see Specifying a Coding System for One Operation), and to write Lisp code which will check for raw
bytes at the boundaries, read the entire sequence of these bytes, and
convert them back to valid characters.
If the argument replace is non-nil, it means to replace the
contents of the buffer (actually, just the accessible portion) with the
contents of the file. This is better than simply deleting the buffer
contents and inserting the whole file, because (1) it preserves some
marker positions and (2) it puts less data in the undo list.
It is possible to read a special file (such as a FIFO or an I/O
device) with insert-file-contents, as long as replace is
nil or if-regular, and visit and beg are
nil. However, you should normally use an end argument
for these files to avoid inserting (potentially) unlimited data into
the buffer (for instance, when inserting data from
/dev/urandom).
This function works like insert-file-contents except that each
byte in the file is handled separately, being converted into an
eight-bit character if needed. It does not run
after-insert-file-functions, and does not do format decoding,
character code conversion, automatic uncompression, and so on.
If you want to pass a file name to another process so that another
program can read the file, use the function file-local-copy; see
Making Certain File Names “Magic”.
You can write the contents of a buffer, or part of a buffer, directly
to a file on disk using the append-to-file and
write-region functions. Don’t use these functions to write to
files that are being visited; that could cause confusion in the
mechanisms for visiting.
This function appends the contents of the region delimited by
start and end in the current buffer to the end of file
filename. If that file does not exist, it is created. This
function returns nil.
An error is signaled if you cannot write or create filename.
When called from Lisp, this function is completely equivalent to:
(write-region start end filename t)
This function writes the region delimited by start and end in the current buffer into the file specified by filename.
If start is nil, then the command writes the entire buffer
contents (not just the accessible portion) to the file and
ignores end.
If start is a string, then write-region writes or appends
that string, rather than text from the buffer. end is ignored in
this case.
If append is non-nil, then the specified text is appended
to the existing file contents (if any). If append is a
number, write-region seeks to that byte offset from the start
of the file and writes the data from there.
If mustbenew is non-nil, then write-region asks
for confirmation if filename names an existing file. If
mustbenew is the symbol excl, then write-region
does not ask for confirmation, but instead it signals an error
file-already-exists if the file already exists. Although
write-region normally follows a symbolic link and creates the
pointed-to file if the symbolic link is dangling, it does not follow
symbolic links if mustbenew is excl.
The test for an existing file, when mustbenew is 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 visit is t, then Emacs establishes an association
between the buffer and the file: the buffer is then visiting that file.
It also sets the last file modification time for the current buffer to
filename’s modtime, and marks the buffer as not modified. This
feature is used by save-buffer, but you probably should not use
it yourself.
If visit is a string, it specifies the file name to visit. This
way, you can write the data to one file (filename) while recording
the buffer as visiting another file (visit). The argument
visit is used in the echo area message and also for file locking;
visit is stored in buffer-file-name. This feature is used
to implement file-precious-flag; don’t use it yourself unless you
really know what you’re doing.
The optional argument lockname, if non-nil, specifies the
file name to use for purposes of locking and unlocking, overriding
filename and visit for that purpose.
The function write-region converts the data which it writes to
the appropriate file formats specified by buffer-file-format
and also calls the functions in the list
write-region-annotate-functions.
See File Format Conversion.
Normally, write-region displays the message ‘Wrote
filename’ in the echo area. This message is inhibited if
visit is neither t nor nil nor a string, or if
Emacs is operating in batch mode (see Batch Mode). This
feature is useful for programs that use files for internal purposes,
files that the user does not need to know about.
If this variable’s value is nil, write-region uses the
fsync system call after writing a file. If the value is
t, Emacs does not use fsync. The default value is
t. See Files and Secondary Storage.
The with-temp-file macro evaluates the body forms with a
temporary buffer as the current buffer; then, at the end, it writes the
buffer contents into file file. It kills the temporary buffer
when finished, restoring the buffer that was current before the
with-temp-file form. Then it returns the value of the last form
in body.
The current buffer is restored even in case of an abnormal exit via
throw or error (see Nonlocal Exits).
Like with-temp-buffer (see Current Buffer), the temporary buffer used by this macro does not run
the hooks kill-buffer-hook, kill-buffer-query-functions
(see Killing Buffers), and buffer-list-update-hook
(see The Buffer List).
When two users edit the same file at the same time, they are likely
to interfere with each other. Emacs tries to prevent this situation
from arising by recording a 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. The name is
constructed by prepending .# to the file name of the buffer.
The target of the symbolic link will be of the form
user@host.pid:boot, where user
is replaced with the current username (from user-login-name),
host with the name of the host where Emacs is running (from
system-name), pid with Emacs’s process id, and boot
with the time since the last reboot. :boot is omitted if
the boot time is unavailable. (On file systems that do not support
symbolic links, a regular file is used instead, with contents of the
form user@host.pid:boot.)
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 Buffer Modification Time.
This function returns nil if the file filename is not
locked. It returns t if it is locked by this Emacs process, and
it returns the name of the user who has locked it if it is locked by
some other job.
(file-locked-p "foo")
⇒ nil
This function locks the file filename, if the current buffer is
modified. The argument 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, or if the option create-lockfiles is
nil.
This function unlocks the file being visited in the current buffer,
if the buffer is modified. If the buffer is not modified, then
the file should not be locked, so this function does nothing. It also
does nothing if the current buffer is not visiting a file, or is not locked.
This function handles file system errors by calling display-warning
and otherwise ignores the error.
If this variable is nil, Emacs does not lock files.
By default, Emacs creates the lock files in the same directory as the
files that are being locked. This can be changed by customizing this
variable. Is has the same syntax as
auto-save-file-name-transforms (see Auto-Saving). For
instance, to make Emacs write all the lock files to /var/tmp/,
you could say something like:
(setq lock-file-name-transforms
'(("\\`/.*/\\([^/]+\\)\\'" "/var/tmp/\\1" t)))
This function is called when the user tries to modify file, but it is locked by another user named other-user. The default definition of this function asks the user to say what to do. The value this function returns determines what Emacs does next:
t says to grab the lock on the file. Then
this user may edit the file and other-user loses the lock.
nil says to ignore the lock and let this
user edit the file anyway.
file-locked error, in which
case the change that the user was about to make does not take place.
The error message for this error looks like this:
error→ File is locked: file other-user
where file is the name of the file and other-user is the
name of the user who has locked the file.
If you wish, you can replace the ask-user-about-lock function
with your own version that makes the decision in another way.
You can prevent the creation of remote lock files by setting the
variable remote-file-name-inhibit-locks to t.
This command, called interactively, toggles the local value of
create-lockfiles in the current buffer.
This section describes the functions for retrieving various types of information about files (or directories or symbolic links), such as whether a file is readable or writable, and its size. These functions all take arguments which are file names. Except where noted, these arguments need to specify existing files, or an error is signaled.
Be careful with file names that end in spaces. On some filesystems (notably, MS-Windows), trailing whitespace characters in file names are silently and automatically ignored.
These functions test for permission to access a file for reading, writing, or execution. Unless explicitly stated otherwise, they follow symbolic links. See Distinguishing Kinds of Files.
On some operating systems, more complex sets of access permissions can be specified, via mechanisms such as Access Control Lists (ACLs). See Extended File Attributes, for how to query and set those permissions.
This function returns t if a file named filename appears
to exist. This does not mean you can necessarily read the file, only
that you can probably find out its attributes. (On GNU and other POSIX-like
systems, this is true if the file exists and you have execute
permission on the containing directories, regardless of the
permissions of the file itself.)
If the file does not exist, or if there was trouble determining
whether the file exists, this function returns nil.
Since a file name that is an empty string is interpreted relative to
the current buffer’s default directory (see Absolute and Relative File Names),
calling file-exists-p with an argument that is an empty string
will report about the buffer’s default directory.
Directories are files, so file-exists-p can return t
when given a directory. However, because file-exists-p follows
symbolic links, it returns t for a symbolic link name only if
the target of the link exists; if your Lisp program needs to consider
dangling symlinks whose target doesn’t exist as existing files,
use file-attributes (see File Attributes) instead of
file-exists-p.
This function returns t if a file named filename exists
and you can read it. It returns nil otherwise.
This function returns t if a file named filename exists
and you can execute it. It returns nil otherwise. On GNU and
other POSIX-like systems, 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.
This function returns t if the file filename can be written
or created by you, and nil otherwise. A file is writable if the
file exists and you can write it. It is creatable if it does not exist,
but its parent directory does exist and you can write in that
directory.
In the example below, foo is not writable because the parent directory does not exist, even though the user could create such a directory.
(file-writable-p "~/no-such-dir/foo")
⇒ nil
This function returns t if you have permission to open existing
files in the directory whose name as a file is dirname;
otherwise (e.g., if there is no such directory), it returns nil.
The value of dirname may be either a directory name (such as
/foo/) or the file name of a file which is a directory
(such as /foo, without the final slash).
For example, from the following we deduce that any attempt to read a file in /foo/ will give an error:
(file-accessible-directory-p "/foo")
⇒ nil
This macro ensures that default-directory is bound to an
existing directory before executing body. If
default-directory already exists, that’s preferred, and
otherwise some other directory is used. This macro can be useful, for
instance, when calling an external command that requires that it’s
running in a directory that exists. The chosen directory is not
guaranteed to be writable.
If you can read filename this function returns nil;
otherwise it signals an error
using string as the error message text.
If the user option remote-file-name-access-timeout is a
positive number, the function signals an error when it doesn’t finish
after that time (in seconds). This applies only to remote files, and
only when there is no additional time spent while reading passwords or
alike.
This function returns t if deleting the file filename and
then creating it anew would keep the file’s owner unchanged. It also
returns t for nonexistent files.
If the optional argument group is non-nil, this function
also checks that the file’s group would be unchanged.
This function does not follow symbolic links.
This function returns the mode bits of filename—an
integer summarizing its read, write, and execution permissions.
This function follows symbolic links. If the file does not exist, the
return value is nil.
See File permissions in The GNU Coreutils
Manual, for a description of mode bits. For example, if the
low-order bit is 1, the file is executable by all users; if the
second-lowest-order bit is 1, the file is writable by all users; etc.
The highest possible value is 4095 (7777 octal), meaning that everyone
has read, write, and execute permission, the SUID bit is set
for both others and group, and the sticky bit is set.
By default this function follows symbolic links. However, if the
optional argument flag is the symbol nofollow, this
function does not follow filename if it is a symbolic link;
this can help prevent inadvertently obtaining the mode bits of a file
somewhere else, and is more consistent with file-attributes
(see File Attributes).
See Changing File Names and Attributes, for the set-file-modes function, which
can be used to set these permissions.
(file-modes "~/junk/diffs" 'nofollow)
⇒ 492 ; Decimal integer.
(format "%o" 492)
⇒ "754" ; Convert to octal.
(set-file-modes "~/junk/diffs" #o666 'nofollow)
⇒ nil
$ ls -l diffs -rw-rw-rw- 1 lewis lewis 3063 Oct 30 16:00 diffs
MS-DOS note: On MS-DOS, there is no such thing as an
executable file mode bit. So file-modes considers a file
executable if its name ends in one of the standard executable
extensions, such as .com, .bat, .exe, and some
others. Files that begin with the POSIX-standard ‘#!’ signature,
such as shell and Perl scripts, are also considered executable.
Directories are also reported as executable, for compatibility with
POSIX. These conventions are also followed by file-attributes
(see File Attributes).
This section describes how to distinguish various kinds of files, such as directories, symbolic links, and ordinary files.
Symbolic links are ordinarily followed wherever they appear. For example, to interpret the file name a/b/c, any of a, a/b, and a/b/c can be symbolic links that are followed, possibly recursively if the link targets are themselves symbolic links. However, a few functions do not follow symbolic links at the end of a file name (a/b/c in this example). Such a function is said to not follow symbolic links.
If the file filename is a symbolic link, this function does not follow it and instead returns its link target as a string. (The link target string is not necessarily the full absolute file name of the target; determining the full file name that the link points to is nontrivial, see below.)
If the file filename is not a symbolic link, or does not exist,
or if there is trouble determining whether it is a symbolic link,
file-symlink-p returns nil.
Here are a few examples of using this function:
(file-symlink-p "not-a-symlink")
⇒ nil
(file-symlink-p "sym-link")
⇒ "not-a-symlink"
(file-symlink-p "sym-link2")
⇒ "sym-link"
(file-symlink-p "/bin")
⇒ "/pub/bin"
Note that in the third example, the function returned sym-link, but did not proceed to resolve it, although that file is itself a symbolic link. That is because this function does not follow symbolic links—the process of following the symbolic links does not apply to the last component of the file name.
The string that this function returns is what is recorded in the symbolic link; it may or may not include any leading directories. This function does not expand the link target to produce a fully-qualified file name, and in particular does not use the leading directories, if any, of the filename argument if the link target is not an absolute file name. Here’s an example:
(file-symlink-p "/foo/bar/baz")
⇒ "some-file"
Here, although /foo/bar/baz was given as a fully-qualified file
name, the result is not, and in fact does not have any leading
directories at all. And since some-file might itself be a
symbolic link, you cannot simply prepend leading directories to it,
nor even naively use expand-file-name (see Functions that Expand Filenames) to produce its absolute file name.
For this reason, this function is seldom useful if you need to
determine more than just the fact that a file is or isn’t a symbolic
link. If you actually need the file name of the link target, use
file-chase-links or file-truename, described in
Truenames.
This function returns t if filename is the name of an
existing directory. It returns nil if filename does
not name a directory, or if there is trouble determining whether
it is a directory.
This function follows symbolic links.
(file-directory-p "~rms")
⇒ t
(file-directory-p "~rms/lewis/files.texi")
⇒ nil
(file-directory-p "~rms/lewis/no-such-file")
⇒ nil
(file-directory-p "$HOME")
⇒ nil
(file-directory-p
(substitute-in-file-name "$HOME"))
⇒ t
This function returns t if the file filename exists and is
a regular file (not a directory, named pipe, terminal, or
other I/O device).
It returns nil if filename does not exist or is not a regular
file, or if there is trouble determining whether it is a regular file.
This function follows symbolic links.
The truename of a file is the name that you get by following symbolic links at all levels until none remain, then simplifying away ‘.’ and ‘..’ 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.
This function returns the truename of the file filename. If the
argument is not an absolute file name, this function first expands it
against default-directory.
This function does not expand environment variables. Only
substitute-in-file-name does that. See Definition of substitute-in-file-name.
If you may need to follow symbolic links preceding ‘..’
appearing as a name component, call file-truename without prior
direct or indirect calls to expand-file-name. Otherwise, the
file name component immediately preceding ‘..’ will be
simplified away before file-truename is called. To
eliminate the need for a call to expand-file-name,
file-truename handles ‘~’ in the same way that
expand-file-name does.
If the target of a symbolic links has remote file name syntax,
file-truename returns it quoted. See Functions that Expand Filenames.
This function follows symbolic links, starting with filename, until it finds a file name which is not the name of a symbolic link. Then it returns that file name. This function does not follow symbolic links at the level of parent directories.
If you specify a number for limit, then after chasing through that many links, the function just returns what it has even if that is still a symbolic link.
To illustrate the difference between file-chase-links and
file-truename, suppose that /usr/foo is a symbolic link to
the directory /home/foo, and /home/foo/hello is an
ordinary file (or at least, not a symbolic link) or nonexistent. Then
we would have:
(file-chase-links "/usr/foo/hello")
;; This does not follow the links in the parent directories.
⇒ "/usr/foo/hello"
(file-truename "/usr/foo/hello")
;; Assuming that /home is not a symbolic link.
⇒ "/home/foo/hello"
This function returns t if the files file1 and
file2 name the same file. This is similar to comparing their
truenames, except that remote file names are also handled in an
appropriate manner. If file1 or file2 does not exist, the
return value is unspecified.
Sometimes file names or their parts need to be compared as strings, in
which case it’s important to know whether the underlying filesystem is
case-insensitive. This function returns t if file
filename is on a case-insensitive filesystem. It always returns
t on MS-DOS and MS-Windows. On Cygwin and macOS,
filesystems may or may not be case-insensitive, and the function tries
to determine case-sensitivity by a runtime test. If the test is
inconclusive, the function returns t on Cygwin and nil
on macOS.
Currently this function always returns nil on platforms other
than MS-DOS, MS-Windows, Cygwin, and macOS. It does not detect
case-insensitivity of mounted filesystems, such as Samba shares or
NFS-mounted Windows volumes. On remote hosts, it assumes t for
the ‘smb’ method. For all other connection methods, runtime
tests are performed.
This function determines the responsible VC backend of the given
file. For example, if emacs.c is a file tracked by Git,
(vc-responsible-backend "emacs.c") returns ‘Git’.
Note that if file is a symbolic link,
vc-responsible-backend will not resolve it—the backend of the
symbolic link file itself is reported. To get the backend VC of the
file to which file refers, wrap file with a symbolic link
resolving function such as file-chase-links:
(vc-responsible-backend (file-chase-links "emacs.c"))
This section describes the functions for getting detailed information about a file, including the owner and group numbers, the number of names, the inode number, the size, and the times of access and modification.
This function returns t if the file filename1 is
newer than file filename2. If filename1 does not
exist, it returns nil. If filename1 does exist, but
filename2 does not, it returns t. Otherwise, it compares
the times of last modification of the files.
In the following example, assume that the file aug-19 was written on the 19th, aug-20 was written on the 20th, and the file no-file doesn’t exist at all.
(file-newer-than-file-p "aug-19" "aug-20")
⇒ nil
(file-newer-than-file-p "aug-20" "aug-19")
⇒ t
(file-newer-than-file-p "aug-19" "no-file")
⇒ t
(file-newer-than-file-p "no-file" "aug-19")
⇒ nil
This function returns non-nil if the time stamp of
filename has changed since the last call. When called for the
first time for some filename, it records the last modification
time and size of the file, and returns non-nil when
filename exists. Thereafter, when called for the same
filename, it compares the current time stamp and size with the
recorded ones, and returns non-nil only if either the time
stamp or the size (or both) are different. This is useful when a Lisp
program wants to re-read a file whenever it changes. With an optional
argument tag, which must be a symbol, the size and modification
time comparisons are limited to calls with the same tag.
This function returns a list of attributes of file filename. If
the specified file does not exist, it returns nil.
This function does not follow symbolic links.
The optional parameter id-format specifies the preferred format
of attributes UID and GID (see below)—the
valid values are 'string and 'integer. The latter is
the default, but we plan to change that, so you should specify a
non-nil value for id-format if you use the returned
UID or GID.
On GNU platforms when operating on a local file, this function is
atomic: if the filesystem is simultaneously being changed by some
other process, this function returns the file’s attributes either
before or after the change. Otherwise this function is not atomic,
and might return nil if it detects the race condition, or might
return a hodgepodge of the previous and current file attributes.
Accessor functions are provided to access the elements in this list. The accessors are mentioned along with the descriptions of the elements below.
The elements of the list, in order, are:
t for a directory, a string for a symbolic link (the name
linked to), or nil for a text file
(file-attribute-type).
file-attribute-link-number).
Alternate names, also known as hard links, can be created by using the
add-name-to-file function (see Changing File Names and Attributes).
file-attribute-user-id). However, if it does not correspond
to a named user, the value is an integer.
file-attribute-group-id).
file-attribute-access-time). The timestamp is in the
style of current-time (see Time of Day) and is truncated
to that of the filesystem’s timestamp resolution; for example, on some
FAT-based filesystems, only the date of last access is recorded, so
this time will always hold the midnight of the day of the last access.
file-attribute-modification-time). This is the last time when
the file’s contents were modified.
file-attribute-status-change-time). This is the time of the
last change to the file’s access mode bits, its owner and group, and
other information recorded in the filesystem for the file, beyond the
file’s contents.
file-attribute-size).
file-attribute-modes).
file-attribute-inode-number),
a nonnegative integer.
file-attribute-device-number), an integer or a cons cell of
two integers. The latter is sometimes used by remote files, in order
to distinguish remote filesystems from local ones.
The file’s inode and device together give enough information
to distinguish any two files on the system—no two files can have the
same values for both of these attributes. This tuple that uniquely
identifies the file is returned by file-attribute-file-identifier.
For example, here are the file attributes for files.texi:
(file-attributes "files.texi" 'string)
⇒ (nil 1 "lh" "users"
(20614 64019 50040 152000)
(20000 23 0 0)
(20614 64555 902289 872000)
122295 "-rw-rw-rw-"
t 6473924464520138
1014478468)
and here is how the result is interpreted:
nilis neither a directory nor a symbolic link.
1has only one name (the name files.texi in the current default directory).
"lh"is owned by the user with name ‘lh’.
"users"is in the group with name ‘users’.
(20614 64019 50040 152000)was last accessed on October 23, 2012, at 20:12:03.050040152 UTC.
(This timestamp is (1351023123050040152 . 1000000000)
if current-time-list is nil.)
(20000 23 0 0)was last modified on July 15, 2001, at 08:53:43.000000000 UTC.
(This timestamp is (1310720023000000000 . 1000000000)
if current-time-list is nil.)
(20614 64555 902289 872000)last had its status changed on October 23, 2012, at 20:20:59.902289872 UTC.
(This timestamp is (1351023659902289872 . 1000000000)
if current-time-list is nil.)
122295is 122295 bytes long. (It may not contain 122295 characters, though, if some of the bytes belong to multibyte sequences, and also if the end-of-line format is CR-LF.)
"-rw-rw-rw-"has a mode of read and write access for the owner, group, and world.
tis merely a placeholder; it carries no information.
6473924464520138has an inode number of 6473924464520138.
1014478468is on the file-system device whose number is 1014478468.
This function returns the number of names (i.e., hard links) that
file filename has. If the file does not exist, this function
returns nil. Note that symbolic links have no effect on this
function, because they are not considered to be names of the files
they link to. This function does not follow symbolic links.
$ ls -l foo* -rw-rw-rw- 2 rms rms 4 Aug 19 01:27 foo -rw-rw-rw- 2 rms rms 4 Aug 19 01:27 foo1
(file-nlinks "foo")
⇒ 2
(file-nlinks "doesnt-exist")
⇒ nil
On some operating systems, each file can be associated with arbitrary extended file attributes. At present, Emacs supports querying and setting two specific sets of extended file attributes: Access Control Lists (ACLs) and SELinux contexts. These extended file attributes are used, on some systems, to impose more sophisticated file access controls than the basic Unix-style permissions discussed in the previous sections.
A detailed explanation of ACLs and SELinux is beyond the scope of this manual. For our purposes, each file can be associated with an ACL, which specifies its properties under an ACL-based file control system, and/or an SELinux context, which specifies its properties under the SELinux system.
This function returns the ACL for the file filename. The exact
Lisp representation of the ACL is unspecified (and may change in
future Emacs versions), but it is the same as what set-file-acl
takes for its acl argument (see Changing File Names and Attributes).
The underlying ACL implementation is platform-specific; on GNU/Linux and BSD, Emacs uses the POSIX ACL interface, while on MS-Windows Emacs emulates the POSIX ACL interface with native file security APIs.
If ACLs are not supported or the file does not exist,
then the return value is nil.
This function returns the SELinux context of the file filename,
as a list of the form (user role type
range). The list elements are the context’s user, role, type,
and range respectively, as Lisp strings; see the SELinux documentation
for details about what these actually mean. The return value has the
same form as what set-file-selinux-context takes for its
context argument (see Changing File Names and Attributes).
If SELinux is not supported or the file does not exist,
then the return value is (nil nil nil nil).
This function returns an alist of the Emacs-recognized extended
attributes of file filename. Currently, it serves as a
convenient way to retrieve both the ACL and SELinux context; you can
then call the function set-file-extended-attributes, with the
returned alist as its second argument, to apply the same file access
attributes to another file (see Changing File Names and Attributes).
One of the elements is (acl . acl), where acl has
the same form returned by file-acl.
Another element is (selinux-context . context), where
context is the SELinux context, in the same form returned by
file-selinux-context.
This section explains how to search for a file in a list of directories (a path), or for an executable file in the standard list of executable file directories.
To search for a user-specific configuration file, See Standard File Names, for the locate-user-emacs-file function.
This function searches for a file whose name is filename in a
list of directories given by path, trying the suffixes in
suffixes. If it finds such a file, it returns the file’s
absolute file name (see Absolute and Relative File Names); otherwise it returns
nil.
The optional argument suffixes gives the list of file-name
suffixes to append to filename when searching.
locate-file tries each possible directory with each of these
suffixes. If suffixes is nil, or (""), then there
are no suffixes, and filename is used only as-is. Typical
values of suffixes are exec-suffixes (see Functions that Create Subprocesses), load-suffixes, load-file-rep-suffixes and
the return value of the function get-load-suffixes (see Load Suffixes).
Typical values for path are exec-path (see Functions that Create Subprocesses) when looking for executable programs, or load-path
(see Library Search) when looking for Lisp files. If
filename is absolute, path has no effect, but the suffixes
in suffixes are still tried.
The optional argument predicate, if non-nil, specifies a
predicate function for testing whether a candidate file is suitable.
The predicate is passed the candidate file name as its single
argument. If predicate is nil or omitted,
locate-file uses file-readable-p as the predicate.
See Distinguishing Kinds of Files, for other useful predicates, e.g.,
file-executable-p and file-directory-p.
This function will normally skip directories, so if you want it to
find directories, make sure the predicate function returns
dir-ok for them. For example:
(locate-file "html" '("/var/www" "/srv") nil
(lambda (f) (if (file-directory-p f) 'dir-ok)))
For compatibility, predicate can also be one of the symbols
executable, readable, writable, exists, or
a list of one or more of these symbols.
This function searches for the executable file of the named
program and returns the absolute file name of the executable,
including its file-name extensions, if any. It returns nil if
the file is not found. The function searches in all the directories
in exec-path, and tries all the file-name extensions in
exec-suffixes (see Functions that Create Subprocesses).
If remote is non-nil, and default-directory is a
remote directory, program is searched on the respective remote host.
The functions in this section rename, copy, delete, link, and set
the modes (permissions) of files. Typically, they signal a
file-error error if they fail to perform their function,
reporting the system-dependent error message that describes the reason
for the failure. If they fail because a file is missing, they signal
a file-missing error instead.
For performance, the operating system may cache or alias changes made by these functions instead of writing them immediately to secondary storage. See Files and Secondary Storage.
In the functions that have an argument newname, if this argument is a directory name it is treated as if the nondirectory part of the source name were appended. Typically, a directory name is one that ends in ‘/’ (see Directory Names). For example, if the old name is a/b/c, the newname d/e/f/ is treated as if it were d/e/f/c. This special treatment does not apply if newname is not a directory name but names a file that is a directory; for example, the newname d/e/f is left as-is even if d/e/f happens to be a directory.
In the functions that have an argument newname, if a file by the name of newname already exists, the actions taken depend on the value of the argument ok-if-already-exists:
file-already-exists error if
ok-if-already-exists is nil.
This function gives the file named oldname the additional name newname. This means that newname becomes a new hard link to oldname.
If newname is a symbolic link, its directory entry is replaced, not the directory entry it points to. If oldname is a symbolic link, this function might or might not follow the link; it does not follow the link on GNU platforms. If oldname is a directory, this function typically fails, although for the superuser on a few old-fashioned non-GNU platforms it can succeed and create a filesystem that is not tree-structured.
In the first part of the following example, we list two files, foo and foo3.
$ ls -li fo* 81908 -rw-rw-rw- 1 rms rms 29 Aug 18 20:32 foo 84302 -rw-rw-rw- 1 rms rms 24 Aug 18 20:31 foo3
Now we create a hard link, by calling add-name-to-file, then list
the files again. This shows two names for one file, foo and
foo2.
(add-name-to-file "foo" "foo2")
⇒ nil
$ ls -li fo* 81908 -rw-rw-rw- 2 rms rms 29 Aug 18 20:32 foo 81908 -rw-rw-rw- 2 rms rms 29 Aug 18 20:32 foo2 84302 -rw-rw-rw- 1 rms rms 24 Aug 18 20:31 foo3
Finally, we evaluate the following:
(add-name-to-file "foo" "foo3" t)
and list the files again. Now there are three names for one file: foo, foo2, and foo3. The old contents of foo3 are lost.
(add-name-to-file "foo1" "foo3")
⇒ nil
$ ls -li fo* 81908 -rw-rw-rw- 3 rms rms 29 Aug 18 20:32 foo 81908 -rw-rw-rw- 3 rms rms 29 Aug 18 20:32 foo2 81908 -rw-rw-rw- 3 rms rms 29 Aug 18 20:32 foo3
This function is meaningless on operating systems where multiple names for one file are not allowed. Some systems implement multiple names by copying the file instead.
See also file-nlinks in File Attributes.
This command renames the file filename as newname.
If filename has additional names aside from filename, it
continues to have those names. In fact, adding the name newname
with add-name-to-file and then deleting filename has the
same effect as renaming, aside from momentary intermediate states and
treatment of errors, directories and symbolic links.
This command does not follow symbolic links. If filename is a symbolic link, this command renames the symbolic link, not the file it points to. If newname is a symbolic link, its directory entry is replaced, not the directory entry it points to.
This command does nothing if filename and newname are the same directory entry, i.e., if they refer to the same parent directory and give the same name within that directory. Otherwise, if filename and newname name the same file, this command does nothing on POSIX-conforming systems, and removes filename on some non-POSIX systems.
If newname exists, then it must be an empty directory if oldname is a directory and a non-directory otherwise.
This command copies the file oldname to newname. An error is signaled if oldname is not a regular file. If newname names a directory, it copies oldname into that directory, preserving its final name component.
This function follows symbolic links, except that it does not follow a dangling symbolic link to create newname.
If time is non-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,
copy-file signals a file-date-error error. In an
interactive call, a prefix argument specifies a non-nil value
for time.
If argument preserve-uid-gid is nil, we let the operating
system decide the user and group ownership of the new file (this is
usually set to the user running Emacs). If preserve-uid-gid is
non-nil, we attempt to copy the user and group ownership of the
file. This works only on some operating systems, and only if you have
the correct permissions to do so.
If the optional argument preserve-permissions is non-nil,
this function copies the file modes (or “permissions”) of
oldname to newname, as well as the Access Control List and
SELinux context (if any). See Information about Files.
Otherwise, the file modes of newname are left unchanged if it is
an existing file, and set to those of oldname, masked by the
default file permissions (see set-default-file-modes below), if
newname is to be newly created. The Access Control List or
SELinux context are not copied over in either case.
This command makes a symbolic link to target, named linkname. This is like the shell command ‘ln -s target linkname’. The target argument is treated only as a string; it need not name an existing file. If ok-if-already-exists is an integer, indicating interactive use, then leading ‘~’ is expanded and leading ‘/:’ is stripped in the target string.
If target is a relative file name, the resulting symbolic link is interpreted relative to the directory containing the symbolic link. See Absolute and Relative File Names.
If both target and linkname have remote file name syntax, and if both remote identifications are equal, the symbolic link points to the local file name part of target.
This function is not available on systems that don’t support symbolic links.
This command deletes the file filename. If the file has
multiple names, it continues to exist under the other names. If
filename is a symbolic link, delete-file deletes only the
symbolic link and not its target.
The command signals a suitable kind of file-error error if
filename cannot be deleted. (On GNU and other POSIX-like
systems, a file can be deleted if its directory is writable.) If the
file does not exist, this command will not signal any error.
If the optional argument trash is non-nil and the
variable delete-by-moving-to-trash is non-nil, this
command moves the file into the system Trash instead of deleting it.
See Miscellaneous File Operations in The GNU
Emacs Manual. When called interactively, trash is t if
no prefix argument is given, and nil otherwise.
See also delete-directory in Creating, Copying and Deleting Directories.
If this variable is non-nil, remote files are never moved to
the Trash. They are deleted instead.
This function sets the file mode (or permissions) of filename to mode.
By default this function follows symbolic links. However, if the
optional argument flag is the symbol nofollow, this
function does not follow filename if it is a symbolic link;
this can help prevent inadvertently changing the mode bits of a file
somewhere else. On platforms that do not support changing mode bits
on a symbolic link, this function signals an error when filename
is a symbolic link and flag is nofollow.
If called non-interactively, mode must be an integer. Only the lowest 12 bits of the integer are used; on most systems, only the lowest 9 bits are meaningful. You can use the Lisp construct for octal numbers to enter mode. For example,
(set-file-modes "myfile" #o644 'nofollow)
specifies that the file should be readable and writable for its owner,
readable for group members, and readable for all other users.
See File permissions in The GNU Coreutils
Manual, for a description of mode bit specifications.
Interactively, mode is read from the minibuffer using
read-file-modes (see below), which lets the user type in either
an integer or a string representing the permissions symbolically.
See Testing Accessibility, for the function file-modes, which
returns the permissions of a file.
This function sets the default permissions for new files created by
Emacs and its subprocesses. Every file created with Emacs initially
has these permissions, or a subset of them (write-region will
not grant execute permissions even if the default file permissions
allow execution). On GNU and other POSIX-like systems, the default
permissions are given by the bitwise complement of the ‘umask’
value, i.e. each bit that is set in the argument mode will be
reset in the default permissions with which Emacs creates
files.
The argument mode should be an integer which specifies the
permissions, similar to set-file-modes above. Only the lowest
9 bits are meaningful.
The default file permissions have no effect when you save a modified version of an existing file; saving a file preserves its existing permissions.
This macro evaluates the body forms with the default
permissions for new files temporarily set to modes (whose value
is as for set-file-modes above). When finished, it restores
the original default file permissions, and returns the value of the
last form in body.
This is useful for creating private files, for example.
This function returns the default file permissions, as an integer.
This function reads a set of file mode bits from the minibuffer. The first optional argument prompt specifies a non-default prompt. Second second optional argument base-file is the name of a file on whose permissions to base the mode bits that this function returns, if what the user types specifies mode bits relative to permissions of an existing file.
If user input represents an octal number, this function returns that
number. If it is a complete symbolic specification of mode bits, as
in "u=rwx", the function converts it to the equivalent numeric
value using file-modes-symbolic-to-number and returns the
result. If the specification is relative, as in "o+g", then
the permissions on which the specification is based are taken from the
mode bits of base-file. If base-file is omitted or
nil, the function uses 0 as the base mode bits. The
complete and relative specifications can be combined, as in
"u+r,g+rx,o+r,g-w". See File permissions in The
GNU Coreutils Manual, for a description of file mode
specifications.
This function converts a symbolic file mode specification in
modes into the equivalent integer. If the symbolic
specification is based on an existing file, that file’s mode bits are
taken from the optional argument base-modes; if that argument is
omitted or nil, it defaults to 0, i.e., no access rights at
all.
This function converts a numeric file mode specification in
modes into the equivalent string form. The string which this
function returns is in the same format produced by the shell command
ls -l and by file-attributes, not the symbolic
form accepted by file-modes-symbolic-to-number and the
chmod shell command.
This function sets the access and modification times of filename
to time. The return value is t if the times are successfully
set, otherwise it is nil. time defaults to the current
time and must be a time value (see Time of Day).
By default this function follows symbolic links. However, if the
optional argument flag is the symbol nofollow, this
function does not follow filename if it is a symbolic link;
this can help prevent inadvertently changing the times of a file
somewhere else. On platforms that do not support changing times
on a symbolic link, this function signals an error when filename
is a symbolic link and flag is nofollow.
This function sets the Emacs-recognized extended file attributes for
filename. The second argument attribute-alist should be
an alist of the same form returned by file-extended-attributes.
The return value is t if the attributes are successfully set,
otherwise it is nil.
See Extended File Attributes.
This function sets the SELinux security context for filename to
context. The context argument should be a list
(user role type range), where each
element is a string. See Extended File Attributes.
The function returns t if it succeeds in setting the SELinux
context of filename. It returns nil if the context was
not set (e.g., if SELinux is disabled, or if Emacs was compiled
without SELinux support).
This function sets the Access Control List for filename to
acl. The acl argument should have the same form returned
by the function file-acl. See Extended File Attributes.
The function returns t if it successfully sets the ACL of
filename, nil otherwise.
After Emacs changes a file, there are two reasons the changes might not survive later failures of power or media, both having to do with efficiency. First, the operating system might alias written data with data already stored elsewhere on secondary storage until one file or the other is later modified; this will lose both files if the only copy on secondary storage is lost due to media failure. Second, the operating system might not write data to secondary storage immediately, which will lose the data if power is lost or if there is a media failure.
Although both sorts of failures can largely be avoided by a suitably
configured system, such systems are typically more expensive or
less efficient. In lower-end systems, to survive media failure you
can copy the file to a different device, and to survive a power
failure (or be immediately notified of a media failure) you can use
the write-region function with the
write-region-inhibit-fsync variable set to nil.
Although this variable is ordinarily t because that can
significantly improve performance, it may make sense to temporarily
bind it to nil if using Emacs to implement database-like
transactions that survive power failure on lower-end systems.
See Writing to Files.
On some platforms when Emacs changes a file other processes might not
be notified of the change immediately. Setting
write-region-inhibit-fsync to nil may improve
notification speed in this case, though there are no guarantees.
Files are generally referred to by their names, in Emacs as elsewhere. File names in Emacs are represented as strings. The functions that operate on a file all expect a file name argument.
In addition to operating on files themselves, Emacs Lisp programs often need to operate on file names; i.e., to take them apart and to use part of a name to construct related file names. This section describes how to manipulate file names.
The functions in this section do not actually access files, so they can operate on file names that do not refer to an existing file or directory.
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 POSIX syntax; but they always return POSIX syntax. This enables Lisp programs to specify file names in POSIX syntax and work properly on all systems without change.22
The operating system groups files into directories. To specify a file, you must specify the directory and the file’s name within that directory. Therefore, Emacs considers a file name as having two main parts: the directory name part, and the nondirectory part (or file name within the directory). Either part may be empty. Concatenating these two parts reproduces the original file name. 23
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.
For some purposes, the nondirectory part is further subdivided into the name proper and the version number. On most systems, only backup files have version numbers in their names.
This function returns the directory part of filename, as a
directory name (see Directory Names), or nil if
filename does not include a directory part.
On GNU and other POSIX-like systems, a string returned by this function always ends in a slash. On MS-DOS it can also end in a colon.
(file-name-directory "lewis/foo") ; GNU example
⇒ "lewis/"
(file-name-directory "foo") ; GNU example
⇒ nil
This function returns the nondirectory part of filename.
(file-name-nondirectory "lewis/foo")
⇒ "foo"
(file-name-nondirectory "foo")
⇒ "foo"
(file-name-nondirectory "lewis/")
⇒ ""
This function returns filename with any file version numbers, backup version numbers, or trailing tildes discarded.
If keep-backup-version is non-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.
(file-name-sans-versions "~rms/foo.~1~")
⇒ "~rms/foo"
(file-name-sans-versions "~rms/foo~")
⇒ "~rms/foo"
(file-name-sans-versions "~rms/foo")
⇒ "~rms/foo"
This function returns filename’s final extension, if any,
after applying file-name-sans-versions to remove any
version/backup part. The extension, in a file name, is the part that
follows the last ‘.’ in the last name component (minus any
version/backup part).
This function returns nil for extensionless file names such as
foo. It returns "" for null extensions, as in
foo.. If the last component of a file name begins with a
‘.’, that ‘.’ doesn’t count as the beginning of an
extension. Thus, .emacs’s extension is nil, not
‘.emacs’.
If period is non-nil, then the returned value includes
the period that delimits the extension, and if filename has no
extension, the value is "".
This function returns filename with its extension set to extension. A single leading dot in the extension will be stripped if there is one. For example:
(file-name-with-extension "file" "el")
⇒ "file.el"
(file-name-with-extension "file" ".el")
⇒ "file.el"
(file-name-with-extension "file.c" "el")
⇒ "file.el"
Note that this function will error if filename or
extension are empty, or if the filename is shaped like a
directory (i.e., if directory-name-p returns non-nil).
This function returns filename minus its extension, if any. The version/backup part, if present, is only removed if the file has an extension. For example,
(file-name-sans-extension "foo.lose.c")
⇒ "foo.lose"
(file-name-sans-extension "big.hack/foo")
⇒ "big.hack/foo"
(file-name-sans-extension "/my/home/.emacs")
⇒ "/my/home/.emacs"
(file-name-sans-extension "/my/home/.emacs.el")
⇒ "/my/home/.emacs"
(file-name-sans-extension "~/foo.el.~3~")
⇒ "~/foo"
(file-name-sans-extension "~/foo.~3~")
⇒ "~/foo.~3~"
Note that the ‘.~3~’ in the two last examples is the backup part, not an extension.
This function is the composition of file-name-sans-extension
and file-name-nondirectory. For example,
(file-name-base "/my/home/foo.c")
⇒ "foo"
This function splits a file name into its components, and can be
thought of as the inverse of string-join with the appropriate
directory separator. For example,
(file-name-split "/tmp/foo.txt")
⇒ ("" "tmp" "foo.txt")
(string-join (file-name-split "/tmp/foo.txt") "/")
⇒ "/tmp/foo.txt"
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 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 relative file name. On GNU and other POSIX-like systems, after any leading ‘~’ has been expanded, an absolute file name starts with a ‘/’ (see abbreviate-file-name), 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 ‘x:/’, where x is the drive letter.
This function returns t if file filename is an absolute
file name, nil otherwise. A file name is considered to be
absolute if its first component is ‘~’, or is ‘~user’
where user is a valid login name. In the following examples,
assume that there is a user named ‘rms’ but no user named
‘nosuchuser’.
(file-name-absolute-p "~rms/foo")
⇒ t
(file-name-absolute-p "~nosuchuser/foo")
⇒ nil
(file-name-absolute-p "rms/foo")
⇒ nil
(file-name-absolute-p "/user/rms/foo")
⇒ t
Given a possibly relative file name, you can expand any
leading ‘~’ and convert the result to an
absolute name using expand-file-name (see Functions that Expand Filenames). This function converts absolute file names to relative
names:
This function tries to return a relative name that is equivalent to
filename, assuming the result will be interpreted relative to
directory (an absolute directory name or directory file name).
If directory is omitted or 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, filename has no relative equivalent based
on directory if they start with two different device names. In
this case, file-relative-name returns filename in absolute
form.
(file-relative-name "/foo/bar" "/foo/")
⇒ "bar"
(file-relative-name "/foo/bar" "/hack/")
⇒ "../foo/bar"
A file name that is an empty string stands for the current buffer’s default directory.
A directory name is a string that must name a directory if it names any file at all. A directory is actually a kind of file, and it has a file name (called the directory file name), which is related to the directory name but is typically not identical. (This is not quite the same as the usual POSIX terminology.) These two names for the same entity are related by a syntactic transformation. On GNU and other POSIX-like systems, this is simple: to obtain a directory name, append a ‘/’ to a directory file name that does not already end in ‘/’. On MS-DOS the relationship is more complicated.
The difference between a directory name and a directory file name is
subtle but crucial. When an Emacs variable or function argument is
described as being a directory name, a directory file name is not
acceptable. When file-name-directory returns a string, that is
always a directory name.
The following two functions convert between directory names and directory file names. They do nothing special with environment variable substitutions such as ‘$HOME’, and the constructs ‘~’, ‘.’ and ‘..’.
This function returns a string representing filename in a form that the operating system will interpret as the name of a directory (a directory name). On most systems, this means appending a slash to the string (if it does not already end in one).
(file-name-as-directory "~rms/lewis")
⇒ "~rms/lewis/"
This function returns non-nil if filename ends with a
directory separator character. This is the forward slash ‘/’ on
GNU and other POSIX-like systems; MS-Windows and MS-DOS recognize both
the forward slash and the backslash ‘\’ as directory separators.
This function returns a string representing dirname in a form that the operating system will interpret as the name of a file (a directory file name). On most systems, this means removing the final directory separators from the string, unless the string consists entirely of directory separators.
(directory-file-name "~lewis/")
⇒ "~lewis"
Concatenate components to directory, inserting a slash before the components if directory or the preceding component didn’t end with a slash.
(file-name-concat "/tmp" "foo")
⇒ "/tmp/foo"
A directory or components that are nil or the empty
string are ignored—they are filtered out first and do not affect the
results in any way.
This is almost the same as using concat, but dirname (and
the non-final components) may or may not end with slash characters,
and this function will not double those characters.
In most cases, one or more calls to expand-file-name (see Functions that Expand Filenames are better suited for the job of generating file names
with leading directories than this function. Use this function only if
some of the special features of expand-file-name get in the way
of what your program needs to do. For example, the special handling by
expand-file-name of ~, ~user, and nil,
or the removal of . and .. might not be what you want.
To convert a directory name to its abbreviation, use this function:
This function returns an abbreviated form of filename. It
applies the abbreviations specified in directory-abbrev-alist
(see File Aliases in The GNU Emacs Manual),
then substitutes ‘~’ for the user’s home directory if the
argument names a file in the home directory or one of its
subdirectories. If the home directory is a root directory, it is not
replaced with ‘~’, because this does not make the result shorter
on many systems.
You can use this function for directory names and for file names, because it recognizes abbreviations even as part of the name.
This function returns the directory name of the parent directory of
filename. If filename is at the root directory of the
filesystem, it returns nil. A relative filename is
assumed to be relative to default-directory, and the return
value will also be relative in that case. If the return value is
non-nil, it ends in a slash.
Expanding a file name means converting a relative file name to an absolute one. Since this is done relative to a default directory, you must specify the default directory as well as the file name to be expanded. It also involves expanding abbreviations like ~/ (see abbreviate-file-name), and eliminating redundancies like ./ and name/../.
This function converts filename to an absolute file name. If
directory is supplied, it is the default directory to start with
if filename is relative and does not start with ‘~’.
(The value of directory should
itself be an absolute directory name or directory file name; it may
start with ‘~’.) Otherwise, the current buffer’s value of
default-directory is used. For example:
(expand-file-name "foo")
⇒ "/xcssun/users/rms/lewis/foo"
(expand-file-name "../foo")
⇒ "/xcssun/users/rms/foo"
(expand-file-name "foo" "/usr/spool/")
⇒ "/usr/spool/foo"
If the part of filename before the first slash is
‘~’, it expands to your home directory, which is typically
specified by the value of the HOME environment variable
(see General Variables in The GNU Emacs Manual).
If the part before the first
slash is ‘~user’ and if user is a valid login name,
it expands to user’s home directory.
If you do not want this expansion for a relative filename that
might begin with a literal ‘~’, you can use (concat
(file-name-as-directory directory) filename) instead of
(expand-file-name filename directory).
File names containing ‘.’ or ‘..’ are simplified to their canonical form:
(expand-file-name "bar/../foo")
⇒ "/xcssun/users/rms/lewis/foo"
In some cases, a leading ‘..’ component can remain in the output:
(expand-file-name "../home" "/")
⇒ "/../home"
This is for the sake of filesystems that have the concept of a superroot above the root directory /. On other filesystems, /../ is interpreted exactly the same as /.
Expanding . or the empty string returns the default directory:
(expand-file-name "." "/usr/spool/")
⇒ "/usr/spool"
(expand-file-name "" "/usr/spool/")
⇒ "/usr/spool"
Note that expand-file-name does not expand environment
variables; only substitute-in-file-name does that:
(expand-file-name "$HOME/foo")
⇒ "/xcssun/users/rms/lewis/$HOME/foo"
Note also that expand-file-name does not follow symbolic links
at any level. This results in a difference between the way
file-truename and expand-file-name treat ‘..’.
Assuming that ‘/tmp/bar’ is a symbolic link to the directory
‘/tmp/foo/bar’ we get:
(file-truename "/tmp/bar/../myfile")
⇒ "/tmp/foo/myfile"
(expand-file-name "/tmp/bar/../myfile")
⇒ "/tmp/myfile"
If you may need to follow symbolic links preceding ‘..’, you
should make sure to call file-truename without prior direct or
indirect calls to expand-file-name. See Truenames.
The value of this buffer-local variable is the default directory for the current buffer. It should be an absolute directory name; it may start with ‘~’. This variable is buffer-local in every buffer.
expand-file-name uses the default directory when its second
argument is nil.
The value is always a string ending with a slash.
default-directory
⇒ "/user/lewis/manual/"
This function replaces environment variable references in filename with the environment variable values. Following standard Unix shell syntax, ‘$’ is the prefix to substitute an environment variable value. If the input contains ‘$$’, that is converted to ‘$’; this gives the user a way to quote a ‘$’.
The environment variable name is the series of alphanumeric characters (including underscores) that follow the ‘$’. If the character following the ‘$’ is a ‘{’, then the variable name is everything up to the matching ‘}’.
Calling substitute-in-file-name on output produced by
substitute-in-file-name tends to give incorrect results. For
instance, use of ‘$$’ to quote a single ‘$’ won’t work
properly, and ‘$’ 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 ‘$’ characters to prevent subsequent incorrect
results.
Here we assume that the environment variable HOME, which holds
the user’s home directory, has value ‘/xcssun/users/rms’.
(substitute-in-file-name "$HOME/foo")
⇒ "/xcssun/users/rms/foo"
After substitution, if a ‘~’ or a ‘/’ appears immediately after another ‘/’, the function discards everything before it (up through the immediately preceding ‘/’).
(substitute-in-file-name "bar/~/foo")
⇒ "~/foo"
(substitute-in-file-name "/usr/local/$HOME/foo")
⇒ "/xcssun/users/rms/foo"
;; /usr/local/ has been discarded.
Sometimes, it is not desired to expand file names. In such cases, the file name can be quoted to suppress the expansion, and to handle the file name literally. Quoting happens by prefixing the file name with ‘/:’.
This macro adds the quotation prefix ‘/:’ to the file name. For a local file name, it prefixes name with ‘/:’. If name is a remote file name, the local part of name (see Making Certain File Names “Magic”) is quoted. If name is already a quoted file name, name is returned unchanged.
(substitute-in-file-name (file-name-quote "bar/~/foo"))
⇒ "/:bar/~/foo"
(substitute-in-file-name (file-name-quote "/ssh:host:bar/~/foo"))
⇒ "/ssh:host:/:bar/~/foo"
The macro cannot be used to suppress file name handlers from magic file names (see Making Certain File Names “Magic”).
This macro removes the quotation prefix ‘/:’ from the file name, if any. If name is a remote file name, the local part of name is unquoted.
This macro returns non-nil, when name is quoted with the
prefix ‘/:’. If name is a remote file name, the local part
of name is checked.
Some programs need to write temporary files. Here is the usual way to construct a name for such a file:
(make-temp-file name-of-application)
The job of make-temp-file is to prevent two different users or
two different jobs from trying to use the exact same file name.
This function creates a temporary file and returns its name. Emacs
creates the temporary file’s name by adding to prefix some
random characters that are different in each Emacs job. The result is
guaranteed to be a newly created file, containing text if that’s
given as a string and empty otherwise. On MS-DOS, this function can
truncate prefix to fit into the 8+3 file-name limits. If
prefix is a relative file name, it is expanded against
temporary-file-directory.
(make-temp-file "foo")
⇒ "/tmp/foo232J6v"
When 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 dir-flag is non-nil, make-temp-file creates an
empty directory instead of an empty file. It returns the file name,
not the directory name, of that directory. See Directory Names.
If suffix is non-nil, make-temp-file adds it at
the end of the file name.
If text is a string, make-temp-file inserts it in the file.
On Posix systems, Emacs creates the file with permissions that limit its access to the current user.
To prevent conflicts among different libraries running in the same
Emacs, each Lisp program that uses make-temp-file should have its
own prefix. The number added to the end of 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.
The default directory for temporary files is controlled by the
variable temporary-file-directory. This variable gives the user
a uniform way to specify the directory for all temporary files. Some
programs use small-temporary-file-directory instead, if that is
non-nil. To use it, you should expand the prefix against
the proper directory before calling make-temp-file.
This variable specifies the directory name for creating temporary files.
Its value should be a directory name (see Directory Names), but it
is good for Lisp programs to cope if the value is a directory’s file
name instead. Using the value as the second argument to
expand-file-name is a good way to achieve that.
The default value is determined in a reasonable way for your operating
system; it is based on the TMPDIR, TMP and 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 make-temp-file to create the temporary
file, you should still use this variable to decide which directory to
put the file in. However, if you expect the file to be small, you
should use small-temporary-file-directory first if that is
non-nil.
This variable 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:
(make-temp-file
(expand-file-name prefix
(or small-temporary-file-directory
temporary-file-directory)))
This function generates a string that might be a unique file
name. The name starts with base-name, and has several random
characters appended to it, which are different in each Emacs job. It
is like make-temp-file except that (i) it just constructs a
name and does not create a file, (ii) base-name should be an
absolute file name that is not magic, and (iii) if the returned file
name is magic, it might name an existing file. See Making Certain File Names “Magic”.
Warning: In most cases, you should not use this function; use
make-temp-file instead! This function is susceptible to a race
condition, between the make-temp-name call and the creation of
the file, which in some cases may cause a security hole.
Sometimes, it is necessary to create a temporary file on a remote host or a mounted directory. The following two functions support this.
This function is similar to make-temp-file, but it creates a
temporary file as close as possible to default-directory. If
prefix is a relative file name, and default-directory is
a remote file name or located on a mounted file systems, the temporary
file is created in the directory returned by the function
temporary-file-directory. Otherwise, the function
make-temp-file is used. prefix, dir-flag and
suffix have the same meaning as in make-temp-file.
(let ((default-directory "/ssh:remotehost:"))
(make-nearby-temp-file "foo"))
⇒ "/ssh:remotehost:/tmp/foo232J6v"
The directory for writing temporary files via
make-nearby-temp-file. In case of a remote
default-directory, this is a directory for temporary files on
that remote host. If such a directory does not exist, or
default-directory ought to be located on a mounted file system
(see mounted-file-systems), the function returns
default-directory. For a non-remote and non-mounted
default-directory, the value of the variable
temporary-file-directory is returned.
In order to extract the local part of the file’s name of a temporary
file, use file-local-name (see Making Certain File Names “Magic”).
This section describes low-level subroutines for completing a file name. For higher level functions, see Reading File Names.
This function returns a list of all possible completions for a file whose name starts with partial-filename in directory directory. The order of the completions is the order of the files in the directory, which is unpredictable and conveys no useful information.
The argument partial-filename must be a file name containing no directory part and no slash (or backslash on some systems). The current buffer’s default directory is prepended to directory, if directory is not absolute.
In the following example, suppose that ~rms/lewis is the current default directory, and has five files whose names begin with ‘f’: foo, file~, file.c, file.c.~1~, and file.c.~2~.
(file-name-all-completions "f" "")
⇒ ("foo" "file~" "file.c.~2~"
"file.c.~1~" "file.c")
(file-name-all-completions "fo" "")
⇒ ("foo")
This function completes the file name filename in directory
directory. It returns the longest prefix common to all file names
in directory directory that start with filename. If
predicate is non-nil then it ignores possible completions
that don’t satisfy predicate, after calling that function
with one argument, the expanded absolute file name.
If only one match exists and filename matches it exactly, the
function returns t. The function returns nil if directory
directory contains no name starting with filename.
In the following example, suppose that the current default directory has five files whose names begin with ‘f’: foo, file~, file.c, file.c.~1~, and file.c.~2~.
(file-name-completion "fi" "")
⇒ "file"
(file-name-completion "file.c.~1" "")
⇒ "file.c.~1~"
(file-name-completion "file.c.~1~" "")
⇒ t
(file-name-completion "file.c.~3" "")
⇒ nil
file-name-completion usually ignores file names that end in any
string in this list. It does not ignore them when all the possible
completions end in one of these suffixes. This variable has no effect
on file-name-all-completions.
A typical value might look like this:
completion-ignored-extensions
⇒ (".o" ".elc" "~" ".dvi")
If an element of completion-ignored-extensions ends in a slash
‘/’, it signals a directory. The elements which do not end
in a slash will never match a directory; thus, the above value will not
filter out a directory named foo.elc.
Sometimes, an Emacs Lisp program needs to specify a standard file
name for a particular use—typically, to hold configuration data
specified by the current user. Usually, such files should be located
in the directory specified by user-emacs-directory, which is
typically ~/.config/emacs/ or ~/.emacs.d/ by default (see How Emacs Finds Your Init File in The GNU Emacs Manual).
For example, abbrev definitions are stored by default in
~/.config/emacs/abbrev_defs or ~/.emacs.d/abbrev_defs.
The easiest way to specify such a file name is to use the function
locate-user-emacs-file.
This function returns an absolute file name for an Emacs-specific
configuration or data file. The argument base-name should be a
relative file name. The return value is the absolute name of a file
in the directory specified by user-emacs-directory; if that
directory does not exist, this function creates it.
If the optional argument old-name is non-nil, it
specifies a file in the user’s home directory,
~/old-name. If such a file exists, the return value is
the absolute name of that file, instead of the file specified by
base-name. This argument is intended to be used by Emacs
packages to provide backward compatibility. For instance, prior to
the introduction of user-emacs-directory, the abbrev file was
located in ~/.abbrev_defs. Here is the definition of
abbrev-file-name:
(defcustom abbrev-file-name (locate-user-emacs-file "abbrev_defs" ".abbrev_defs") "Default name of file from which to read abbrevs." ... :type 'file)
A lower-level function for standardizing file names, which
locate-user-emacs-file uses as a subroutine, is
convert-standard-filename.
This function returns a file name based on filename, which fits the conventions of the current operating system.
On GNU and other POSIX-like systems, this simply returns filename. On other operating systems, it may enforce system-specific file name conventions; for example, on MS-DOS this function performs a variety of changes to enforce MS-DOS file name limitations, including converting any leading ‘.’ to ‘_’ and truncating to three characters after the ‘.’.
The recommended way to use this function is to specify a name which
fits the conventions of GNU and Unix systems, and pass it to
convert-standard-filename.
A directory is a kind of file that contains other files entered under various names. Directories are a feature of the file system.
Emacs can list the names of the files in a directory as a Lisp list,
or display the names in a buffer using the ls shell command. In
the latter case, it can optionally display information about each file,
depending on the options passed to the ls command.
This function returns a list of the names of the files in the directory directory. By default, the list is in alphabetical order.
If full-name is non-nil, the function returns the files’
absolute file names. Otherwise, it returns the names relative to
the specified directory.
If match-regexp is non-nil, this function returns only
those file names whose non-directory part contain a match for that
regular expression—the other file names are excluded from the list.
On case-insensitive filesystems, the regular expression matching is
case-insensitive.
If nosort is non-nil, directory-files does not sort
the list, so you get the file names in no particular order. Use this if
you want the utmost possible speed and don’t care what order the files
are processed in. If the order of processing is visible to the user,
then the user will probably be happier if you do sort the names.
If count is non-nil, the function will return names of
first count number of files, or names of all files, whichever
occurs first. count has to be an integer greater than zero.
(directory-files "~lewis")
⇒ ("#foo#" "#foo.el#" "." ".."
"dired-mods.el" "files.texi"
"files.texi.~1~")
An error is signaled if directory is not the name of a directory that can be read.
This utility function returns t if given directory is an
accessible directory and it does not contain any files, i.e., is an
empty directory. It will ignore ‘.’ and ‘..’ on systems
that return them as files in a directory.
Symbolic links to directories count as directories. See file-symlink-p to distinguish symlinks.
Return all files under directory whose names match regexp.
This function searches the specified directory and its
sub-directories, recursively, for files whose basenames (i.e., without
the leading directories) match the specified regexp, and returns
a list of the absolute file names of the matching files
(see absolute file names). The file names
are returned in depth-first order, meaning that files in some
sub-directory are returned before the files in its parent directory.
In addition, matching files found in each subdirectory are sorted
alphabetically by their basenames. By default, directories whose
names match regexp are omitted from the list, but if the
optional argument include-directories is non-nil, they
are included.
By default, all subdirectories are descended into. If predicate
is t, errors when trying to descend into a subdirectory (for
instance, if it’s not readable by this user) are ignored. If it’s
neither nil nor t, it should be a function that takes
one parameter (the subdirectory name) and should return non-nil
if the directory is to be descended into.
Symbolic links to subdirectories are not followed by default, but if
follow-symlinks is non-nil, they are followed.
Starting at file, go up the directory tree hierarchy looking for
the first directory where name, a string, exists, and return that
directory. If file is a file, its directory will serve as the
starting point for the search; otherwise file should be a
directory from which to start. The function looks in the starting
directory, then in its parent, then in its parent’s parent, etc.,
until it either finds a directory with name or reaches the root
directory of the filesystem without finding name – in the
latter case the function returns nil.
The argument name can also be a predicate function. The
predicate is called for every directory examined by the function,
starting from file (even if file is not a directory). It
is called with one argument (the file or directory) and should return
non-nil if that directory is the one it is looking for.
This function returns t if file is a file in directory
dir, or in a subdirectory of dir. It also returns
t if file and dir are the same directory. It
compares the truenames of the two directories. If dir does not
name an existing directory, the return value is nil.
This is similar to directory-files in deciding which files
to report on and how to report their names. However, instead
of returning a list of file names, it returns for each file a
list (filename . attributes), where attributes
is what file-attributes returns for that file.
The optional argument id-format has the same meaning as the
corresponding argument to file-attributes (see Definition of file-attributes).
This regular expression matches any file name except ‘.’ and
‘..’. More precisely, it matches parts of any nonempty string
except those two. It is useful as the match-regexp argument to
directory-files and directory-files-and-attributes:
(directory-files "/foo" nil directory-files-no-dot-files-regexp)
returns nil, if directory ‘/foo’ is empty.
This function expands the wildcard pattern pattern, returning a list of file names that match it.
pattern is, by default, a “glob”/wildcard string, e.g.,
‘"/tmp/*.png"’ or ‘"/*/*/foo.png"’, but can also be a
regular expression if the optional regexp parameter is non-nil.
In any case, the matches are applied per sub-directory, so a match
can’t span a parent/sub directory.
If pattern is written as an absolute file name, the values are absolute also.
If 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
full is non-nil, they are absolute.
This function inserts (in the current buffer) a directory listing for
directory file, formatted with ls according to
switches. It leaves point after the inserted text.
switches may be a string of options, or a list of strings
representing individual options.
The argument file may be either a directory or a file
specification including wildcard characters. If wildcard is
non-nil, that means treat file as a file specification with
wildcards.
If full-directory-p is non-nil, that means the directory
listing is expected to show the full contents of a directory. You
should specify t when file is a directory and switches do
not contain ‘-d’. (The ‘-d’ option to ls says to
describe a directory itself as a file, rather than showing its
contents.)
On most systems, this function works by running a directory listing
program whose name is in the variable insert-directory-program.
If wildcard is non-nil, it also runs the shell specified by
shell-file-name, to expand the wildcards.
MS-DOS and MS-Windows systems usually lack the standard Unix program
ls, so this function emulates the standard Unix program ls
with Lisp code.
As a technical detail, when switches contains the long
‘--dired’ option, insert-directory treats it specially,
for the sake of dired. However, the normally equivalent short
‘-D’ option is just passed on to insert-directory-program,
as any other option.
This user option specifies the program to run to generate a directory
listing for the function insert-directory. It is ignored on
systems that generate the listing with Lisp code.
Most Emacs Lisp file-manipulation functions get errors when used on
files that are directories. For example, you cannot delete a directory
with delete-file. These special functions exist to create and
delete directories.
This command creates a directory named dirname. If
parents is non-nil, as is always the case in an
interactive call, that means to create the parent directories first,
if they don’t already exist.
As a function, make-directory returns non-nil if dirname
already exists as a directory and parents is non-nil,
and returns nil if it successfully created dirname.
mkdir is an alias for this.
This command creates an empty file named filename.
As make-directory, this command creates parent directories
if parents is non-nil.
If filename already exists, this command signals an error.
This command copies the directory named dirname to newname. If newname is a directory name, dirname will be copied to a subdirectory there. See Directory Names.
It always sets the file modes of the copied files to match the corresponding original file.
The third argument keep-time non-nil means to preserve the
modification time of the copied files. A prefix arg makes
keep-time non-nil.
The fourth argument parents says whether to create parent directories if they don’t exist. Interactively, this happens by default.
The fifth argument copy-contents, if non-nil, means to
copy the contents of dirname directly into newname if the
latter is a directory name, instead of copying dirname into
it as a subdirectory.
This command deletes the directory named dirname. The function
delete-file does not work for files that are directories; you
must use delete-directory for them. If recursive is
nil, and the directory contains any files,
delete-directory signals an error.
If recursive is non-nil, there is no error merely because the
directory or its files are deleted by some other process before
delete-directory gets to them.
delete-directory only follows symbolic links at the level of
parent directories.
If the optional argument trash is non-nil and the
variable delete-by-moving-to-trash is non-nil, this
command moves the file into the system Trash instead of deleting it.
See Miscellaneous File Operations in The GNU
Emacs Manual. When called interactively, trash is t if
no prefix argument is given, and nil otherwise.
You can implement special handling for certain file names. This is called making those names magic. The principal use for this feature is in implementing access to remote files (see Remote Files in The GNU Emacs Manual).
To define a kind of magic file name, you must supply a regular expression to define the class of names (all those that match the regular expression), plus a handler that implements all the primitive Emacs file operations for file names that match.
The variable file-name-handler-alist holds a list of handlers,
together with regular expressions that determine when to apply each
handler. Each element has this form:
(regexp . handler)
All the Emacs primitives for file access and file name transformation
check the given file name against file-name-handler-alist. If
the file name matches regexp, the primitives handle that file by
calling handler.
The first argument given to handler is the name of the primitive, as a symbol; the remaining arguments are the arguments that were passed to that primitive. (The first of these arguments is most often the file name itself.) For example, if you do this:
(file-exists-p filename)
and filename has handler handler, then handler is called like this:
(funcall handler 'file-exists-p filename)
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:
(expand-file-name filename dirname)
then it checks for a handler for filename and then for a handler for dirname. In either case, the handler is called like this:
(funcall handler 'expand-file-name filename dirname)
The handler then needs to figure out whether to handle filename or 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:
abbreviate-file-name, access-file,
add-name-to-file, byte-compiler-base-file-name,
copy-directory, copy-file,
delete-directory, delete-file,
diff-latest-backup-file,
directory-file-name,
directory-files,
directory-files-and-attributes,
dired-compress-file, dired-uncache,
exec-path, expand-file-name,
file-accessible-directory-p,
file-acl,
file-attributes,
file-directory-p,
file-equal-p,
file-executable-p, file-exists-p,
file-group-gid, file-in-directory-p,
file-local-copy, file-locked-p,
file-modes, file-name-all-completions,
file-name-as-directory,
file-name-case-insensitive-p,
file-name-completion,
file-name-directory,
file-name-nondirectory,
file-name-sans-versions, file-newer-than-file-p,
file-notify-add-watch, file-notify-rm-watch,
file-notify-valid-p,
file-ownership-preserved-p,
file-readable-p, file-regular-p,
file-remote-p, file-selinux-context,
file-symlink-p, file-system-info,
file-truename, file-user-uid,
file-writable-p,
find-backup-file-name,
get-file-buffer,
insert-directory,
insert-file-contents,
list-system-processes,
load, lock-file,
make-auto-save-file-name,
make-directory,
make-lock-file-name,
make-nearby-temp-file,
make-process,
make-symbolic-link,
memory-info, process-attributes, process-file,
rename-file, set-file-acl, set-file-modes,
set-file-selinux-context, set-file-times,
set-visited-file-modtime, shell-command,
start-file-process,
substitute-in-file-name,
temporary-file-directory,
unhandled-file-name-directory,
unlock-file,
vc-registered,
verify-visited-file-modtime,
write-region.
Handlers for insert-file-contents typically need to clear the
buffer’s modified flag, with (set-buffer-modified-p nil), if the
visit argument is non-nil. This also has the effect of
unlocking the buffer if it is locked.
The handler function must handle all of the above operations, and possibly others to be added in the future. It need not implement all these operations itself—when it has nothing special to do for a certain operation, it can reinvoke the primitive, to handle the operation in the usual way. It should always reinvoke the primitive for an operation it does not recognize. Here’s one way to do this:
(defun my-file-handler (operation &rest args) ;; First check for the specific operations ;; that we have special handling for. (cond ((eq operation 'insert-file-contents) ...) ((eq operation 'write-region) ...) ... ;; Handle any operation we don’t know about. (t (let ((inhibit-file-name-handlers (cons 'my-file-handler (and (eq inhibit-file-name-operation operation) inhibit-file-name-handlers))) (inhibit-file-name-operation operation)) (apply operation args)))))
When a handler function decides to call the ordinary Emacs primitive for
the operation at hand, it needs to prevent the primitive from calling
the same handler once again, thus leading to an infinite recursion. The
example above shows how to do this, with the variables
inhibit-file-name-handlers and
inhibit-file-name-operation. Be careful to use them exactly as
shown above; the details are crucial for proper behavior in the case of
multiple handlers, and for operations that have two file names that may
each have handlers.
Handlers that don’t really do anything special for actual access to the
file—such as the ones that implement completion of host names for
remote file names—should have a non-nil safe-magic
property. For instance, Emacs normally protects directory names
it finds in PATH from becoming magic, if they look like magic
file names, by prefixing them with ‘/:’. But if the handler that
would be used for them has a non-nil safe-magic
property, the ‘/:’ is not added.
A file name handler can have an operations property to
declare which operations it handles in a nontrivial way. If this
property has a non-nil value, it should be a list of
operations; then only those operations will call the handler. This
avoids inefficiency, but its main purpose is for autoloaded handler
functions, so that they won’t be loaded except when they have real
work to do.
Simply deferring all operations to the usual primitives does not
work. For instance, if the file name handler applies to
file-exists-p, then it must handle load itself, because
the usual load code won’t work properly in that case. However,
if the handler uses the operations property to say it doesn’t
handle file-exists-p, then it need not handle load
nontrivially.
This variable holds a list of handlers whose use is presently inhibited for a certain operation.
The operation for which certain handlers are presently inhibited.
This function returns the handler function for file name file,
or nil if there is none. The argument operation should
be the operation to be performed on the file—the value you will pass
to the handler as its first argument when you call it. If
operation equals inhibit-file-name-operation, or if it is
not found in the operations property of the handler, this
function returns nil.
This function copies file filename to an ordinary non-magic file
on the local machine, if it isn’t on the local machine already. Magic
file names should handle the file-local-copy operation if they
refer to files on other machines. A magic file name that is used for
other purposes than remote file access should not handle
file-local-copy; then this function will treat the file as
local.
If filename is local, whether magic or not, this function does
nothing and returns nil. Otherwise it returns the file name
of the local copy file.
This function tests whether filename is a remote file. If
filename is local (not remote), the return value is nil.
If filename is indeed remote, the return value is a string that
identifies the remote system.
This identifier string can include a host name and a user name, as
well as characters designating the method used to access the remote
system. For example, the remote identifier string for the file name
/sudo::/some/file is /sudo:root@localhost:.
If file-remote-p returns the same identifier for two different
file names, that means they are stored on the same file system and can
be accessed locally with respect to each other. This means, for
example, that it is possible to start a remote process accessing both
files at the same time. Implementers of file name handlers need to
ensure this principle is valid.
identification specifies which part of the identifier shall be
returned as string. identification can be the symbol
method, user, host or localname; any other
value is handled like nil and means to return the complete
identifier string. In the example above, the remote user
identifier string would be root.
If the remote file does not contain a method, a user name, or a
host name, the respective default value is returned. The string
returned for identification localname can differ depending
on whether there is an existing connection. File name handler specific
implementations could support further identification symbols;
See Tramp, for example, knows also the hop
symbol.
If connected is non-nil, this function returns nil
even if filename is remote, if Emacs has no network connection
to its host. This is useful when you want to avoid the delay of
making connections when they don’t exist. If connected is
never, never use an existing connection to return the
identification, even if one is already present (this is otherwise like
a value of nil). This lets you prevent any connection-specific
logic, such as expanding the local part of the file name.
This function returns the name of a directory that is not magic. For
a non-magic filename it returns the corresponding directory name
(see Directory Names). For a magic filename, it invokes the
file name handler, which therefore decides what value to return. If
filename is not accessible from a local process, then the file
name handler should indicate that by returning nil.
This is useful for running a subprocess; every subprocess must have a non-magic directory to serve as its current directory, and this function is a good way to come up with one.
This function returns the local part of filename. This is the part of the file’s name that identifies it on the remote host, and is typically obtained by removing from the remote file name the parts that specify the remote host and the method of accessing it. For example:
(file-local-name "/ssh:user@host:/foo/bar")
⇒ "/foo/bar"
For a remote filename, this function returns a file name which could be used directly as an argument of a remote process (see Creating an Asynchronous Process, and see Creating a Synchronous Process), and as the program to run on the remote host. If filename is local, this function returns it unchanged.
The attributes of remote files can be cached for better performance. If they are changed outside of Emacs’s control, the cached values become invalid, and must be reread.
When this variable is set to nil, cached values are never
expired. Use this setting with caution, only if you are sure nothing
other than Emacs ever changes the remote files. If it is set to
t, cached values are never used. This is the safest value, but
could result in performance degradation.
A compromise is to set it to a positive number. This means that cached values are used for that amount of seconds since they were cached. If a remote file is checked regularly, it might be a good idea to let-bind this variable to a value less than the time period between consecutive checks. For example:
(defun display-time-file-nonempty-p (file)
(let ((remote-file-name-inhibit-cache
(- display-time-interval 5)))
(and (file-exists-p file)
(< 0 (file-attribute-size
(file-attributes
(file-chase-links file)))))))
The without-remote-files macro evaluates the body forms
with deactivated file name handlers for remote files. Those file
names would be handled literally.
The macro should be used only in forms where it is obvious, that
remote files cannot appear or where it is intended not to handle
remote file names. It also reduces checks with
file-name-handler-alist, resulting in more performant code.
Emacs performs several steps to convert the data in a buffer (text,
text properties, and possibly other information) to and from a
representation suitable for storing into a file. This section describes
the fundamental functions that perform this format conversion,
namely insert-file-contents for reading a file into a buffer,
and write-region for writing a buffer into a file.
The function insert-file-contents:
format-alist; and
after-insert-file-functions.
The function write-region:
write-region-annotate-functions;
format-alist;
This shows the symmetry of the lowest-level operations; reading and writing handle things in opposite order. The rest of this section describes the two facilities surrounding the three variables named above, as well as some related functions. Coding Systems, for details on character encoding and decoding.
The most general of the two facilities is controlled by the variable
format-alist, a list of file format specifications, which
describe textual representations used in files for the data in an Emacs
buffer. The descriptions for reading and writing are paired, which is
why we call this “round-trip” specification
(see Piecemeal Specification, for non-paired specification).
This list contains one format definition for each defined file format. Each format definition is a list of this form:
(name doc-string regexp from-fn to-fn modify mode-fn preserve)
Here is what the elements in a format definition mean:
The name of this format.
A documentation string for the format.
A regular expression which is used to recognize files represented in
this format. If nil, the format is never applied automatically.
A shell command or function to decode data in this format (to convert file data into the usual Emacs data representation).
A shell command is represented as a string; Emacs runs the command as a filter to perform the conversion.
If from-fn is a function, it is called with two arguments, begin and end, which specify the part of the buffer it should convert. It should convert the text by editing it in place. Since this can change the length of the text, from-fn should return the modified end position.
One responsibility of from-fn is to make sure that the beginning of the file no longer matches regexp. Otherwise it is likely to get called again. Also, from-fn must not involve buffers or files other than the one being decoded, otherwise the internal buffer used for formatting might be overwritten.
A shell command or function to encode data in this format—that is, to convert the usual Emacs data representation into this format.
If to-fn is a string, it is a shell command; Emacs runs the command as a filter to perform the conversion.
If to-fn is a function, it is called with three arguments: begin and end, which specify the part of the buffer it should convert, and buffer, which specifies which buffer. There are two ways it can do the conversion:
(position . string), where position is an
integer specifying the relative position in the text to be written, and
string is the annotation to add there. The list must be sorted in
order of position when to-fn returns it.
When write-region actually writes the text from the buffer to the
file, it intermixes the specified annotations at the corresponding
positions. All this takes place without modifying the buffer.
to-fn must not involve buffers or files other than the one being encoded, otherwise the internal buffer used for formatting might be overwritten.
A flag, t if the encoding function modifies the buffer, and
nil if it works by returning a list of annotations.
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.
A flag, t if format-write-file should not remove this format
from buffer-file-format.
The function insert-file-contents automatically recognizes file
formats when it reads the specified file. It checks the text of the
beginning of the file against the regular expressions of the format
definitions, and if it finds a match, it calls the decoding function for
that format. Then it checks all the known formats over again.
It keeps checking them until none of them is applicable.
Visiting a file, with find-file-noselect or the commands that use
it, performs conversion likewise (because it calls
insert-file-contents); it also calls the mode function for each
format that it decodes. It stores a list of the format names in the
buffer-local variable buffer-file-format.
This variable states the format of the visited file. More precisely, this is a list of the file format names that were decoded in the course of visiting the current buffer’s file. It is always buffer-local in all buffers.
When write-region writes data into a file, it first calls the
encoding functions for the formats listed in buffer-file-format,
in the order of appearance in the list.
This command writes the current buffer contents into the file file
in a format based on format, which is a list of format names. It
constructs the actual format starting from format, then appending
any elements from the value of buffer-file-format with a
non-nil preserve flag (see above), if they are not already
present in format. It then updates buffer-file-format with
this format, making it the default for future saves. Except for the
format argument, this command is similar to write-file. In
particular, confirm has the same meaning and interactive treatment
as the corresponding argument to write-file. See Definition of write-file.
This command finds the file file, converting it according to format format. It also makes format the default if the buffer is saved later.
The argument format is a list of format names. If format is
nil, no conversion takes place. Interactively, typing just
RET for format specifies nil.
This command inserts the contents of file file, converting it
according to format format. If beg and end are
non-nil, they specify which part of the file to read, as in
insert-file-contents (see Reading from Files).
The return value is like what insert-file-contents returns: a
list of the absolute file name and the length of the data inserted
(after conversion).
The argument format is a list of format names. If format is
nil, no conversion takes place. Interactively, typing just
RET for format specifies nil.
This variable specifies the format to use for auto-saving. Its value is
a list of format names, just like the value of
buffer-file-format; however, it is used instead of
buffer-file-format for writing auto-save files. If the value
is t, the default, auto-saving uses the same format as a
regular save in the same buffer. This variable is always buffer-local
in all buffers.
In contrast to the round-trip specification described in the previous
subsection (see Round-Trip Specification), you can use the variables
after-insert-file-functions and write-region-annotate-functions
to separately control the respective reading and writing conversions.
Conversion starts with one representation and produces another representation. When there is only one conversion to do, there is no conflict about what to start with. However, when there are multiple conversions involved, conflict may arise when two conversions need to start with the same data.
This situation is best understood in the context of converting text
properties during write-region. For example, the character at
position 42 in a buffer is ‘X’ with a text property foo. If
the conversion for foo is done by inserting into the buffer, say,
‘FOO:’, then that changes the character at position 42 from
‘X’ to ‘F’. The next conversion will start with the wrong
data straight away.
To avoid conflict, cooperative conversions do not modify the buffer,
but instead specify annotations, a list of elements of the form
(position . string), sorted in order of increasing
position.
If there is more than one conversion, write-region merges their
annotations destructively into one sorted list. Later, when the text
from the buffer is actually written to the file, it intermixes the
specified annotations at the corresponding positions. All this takes
place without modifying the buffer.
In contrast, when reading, the annotations intermixed with the text
are handled immediately. insert-file-contents sets point to
the beginning of some text to be converted, then calls the conversion
functions with the length of that text. These functions should always
return with point at the beginning of the inserted text. This
approach makes sense for reading because annotations removed by the
first converter can’t be mistakenly processed by a later converter.
Each conversion function should scan for the annotations it
recognizes, remove the annotation, modify the buffer text (to set a
text property, for example), and return the updated length of the
text, as it stands after those changes. The value returned by one
function becomes the argument to the next function.
A list of functions for write-region to call. Each function in
the list is called with two arguments: the start and end of the region
to be written. These functions should not alter the contents of the
buffer. Instead, they should return annotations.
As a special case, a function may return with a different buffer
current. Emacs takes this to mean that the current buffer contains
altered text to be output. It therefore changes the start and
end arguments of the write-region call, giving them the
values of point-min and point-max in the new buffer,
respectively. It also discards all previous annotations, because they
should have been dealt with by this function.
The value of this variable, if non-nil, should be a function.
This function is called, with no arguments, after write-region
has completed.
If any function in write-region-annotate-functions returns with
a different buffer current, Emacs calls
write-region-post-annotation-function more than once. Emacs
calls it with the last buffer that was current, and again with the
buffer before that, and so on back to the original buffer.
Thus, a function in write-region-annotate-functions can create
a buffer, give this variable the local value of kill-buffer in
that buffer, set up the buffer with altered text, and make the buffer
current. The buffer will be killed after write-region is done.
Each function in this list is called by insert-file-contents
with one argument, the number of characters inserted, and with point
at the beginning of the inserted text. Each function should leave
point unchanged, and return the new character count describing the
inserted text as modified by the function.
We invite users to write Lisp programs to store and retrieve text properties in files, using these hooks, and thus to experiment with various data formats and find good ones. Eventually we hope users will produce good, general extensions we can install in Emacs.
We suggest not trying to handle arbitrary Lisp objects as text property names or values—because a program that general is probably difficult to write, and slow. Instead, choose a set of possible data types that are reasonably flexible, and not too hard to encode.
In MS-Windows versions of Emacs compiled for the Cygwin
environment, you can use the functions
cygwin-convert-file-name-to-windows and
cygwin-convert-file-name-from-windows to convert between the
two file-name syntaxes.
Emacs follows the GNU convention to use the term file name instead of the term pathname. We use the term path only for search paths, which are lists of directory names.