Next: , Previous: Information about Files, Up: 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:

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). 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.

— 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. See Miscellaneous File Operations. 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. See 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.

See 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". See 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 (see 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. See 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. See 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. See Extended Attributes.

The function returns t if it successfully sets the ACL of filename, nil otherwise.