RENAME(2)                        System Calls                        RENAME(2)

NAME

       rename - change the name of a file

SYNOPSIS

       #include <stdio.h>

       int rename (const char *from, const char *to);

DESCRIPTION

       Rename  causes  the link named from to be renamed as to.  If to exists,
       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.

CAVEATS

       The system can deadlock if a loop in the file system graph is  present.
       This loop takes the form of an entry in directory 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 modification.  Hard links to directories should be  re‐
       placed by symbolic links by the system administrator.

       GNO  does not currently support symbolic or multiple hard links, so the
       above paragraph and the final paragraph of the DESCRIPTION section does
       not apply.

RETURN VALUES

       A  0  value is returned if the operation succeeds, otherwise rename re‐
       turns -1 and the global variable errno indicates  the  reason  for  the
       failure.

ERRORS

       Rename will fail and neither of the argument files will be affected if:

              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 from path does not exist,  or  a  path
                     prefix of to does not exist.

              EACCES A  component  of either path prefix denies search permis‐
                     sion.

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

              EPERM  The  directory containing from is marked sticky, and nei‐
                     ther 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.

              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 be‐
                     ing 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 be‐
                     ing 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 updating  a  direc‐
                     tory entry.

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

              EFAULT Path  points  outside  the  process's  allocated  address
                     space.

              EINVAL From  is  a parent directory of to, or an attempt is made
                     to rename .  or ...

              ENOTEMPTY
                     To is a directory and is not empty.

SEE ALSO

       open(2) symlink(7)

STANDARDS

       Rename conforms to IEEE Std 1003.1-1988 (POSIX).



GNO                            15 September 1997                     RENAME(2)