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
       replaced 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
       returns -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
                     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  direc-
                     tory 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)

Man(1) output converted with man2html