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 returns ENOTEMPTY.

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.