'\"macro stdmacro
.if n .pH g2.rename @(#)rename	40.14 of 10/10/89
.\" Copyright 1989 AT&T
.nr X
.if \nX=0 .ds x} rename 2 "" "\&"
.if \nX=1 .ds x} rename 2 ""
.if \nX=2 .ds x} rename 2 "" "\&"
.if \nX=3 .ds x} rename "" "" "\&"
.TH \*(x}
.SH NAME
\f4rename\f1 \- change the name of a file
.SH SYNOPSIS
\f4#include <stdio.h>
.PP
\f4int rename(const char \(**old, const char \(**new);\f1
.SH DESCRIPTION
\f4rename\fP renames a file.  \f2old\f1 is a pointer to
the pathname of the file or directory to be renamed.
\f2new\f1 is a pointer to the new pathname of the file or directory.
Both \f2old\f1 and \f2new\f1
must be of the same type (either both files, or both
directories) and must reside on the same file system.
.P
If \f2new\f1 already exists, it is removed.
Thus, if \f2new\f1 names an existing directory, the directory must
not have any entries other than, possibly, ``\f4.\fP'' and ``\f4..\fP''.
When renaming directories, the \f2new\f1 pathname must not name a
descendant of \f2old\f1.
The implementation of \f4rename\fP ensures that upon successful
completion a link named \f2new\f1 will always exist.
.P
If the final component of \f2old\f1 is a symbolic link, the symbolic
link is renamed, not the file or directory to which it points.
.P
Write permission is required for both the directory containing \f2old\f1
and the directory containing \f2new\f1.
Furthermore, if \f2old\f1 and \f2new\f1 are directories,
write permission is required for the directory
named by \f2old\f1, and if it exists, the directory named by
\f2new\f1.
\f4rename\fP fails, \f2old\f1 is not changed, and no \f2new\f1 
file is created if one or more of the following are true:
.TP 20
\f4EACCES\fP
A component of either path prefix denies search
permission; one of the directories containing \f2old\f1 or \f2new\f1
denies write permission; or one of the directories
pointed to by \f2old\f1 or \f2new\f1
denies write permission.
.TP 20
\f4EBUSY\fP
\f2new\f1 is a directory and the mount point for a
mounted file system.
.TP 20
\f4EDQUOT\fP
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.
.TP 20
\f4EEXIST\fP
The link named by \f2new\f1
is a directory containing entries other than ``\f4.\fP'' and ``\f4..\fP''.
.TP 20
\f4EFAULT\fP
\f2old\f1 or \f2new\f1 points
outside the process's allocated address space.
.TP 20
\f4EINVAL\fP
\f2old\f1 is a parent directory of \f2new\f1,
or an attempt is made to rename ``\f4.\fP'' or ``\f4..\fP''.
.TP 20
\f4EINTR\fP
A signal was caught during execution of the \f4rename\fP system call.
.TP 20
\f4EIO\fP
An I/O error occurred while making or updating a
directory entry.
.TP 20
\f4EISDIR\fP
\f2new\f1 points to a directory
but \f2old\f1 points to a file that is not a directory.
.TP 20
\f4ELOOP\fP
Too many symbolic links were encountered in translating
\f2old\f1 or \f2new\f1.
.TP 20
\f4EMULTIHOP\fP
Components of pathnames require hopping to multiple remote
machines and the file system type does not allow it.
.TP 20
\f4ENAMETOOLONG\fP
The length of the \f2old\f1 or \f2new\f1 argument exceeds {\f4PATH_MAX\f1}, or the
length of a \f2old\f1 or \f2new\f1 component exceeds {\f4NAME_MAX\f1} while
\f4_POSIX_NO_TRUNC\f1 is in effect.
.TP 20
\f4ENOENT\fP
A component of either \f2old\f1 or \f2new\f1 does not exist, or the file 
referred to by either \f2old\f1 or \f2new\f1 does not exist.
.TP 20
\f4ENOLINK\fP
Pathnames point to a remote machine and the link to that
machine is no longer active.
.TP 20
\f4ENOSPC\fP
The directory that would contain \f2new\f1
is out of space.
.TP 20
\f4ENOTDIR\fP
A component of either path prefix is not a
directory; or the \f2old\f1 parameter names a directory and the \f2new\f1
parameter names a file.
.TP 20
\f4EROFS\fP
The requested operation requires writing
in a directory on a read-only file system.
.TP 20
\f4EXDEV\fP
The links named by \f2old\f1 and \f2new\f1
are on different file systems.
.SH DIAGNOSTICS
Upon successful completion, a value of 0 is returned.  Otherwise, a
value of \-1 is returned and \f4errno\fP is set to indicate the
error.
.SH 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 \f2a\f1,
say \f2a/foo\f1, being a hard link to directory \f2b\f1, and an
entry in directory \f2b\f1, say \f2b/bar\f1, being a hard link to
directory \f2a\f1.
When such a loop exists and two separate processes
attempt to perform \f4rename\fP \f2a/foo b/bar\f1 and \f4rename\f1 \f2b/bar a/foo\f1,
respectively, the system may deadlock attempting to lock both
directories for modification.
The system administrator should replace
hard links to directories
by symbolic links.
.SH "SEE ALSO"
\f4link\fP(2), \f4unlink\fP(2)
