DESCRIPTION

     rename renames a file,  moving  it  between  directories  if
     required.

     Any other hard links to the file (as created using link) are
     unaffected.

     If newpath already exists it  will  be  atomically  replaced
     (subject  to  a  few conditions - see ERRORS below), so that
     there is no point at which  another  process  attempting  to
     access newpath will find it missing.

     If newpath exists but the operation fails for some reason or
     the system crashes rename guarantees to leave an instance of
     newpath in place.

     However, when overwriting there will probably be a window in
     which  both  oldpath  and  newpath  refer  to the file being
     renamed.

     If oldpath refers to a symbolic link the link is renamed; if
     newpath refers to a symbolic link the link will be overwrit-
     ten.

RETURN VALUE

     On success, zero is returned.  On error, -1 is returned, and
     errno is set appropriately.

ERRORS

     EISDIR  newpath is an existing directory, but oldpath is not
             a directory.

     EXDEV   oldpath and newpath are not on the same filesystem.

     ENOTEMPTY
             newpath is a non-empty directory.

     EBUSY   newpath exists and is the current working  directory
             or root directory of some process.

     EEXIST  The new pathname contained a path prefix of the old.

     EINVAL  An attempt was made to make a directory a  subdirec-
             tory of itself.

     EMLINK  oldpath already has the maximum number of  links  to
             it, or it was a directory and the directory contain-
             ing newpath has the maximum number of links.

     ENOTDIR A component  used  as  a  directory  in  oldpath  or
             newpath is not, in fact, a directory.

     EFAULT  oldpath or newpath points  outside  your  accessible
             address space.

     EACCES  Write access to the directory containing oldpath  or
             newpath  is  not allowed for the process's effective
             uid, or one of the directories in oldpath or newpath
             did  not  allow search (execute) permission, or old-
             path was a directory and did not allow write permis-
             sion (needed to update the .. entry).

     EPERM   The directory containing oldpath has the sticky  bit
             set  and  the process's effective uid is neither the
             uid of the file to be deleted nor that of the direc-
             tory  containing  it,  or  the filesystem containing
             pathname does  not  support  renaming  of  the  type
             requested.

     ENAMETOOLONG
             oldpath or newpath was too long.

     ENOENT  A directory component in oldpath  or   newpath  does
             not exist or is a dangling symbolic link.

     ENOMEM  Insufficient kernel memory was available.

     EROFS   The file is on a read-only filesystem.

     ELOOP   Too many symbolic links were encountered in  resolv-
             ing oldpath or newpath.

     ENOSPC  The device containing the file has no room  for  the
             new directory entry.

CONFORMING TO

     POSIX, 4.3BSD, ANSI C

BUGS

     On NFS filesystems, you can not assume that if the operation
     failed  the  file  was  not renamed.  If the server does the
     rename operation and then  crashes,  the  retransmitted  RPC
     which will be processed when the server is up again causes a
     failure.  The application is expected  to  deal  with  this.
     See link(2) for a similar problem.

SEE ALSO

     link(2), unlink(2), symlink(2), mv(1)