RENAME(2)                            SysV                            RENAME(2)



NAME
     rename - change the name of a file

SYNOPSIS
     rename(from, to)
     char *from, *to;

DESCRIPTION
     rename causes the link named from to be renamed with name to.  If a file
     named to existed before the call to rename, it is removed.  Both from and
     to must be objects of the same type (that is, both directories or both
     non-directories), and both must reside on the same file system.

     rename guarantees that an instance of to will always exist, even if the
     system should crash in the middle of the operation.

ERRORS
     rename will fail and neither of the argument files will be affected if
     any of the following are true:

     [ENOTDIR]   A component of either path prefix is not a directory.

     [ENOENT]    A component of either path prefix does not exist.

     [EACCES]    A component of either path prefix denies search permission.

     [ENOENT]    The file named by from does not exist.

     [EPERM]     The file named by from is a directory and the effective user
                 ID is not super-user.

     [EXDEV]     The link named by to and the file named by from are on
                 different logical devices (that is, file systems).  Note that
                 this error code will not be returned if the implementation
                 permits cross-device links.

     [EACCES]    The requested link requires writing in a directory with a
                 mode that denies write permission.

     [EROFS]     The requested link requires writing in a directory on a
                 read-only file system.

     [EFAULT]    from or to points outside the process' allocated address
                 space.

     [EINVAL]    from is a parent directory of to.

NOTES
     The system can deadlock if a "circular link" is present.  A circular link
     occurs when an entry in directory "a" (for example, "a/foo") is a hard
     link to directory "b", and an entry in directory "b" (for example,
     "b/bar") is a hard link to directory "a".  When such a relationship
     exists and two separate processes attempt to perform "rename a/foo b/bar"
     and "rename b/bar a/foo", respectively, the system may deadlock while
     trying to lock both directories for modification.  To prevent this
     problem, a system administrator should replace all hard links to
     directories with symbolic ones.

SEE ALSO
     open(2).

DIAGNOSTICS
     A successful call returns 0.  A failed call returns -1 and sets errno as
     indicated under "Errors."