25.7 Changing File Names and Attributes

The functions in this section rename, copy, delete, link, and set the modes of files.

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.

Function: 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 29 Aug 18 20:32 foo 84302 -rw-rw-rw- 1 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 29 Aug 18 20:32 foo 81908 -rw-rw-rw- 2 rms 29 Aug 18 20:32 foo2 84302 -rw-rw-rw- 1 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 29 Aug 18 20:32 foo 81908 -rw-rw-rw- 3 rms 29 Aug 18 20:32 foo2 81908 -rw-rw-rw- 3 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 25.6.4 Other Information about Files.

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.

In an interactive call, this function prompts for filename and newname in the minibuffer; also, it requests confirmation if newname already exists.

Command: copy-file oldname newname &optional ok-if-exists time

This command copies the file oldname to newname. An error is signaled if oldname does not exist.

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, this function prompts for filename and newname in the minibuffer; also, it requests confirmation if newname already exists.

Command: delete-file filename

This command deletes the file filename, like the shell command `rm filename'. If the file has multiple names, it continues to exist under the other names.

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

See also delete-directory in 25.10 Creating and Deleting Directories.

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

In an interactive call, this function prompts for filename and newname in the minibuffer; also, it requests confirmation if newname already exists.

This function is not available on systems that don't support symbolic links.

Function: define-logical-name varname string

This function defines the logical name name to have the value string. It is available only on VMS.

Function: set-file-modes filename mode

This function sets mode bits of filename to mode (which must be an integer). Only the low 12 bits of mode are used.

Function: set-default-file-modes mode

This function sets the default file protection for new files created by Emacs and its subprocesses. Every file created with Emacs initially has this protection, or a subset of it (write-region will not give a file execute permission even if the default file protection allows execute permission). On Unix and GNU/Linux, the default protection is the bitwise complement of the "umask" value.

The argument mode must be an integer. On most systems, only the low 9 bits of mode are meaningful. You can use the Lisp construct for octal character codes to enter mode; for example,

(set-default-file-modes ?\644)

Saving a modified version of an existing file does not count as creating the file; it preserves the existing file's mode, whatever that is. So the default file protection has no effect.

Function: default-file-modes

This function returns the current default protection value.

On MS-DOS, there is no such thing as an "executable" file mode bit. So Emacs considers a file executable if its name ends in one of the standard executable extensions, such as `.com', `.bat', `.exe', and some others. Files that begin with the Unix-standard `#!' signature, such as shell and Perl scripts, are also considered as executable files. This is reflected in the values returned by file-modes and file-attributes. Directories are also reported with executable bit set, for compatibility with Unix.