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
     nondirectories), 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.

STATUS MESSAGES AND 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.

     The rename command will fail and neither of the files named
     as arguments will be affected if any of the following is
     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
          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 exist.

     EACCES
          A component of either path prefix denies search
          permission.

     ENOENT
          The file named by from does not exist.

     EPERM



January 1992                                                    1

rename(2)                                               rename(2)



          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 systems).

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

     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.

WARNING
     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 with symbolic links by the
     system administrator.

SEE ALSO
     open(2)

     mv(1) in A/UX Command Reference










2                                                    January 1992