Go to the previous, next section.

Renaming Files

The rename function is used to change a file's name.

Function: int rename (const char *oldname, const char *newname)

The rename function renames the file name oldname with newname. The file formerly accessible under the name oldname is afterward accessible as newname instead. (If the file had any other names aside from oldname, it continues to have those names.)

The directory containing the name newname must be on the same file system as the file (as indicated by the name oldname).

One special case for rename is when oldname and newname are two names for the same file. The consistent way to handle this case is to delete oldname. However, POSIX says that in this case rename does nothing and reports success--which is inconsistent. We don't know what your operating system will do. The GNU system, when completed, will probably do the right thing (delete oldname) unless you explicitly request strict POSIX compatibility "even when it hurts".

If the oldname is not a directory, then any existing file named newname is removed during the renaming operation. However, if newname is the name of a directory, rename fails in this case.

If the oldname is a directory, then either newname must not exist or it must name a directory that is empty. In the latter case, the existing directory named newname is deleted first. The name newname must not specify a subdirectory of the directory oldname which is being renamed.

One useful feature of rename is that the meaning of the name newname changes "atomically" from any previously existing file by that name to its new meaning (the file that was called oldname). There is no instant at which newname is nonexistent "in between" the old meaning and the new meaning.

If rename fails, it returns -1. In addition to the usual file name syntax errors (see section File Name Errors), the following errno error conditions are defined for this function:

EACCES

One of the directories containing newname or oldname refuses write permission; or newname and oldname are directories and write permission is refused for one of them.

EBUSY

A directory named by oldname or newname is being used by the system in a way that prevents the renaming from working. This includes directories that are mount points for filesystems, and directories that are the current working directories of processes.

EEXIST

The directory newname isn't empty.

ENOTEMPTY

The directory newname isn't empty.

EINVAL

The oldname is a directory that contains newname.

EISDIR

The newname names a directory, but the oldname doesn't.

EMLINK

The parent directory of newname would have too many links.

Well-designed file systems never report this error, because they permit more links than your disk could possibly hold. However, you must still take account of the possibility of this error, as it could result from network access to a file system on another machine.

ENOENT

The file named by oldname doesn't exist.

ENOSPC

The directory that would contain newname has no room for another entry, and there is no space left in the file system to expand it.

EROFS

The operation would involve writing to a directory on a read-only file system.

EXDEV

The two file names newname and oldnames are on different file systems.

Go to the previous, next section.