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

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.
One of the directories used by the old name or the new name is being used by the system and cannot be changed.
The directory was not empty, so cannot be deleted. This code is synonymous with EEXIST, but GNU always returns ENOTEMPTY.
The old name is a directory that contains the new name.
The new name is a directory, but the old name is not.
The parent directory of the new name would contain too many entries if the new name were created.
The old name does not exist.
The directory that would contain the new name has no room for another entry, and cannot be expanded.
The rename operation would involve writing on a read-only file system.
The new name and the old name are on different file systems.