.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved 
.TH "RENAME" 3P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual"
.\" rename 
.SH PROLOG
This manual page is part of the POSIX Programmer's Manual.
The Linux implementation of this interface may differ (consult
the corresponding Linux manual page for details of Linux behavior),
or the interface may not be implemented on Linux.
.SH NAME
rename \- rename a file
.SH SYNOPSIS
.LP
\fB#include <stdio.h>
.br
.sp
int rename(const char *\fP\fIold\fP\fB, const char *\fP\fInew\fP\fB);
.br
\fP
.SH DESCRIPTION
.LP
The \fIrename\fP() function shall change the name of a file. The \fIold\fP
argument points to the pathname of the file to be
renamed. The \fInew\fP argument points to the new pathname of the
file.
.LP
If
either the \fIold\fP or \fInew\fP argument names a symbolic link,
\fIrename\fP() shall operate on the symbolic link itself, and
shall not resolve the last component of the argument. If the \fIold\fP
argument and the \fInew\fP argument resolve to the same
existing file, \fIrename\fP() shall return successfully and perform
no other action.
.LP
If the \fIold\fP argument points to the pathname of a file that is
not a directory, the \fInew\fP argument shall not point to
the pathname of a directory. If the link named by the \fInew\fP argument
exists, it shall be removed and \fIold\fP renamed to
\fInew\fP. In this case, a link named \fInew\fP shall remain visible
to other processes throughout the renaming operation and
refer either to the file referred to by \fInew\fP or \fIold\fP before
the operation began. Write access permission is required
for both the directory containing \fIold\fP and the directory containing
\fInew\fP.
.LP
If the \fIold\fP argument points to the pathname of a directory, the
\fInew\fP argument shall not point to the pathname of a
file that is not a directory. If the directory named by the \fInew\fP
argument exists, it shall be removed and \fIold\fP renamed
to \fInew\fP. In this case, a link named \fInew\fP shall exist throughout
the renaming operation and shall refer either to the
directory referred to by \fInew\fP or \fIold\fP before the operation
began. If \fInew\fP names an existing directory, it shall
be required to be an empty directory.
.LP
If the \fIold\fP argument points to a pathname of a symbolic link,
the symbolic link shall be renamed. If the \fInew\fP
argument points to a pathname of a symbolic link, the symbolic link
shall be removed.
.LP
The \fInew\fP pathname shall not contain a path prefix that names
\fIold\fP. Write access permission is required for the
directory containing \fIold\fP and the directory containing \fInew\fP.
If the \fIold\fP argument points to the pathname of a
directory, write access permission may be required for the directory
named by \fIold\fP, and, if it exists, the directory named by
\fInew\fP.
.LP
If the link named by the \fInew\fP argument exists and the file's
link count becomes 0 when it is removed and no process has
the file open, the space occupied by the file shall be freed and the
file shall no longer be accessible. If one or more processes
have the file open when the last link is removed, the link shall be
removed before \fIrename\fP() returns, but the removal of the
file contents shall be postponed until all references to the file
are closed.
.LP
Upon successful completion, \fIrename\fP() shall mark for update the
\fIst_ctime\fP and \fIst_mtime\fP fields of the parent
directory of each file.
.LP
If the \fIrename\fP() function fails for any reason other than [EIO],
any file named by \fInew\fP shall be unaffected. 
.SH RETURN VALUE
.LP
Upon successful completion, \fIrename\fP() shall return 0; otherwise,
-1 shall be returned,   \fIerrno\fP shall
be set to indicate the error,  and neither the file named by
\fIold\fP nor the file named by \fInew\fP shall be changed or created.
.SH ERRORS
.LP
The \fIrename\fP() function shall fail if:
.TP 7
.B EACCES
A
component of either path prefix denies search permission; or one of
the directories containing \fIold\fP or \fInew\fP denies
write permissions; or, write permission is required and is denied
for a directory pointed to by the \fIold\fP or \fInew\fP
arguments. 
.TP 7
.B EBUSY
The directory named by \fIold\fP or \fInew\fP is currently in use
by the system or another process, and the implementation
considers this an error. 
.TP 7
.B EEXIST \fRor\fP ENOTEMPTY
.sp
The link named by \fInew\fP is a directory that is not an empty directory.
.TP 7
.B EINVAL
The \fInew\fP directory pathname contains a path prefix that names
the \fIold\fP directory. 
.TP 7
.B EIO
A
physical I/O error has occurred. 
.TP 7
.B EISDIR
The \fInew\fP argument points to a directory and the \fIold\fP argument
points to a file that is not a directory. 
.TP 7
.B ELOOP
A
loop exists in symbolic links encountered during resolution of the
\fIpath\fP argument. 
.TP 7
.B EMLINK
The file named by \fIold\fP is a directory, and the link count of
the parent directory of \fInew\fP would exceed {LINK_MAX}. 
.TP 7
.B ENAMETOOLONG
.sp
The length of the \fIold\fP or \fInew\fP argument exceeds {PATH_MAX}
or a pathname component is longer than {NAME_MAX}. 
.TP 7
.B ENOENT
The link named by \fIold\fP does not name an existing file, or either
\fIold\fP or \fInew\fP points to an empty string. 
.TP 7
.B ENOSPC
The directory that would contain \fInew\fP cannot be extended. 
.TP 7
.B ENOTDIR
A
component of either path prefix is not a directory; or the \fIold\fP
argument names a directory and \fInew\fP argument names a
non-directory file. 
.TP 7
.B EPERM \fRor\fP EACCES
.sp
The S_ISVTX flag is set on the directory containing the file referred
to by \fIold\fP and the caller is not the file owner, nor is
the caller the directory owner, nor does the caller have appropriate
privileges; or \fInew\fP refers to an existing file, the
S_ISVTX flag is set on the directory containing this file, and the
caller is not the file owner, nor is the caller the directory
owner, nor does the caller have appropriate privileges. 
.TP 7
.B EROFS
The requested operation requires writing in a directory on a read-only
file system. 
.TP 7
.B EXDEV
The links named by \fInew\fP and \fIold\fP are on different file systems
and the implementation does not support links between
file systems. 
.sp
.LP
The \fIrename\fP() function may fail if:
.TP 7
.B EBUSY
The file named by the \fIold\fP or \fInew\fP arguments is a named
STREAM. 
.TP 7
.B ELOOP
More than {SYMLOOP_MAX} symbolic links were encountered during resolution
of the \fIpath\fP argument. 
.TP 7
.B ENAMETOOLONG
.sp
As a result of encountering a symbolic link in resolution of the \fIpath\fP
argument, the length of the substituted pathname
string exceeded {PATH_MAX}. 
.TP 7
.B ETXTBSY
The file to be renamed is a pure procedure (shared text) file that
is being executed. 
.sp
.LP
\fIThe following sections are informative.\fP
.SH EXAMPLES
.SS Renaming a File
.LP
The following example shows how to rename a file named \fB/home/cnd/mod1\fP
to \fB/home/cnd/mod2\fP.
.sp
.RS
.nf

