RENAME(2)                            BSD                             RENAME(2)



NAME
     rename - change the name of a file

SYNOPSIS
     #include <stdio.h>
     int rename(from, to)
     const 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
               or to does not exist or either path points to an empty string.

     [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 volumes/devices (file systems).

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

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