RENAME(2)

NAME
       rename - change the name or location of a file

SYNOPSIS
       #include <<unistd.h>>

       int rename(const char *oldpath, const char *newpath);

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 overwrit-
       ten (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
       overwritten.

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  filesys-
               tem.

       ENOTEMPTY
               newpath is a non-empty directory.

       EBUSY   newpath  exists  and is the current working direc-
               tory 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 subdi-
               rectory of itself.

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

       ENOTDIR A component used as a directory in oldpath or new-
               path 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 effec-
               tive uid, or one of the directories in oldpath  or
               newpath did not allow search (execute) permission,
               or oldpath was a directory and did not allow write
               permission (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
               directory containing it, or  the  filesystem  con-
               taining  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
               resolving 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 opera-
       tion 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) link(8).