\fB#include <stdio.h>
.sp

int status;
\&...
status = rename("/home/cnd/mod1", "/home/cnd/mod2");
\fP
.fi
.RE
.SH APPLICATION USAGE
.LP
Some implementations mark for update the \fIst_ctime\fP field of renamed
files and some do not. Applications which make use of
the \fIst_ctime\fP field may behave differently with respect to renamed
files unless they are designed to allow for either
behavior.
.SH RATIONALE
.LP
This \fIrename\fP() function is equivalent for regular files to that
defined by the ISO\ C standard. Its inclusion here
expands that definition to include actions on directories and specifies
behavior when the \fInew\fP parameter names a file that
already exists. That specification requires that the action of the
function be atomic.
.LP
One of the reasons for introducing this function was to have a means
of renaming directories while permitting implementations to
prohibit the use of \fIlink\fP() and \fIunlink\fP()
with directories, thus constraining links to directories to those
made by \fImkdir\fP().
.LP
The specification that if \fIold\fP and \fInew\fP refer to the same
file is intended to guarantee that:
.sp
.RS
.nf

\fBrename("x", "x");
\fP
.fi
.RE
.LP
does not remove the file.
.LP
Renaming dot or dot-dot is prohibited in order to prevent cyclical
file system paths.
.LP
See also the descriptions of [ENOTEMPTY] and [ENAMETOOLONG] in \fIrmdir\fP()
and [EBUSY] in \fIunlink\fP(). For a discussion of [EXDEV], see \fIlink\fP()
\&.
.SH FUTURE DIRECTIONS
.LP
None.
.SH SEE ALSO
.LP
\fIlink\fP(), \fIrmdir\fP(), \fIsymlink\fP(),
\fIunlink\fP(), the Base Definitions volume of IEEE\ Std\ 1003.1-2001,
\fI<stdio.h>\fP
.SH COPYRIGHT
Portions of this text are reprinted and reproduced in electronic form
from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology
-- Portable Operating System Interface (POSIX), The Open Group Base
Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of
Electrical and Electronics Engineers, Inc and The Open Group. In the
event of any discrepancy between this version and the original IEEE and
The Open Group Standard, the original IEEE and The Open Group Standard
is the referee document. The original Standard can be obtained online at
http://www.opengroup.org/unix/online.html .