rename(2)                                               rename(2)



     NAME
          rename - change the name of a file

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

     DESCRIPTION
          rename causes the link named from to be renamed as to.  If
          to exists, then 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 the file will always
          exist, even if the system should crash in the middle of the
          operation.

     CAVEAT
          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 modification.  Hard links to direc-
          tories should be replaced by symbolic links by the system
          administrator.

     RETURN VALUE
          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 files named as arguments
          will be affected if any of the following are true:

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

          [EPERM]      A pathname contains a character with the high-
                       order bit set.

          [ENAMETOOLONG]



     April, 1990                                                     1

     rename(2)                                               rename(2)



                       A component of a pathname exceeded NAME_MAX
                       characters, or an entire pathname exceeded
                       PATH_MAX.

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

          [ENOENT]     A component of either path prefix does not ex-
                       ist.

          [EACCES]     A component of either path prefix denies search
                       permission.

          [ENOENT]     The file named by from does not exist.

          [EPERM]      The file named by from is a directory and the
                       effective user ID is not superuser.

          [EXDEV]      The link named by to and the file named by from
                       are on different logical devices (file sys-
                       tems).

          [EACCES]     The requested link requires writing in a direc-
                       tory with a mode that denies write permission.

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

          [EFAULT]     path points outside the process's allocated ad-
                       dress space.

          [EINVAL]     from is a parent directory of to.

     SEE ALSO
          mv(1), open(2).




















     2                                                     April, 1990