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:
file-already-existserror if ok-if-already-exists is
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
replaces it with its (recursive) target.
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.
file-nlinksin 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-fileand then deleting filename has the same effect as renaming, aside from momentary intermediate states.
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,
file-date-errorerror. In an interactive call, a prefix argument specifies a non-
nilvalue for time.
This function copies the file modes, too.
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.
This function is not available on systems that don't support symbolic links.
A suitable kind of
file-errorerror 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 filename is a symbolic link,
delete-filedoes not replace it with its target, but it does follow symbolic links at all levels of parent directories.
delete-directoryin Create/Delete Dirs.
This function sets mode bits of filename to mode (which must be an integer when the function is called non-interactively). Only the low 12 bits of mode are used.
Interactively, mode is read from the minibuffer using
read-file-modes, which accepts mode bits either as a number or as a character string representing the mode bits symbolically. See the description of
read-file-modesbelow for the supported forms of symbolic notation for mode bits.
This function recursively follows symbolic links at all levels for filename.
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-regionwill 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.
This function reads file mode bits from the minibuffer. The optional argument prompt specifies a non-default prompt. 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-numberand 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
0as the base mode bits. The complete and relative specifications can be combined, as in
"u+r,g+rx,o+r,g-w". See , for detailed description of symbolic mode bits specifications.
This subroutine converts a symbolic specification of file mode bits in modes into the equivalent numeric value. 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 zero, i.e. no access rights at all.
This function sets the access and modification times of filename to time. The return value is
tif 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).