Node:Renaming files at a low level, Previous:Deleting files at a low level, Up:Low-level file routines
Renaming files at a low level
If you want to rename a file, you can use the rename function,
which takes two parameters. The first parameter is a string containing
the old name of the file, and the second is a string containing the new
name. (As with unlink, this function only operates on one of the
names of a file, if the file has hard links. See Deleting files at a low level, for caveats and information on hard links.)
Both the new name and the old name must be on the same file system. Any file in the same directory that has the same name as the new file name will be deleted in the process of renaming the file.
If rename fails, it will return -1. In addition to the usual
file name errors, unlink can set errno to the following
values. (See Usual file name errors, for a list of the usual file
name errors.)
EACCES- Either one of the directories in question (either the one containing the
old name or the one containing the new name) refuses write permission,
or the new name and the old name are directories, and write permission
is refused for at least one of them.
EBUSY- One of the directories used by the old name or the new name is being used
by the system and cannot be changed.
ENOTEMPTY- The directory was not empty, so cannot be deleted. This code is synonymous
with
EEXIST, but GNU always returnsENOTEMPTY. EINVAL- The old name is a directory that contains the new name.
EISDIR- The new name is a directory, but the old name is not.
EMLINK- The parent directory of the new name would contain too many entries
if the new name were created.
ENOENT- The old name does not exist.
ENOSPC- The directory that would contain the new name has no room for another entry,
and cannot be expanded.
EROFS- The rename operation would involve writing on a read-only file system.
EXDEV- The new name and the old name are on different file systems.