elisp: Changing Files
24.7 Changing File Names and Attributes
=======================================
The functions in this section rename, copy, delete, link, and set the
modes (permissions) of files. They all 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.
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:
• Signal a ‘file-already-exists’ error if OK-IF-ALREADY-EXISTS is
‘nil’.
• Request confirmation if OK-IF-ALREADY-EXISTS is a number.
• Replace the old file without confirmation if OK-IF-ALREADY-EXISTS
is any other value.
The next four commands all recursively follow symbolic links at all
levels of parent directories for their first argument, but, if that
argument is itself a symbolic link, then only ‘copy-file’ replaces it
with its (recursive) target.
-- Command: add-name-to-file oldname newname &optional
ok-if-already-exists
This function gives the file named OLDNAME the additional name
NEWNAME. This means that NEWNAME becomes a new hard link to
OLDNAME.
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.
-- Command: rename-file filename newname &optional ok-if-already-exists
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.
-- Command: copy-file oldname newname &optional ok-if-exists time
preserve-uid-gid preserve-extended-attributes
This command copies the file OLDNAME to NEWNAME. An error is
signaled if OLDNAME does not exist. If NEWNAME names a directory,
it copies OLDNAME into that directory, preserving its final name
component.
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). 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.
-- Command: make-symbolic-link filename newname &optional ok-if-exists
This command makes a symbolic link to FILENAME, named NEWNAME.
This is like the shell command ‘ln -s FILENAME NEWNAME’.
This function is not available on systems that don’t support
symbolic links.
-- Command: delete-file filename &optional trash
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 (though it does follow symbolic links at all levels
of parent directories).
A suitable kind of ‘file-error’ error is signaled if the file does
not exist, or is not deletable. (On Unix and GNU/Linux, a file is
deletable if its directory is writable.)
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.
Miscellaneous File Operations (emacs)Misc File Ops. When called
interactively, TRASH is ‘t’ if no prefix argument is given, and
‘nil’ otherwise.
See also ‘delete-directory’ in Create/Delete Dirs.
-- Command: set-file-modes filename mode
This function sets the “file mode” (or “permissions”) of FILENAME
to MODE. It recursively follows symbolic links at all levels for
FILENAME.
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 #o644)
specifies that the file should be readable and writable for its
owner, readable for group members, and readable for all other
users. (coreutils)File permissions, 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.
File Attributes, for the function ‘file-modes’, which
returns the permissions of a file.
-- Function: set-default-file-modes mode
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 Unix and GNU/Linux,
the default permissions are given by the bitwise complement of the
‘umask’ value.
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.
-- Macro: with-file-modes mode body...
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.
-- Function: default-file-modes
This function returns the default file permissions, as an integer.
-- Function: read-file-modes &optional prompt base-file
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"’.
(coreutils)File permissions, for a description of file mode
specifications.
-- Function: file-modes-symbolic-to-number modes &optional base-modes
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.
-- Function: set-file-times filename &optional time
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 in the format returned by ‘current-time’ (Time of Day).
-- Function: set-file-extended-attributes filename attribute-alist
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’. Extended Attributes.
-- Function: set-file-selinux-context filename context
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. Extended
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).
-- Function: set-file-acl filename acl
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’. Extended Attributes.
The function returns ‘t’ if it successfully sets the ACL of
FILENAME, ‘nil’ otherwise.
Info Catalog
elisp: Information about Files
elisp: Files
elisp: File Names