RENAME(2)                            BSD                             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 to.  If a file named to
     already exists, then it is first removed.  Both from and to must be of
     the same type (that is, both directories or both non-directories), and
     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.

     If the final component of from is a symbolic link, the symbolic link is
     renamed, not the file or directory to which it points.

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

     [ENAMETOOLONG]   A component of either pathname exceeded 255 characters,
                      or the entire length of either pathname exceeded 1023
                      characters.

     [ENOENT]         A component of the from path does not exist, or a path
                      prefix of to does not exist.

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

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

     [ELOOP]          Too many symbolic links were encountered in translating
                      either pathname.

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

     [ENOTDIR]        from is a directory, but to is not a directory.

     [EISDIR]         to is a directory, but from is not a directory.

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

     [ENOSPC]         The directory in which the entry for the new name is
                      being placed cannot be extended because there is no
                      space left on the file system containing the directory.

     [EIO]            An I/O error occurred while making or updating a
                      directory entry.

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

     [EFAULT]         Path points outside the process' allocated address

                      space.

     [EINVAL]         from is a parent directory of to, or an attempt is made
                      to rename dot (.) or dot-dot (..).

     [ENOTEMPTY]      to is a directory and is not empty.

SEE ALSO
     open(2)

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

NOTES
     The following errors, not returned under Domain/OS BSD, may be returned
     under other implementations:

     [EINVAL]         Either pathname contains a character with the high-order
                      bit set.

     [EPERM]          The directory containing from is marked "sticky," and
                      neither the containing directory nor from are owned by
                      the effective user ID.

     [EPERM]          The to file exists, the directory containing to is
                      marked "sticky," and neither the containing directory
                      nor to are owned by the effective user ID.

     [EDQUOT]         The directory in which the entry for the new name is
                      being placed cannot be extended because the user's quota
                      of disk blocks on the file system containing the
                      directory has been exhausted.