rename(2)                                                            rename(2)


NAME
     rename - change the name of a file

SYNOPSIS
     #include <stdio.h>

     int rename(const char *old, const char *new);

DESCRIPTION
     rename renames a file.  old is a pointer to the pathname of the file or
     directory to be renamed.  new is a pointer to the new pathname of the
     file or directory.  Both old and new must be of the same type (either
     both files, or both directories) and must reside on the same file system.

     If new already exists, it is removed.  Thus, if new names an existing
     directory, the directory must not have any entries other than, possibly,
     ``.'' and ``..''.  When renaming directories, the new pathname must not
     name a descendant of old.  The implementation of rename ensures that upon
     successful completion a link named new will always exist.

     If the final component of old is a symbolic link, the symbolic link is
     renamed, not the file or directory to which it points.

     Write permission is required for both the directory containing old and
     the directory containing new.

     rename fails, old is not changed, and no new file is created if one or
     more of the following are true:

     EACCES              A component of either path prefix denies search
                         permission; one of the directories containing old or
                         new denies write permission; one of the directories
                         pointed to by old or new denies write permission; or
                         new exists and write permission is denied on new.

     EBUSY               new is a directory and the mount point for a mounted
                         file system.

     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.

     EEXIST              The link named by new is a directory containing
                         entries other than ``.'' and ``..''.

     EFAULT              old or new points outside the process's allocated
                         address space.

     EINVAL              old is a parent directory of new, or an attempt is
                         made to rename ``.'' or ``..''.


     EINTR               A signal was caught during execution of the rename
                         system call.

     EIO                 An I/O error occurred while making or updating a
                         directory entry.

     EISDIR              new points to a directory but old points to a file
                         that is not a directory.

     ELOOP               Too many symbolic links were encountered in
                         translating old or new.

     EMULTIHOP           Components of pathnames require hopping to multiple
                         remote machines and the file system type does not
                         allow it.

     ENAMETOOLONG        The length of the old or new argument exceeds
                         {PATH_MAX}, or the length of a old or new component
                         exceeds {NAME_MAX} while _POSIX_NO_TRUNC is in
                         effect.

     ENOENT              A component of either old or new does not exist, or
                         the file referred to by either old or new does not
                         exist.

     ENOLINK             Pathnames point to a remote machine and the link to
                         that machine is no longer active.

     ENOSPC              The directory that would contain new is out of space.

     ENOTDIR             A component of either path prefix is not a directory;
                         or the old parameter names a directory and the new
                         parameter names a file.

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

     EXDEV               The links named by old and new are on different file
                         systems.

DIAGNOSTICS
     Upon successful completion, a value of 0 is returned.  Otherwise, a value
     of -1 is returned and errno is set to indicate the error.

NOTES
     The system can deadlock if there is a loop in the file system graph.
     Such a 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.  The system administrator should replace hard links to


     directories by symbolic links.

SEE ALSO
     link(2), unlink(2) chmod(2), open(2).


                                                                        Page 3