usr/man/cat2/rename.0



RENAME(2)           UNIX Programmer's Manual            RENAME(2)


N\bNA\bAM\bME\bE
     rename - change the name of a file

S\bSY\bYN\bNO\bOP\bPS\bSI\bIS\bS
     r\bre\ben\bna\bam\bme\be(\b(f\bfr\bro\bom\bm,\b, t\bto\bo)\b)
     c\bch\bha\bar\br *\b*f\bfr\bro\bom\bm,\b, *\b*t\bto\bo;\b;

D\bDE\bES\bSC\bCR\bRI\bIP\bPT\bTI\bIO\bON\bN
     _\bR_\be_\bn_\ba_\bm_\be causes the link named _\bf_\br_\bo_\bm to be renamed as _\bt_\bo.  If
     _\bt_\bo exists, then it is first removed.  Both _\bf_\br_\bo_\bm and _\bt_\bo must
     be of the same type (that is, both directories or both non-
     directories), and must reside on the same file system.

     _\bR_\be_\bn_\ba_\bm_\be guarantees that an instance of _\bt_\bo will always exist,
     even if the system should crash in the middle of the opera-
     tion.

     If the final component of _\bf_\br_\bo_\bm is a symbolic link, the sym-
     bolic link is renamed, not the file or directory to which it
     points.

C\bCA\bAV\bVE\bEA\bAT\bT
     The system can deadlock if a loop in the file system graph
     is present.  This loop takes the form of an entry in direc-
     tory "a", say "a/foo", being a hard link to directory "b",
     and an entry in directory "b", say "b/bar", being a hard
     link to directory "a".  When such a loop exists and two
     separate processes attempt to perform "rename a/foo b/bar"
     and "rename b/bar a/foo", respectively, the system may
     deadlock attempting to lock both directories for modifica-
     tion.  Hard links to directories should be replaced by sym-
     bolic links by the system administrator.

R\bRE\bET\bTU\bUR\bRN\bN V\bVA\bAL\bLU\bUE\bE
     A 0 value is returned if the operation succeeds, otherwise
     _\br_\be_\bn_\ba_\bm_\be returns -1 and the global variable _\be_\br_\br_\bn_\bo indicates
     the reason for the failure.

E\bER\bRR\bRO\bOR\bRS\bS
     _\bR_\be_\bn_\ba_\bm_\be will fail and neither of the argument files will be
     affected if any of the following are true:

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

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

     [ENOENT]       A component of the _\bf_\br_\bo_\bm path does not exist,
                    or a path prefix of FIto _\bd_\bo_\be_\bs _\bn_\bo_\bt _\be_\bx_\bi_\bs_\bt.


Printed 7/9/88            May 22, 1986                          1


RENAME(2)           UNIX Programmer's Manual            RENAME(2)


     [_\bE_\bA_\bC_\bC_\bE_\bS]           A component of either path prefix denies
                    search permission.

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

     [EPERM]        The directory containing _\bf_\br_\bo_\bm is marked
                    sticky, and neither the containing directory
                    nor _\bf_\br_\bo_\bm are owned by the effective user ID.

     [EPERM]        The _\bt_\bo file exists, the directory containing
                    _\bt_\bo is marked sticky, and neither the contain-
                    ing directory nor _\bt_\bo are owned by the effec-
                    tive user ID.

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

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

     [ENOTDIR]      _\bF_\br_\bo_\bm is a directory, but _\bt_\bo is not a direc-
                    tory.

     [EISDIR]       _\bT_\bo is a directory, but _\bf_\br_\bo_\bm is not a direc-
                    tory.

     [EXDEV]        The link named by _\bt_\bo and the file named by
                    _\bf_\br_\bo_\bm 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.

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

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

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

     [EFAULT]       _\bP_\ba_\bt_\bh points outside the process's allocated


Printed 7/9/88            May 22, 1986                          2


RENAME(2)           UNIX Programmer's Manual            RENAME(2)


                    address space.

     [EINVAL]       _\bF_\br_\bo_\bm is a parent directory of _\bt_\bo, or an
                    attempt is made to rename ``.'' or ``..''.

     [ENOTEMPTY]    _\bT_\bo is a directory and is not empty.

S\bSE\bEE\bE A\bAL\bLS\bSO\bO
     open(2)


Printed 7/9/88            May 22, 1986                          3