NAME
rename - rename a file
SYNOPSIS
#include <stdio.h>
int rename(const char *old, const char *new);
DESCRIPTION
The rename() function shall change the name of a file. The old argument
points to the pathname of the file to be renamed. The new argument
points to the new pathname of the file.
If either the old or new argument names a symbolic link, rename() shall
operate on the symbolic link itself, and shall not resolve the last
component of the argument. If the old argument and the new argument
resolve to the same existing file, rename() shall return successfully
and perform no other action.
If the old argument points to the pathname of a file that is not a
directory, the new argument shall not point to the pathname of a
directory. If the link named by the new argument exists, it shall be
removed and old renamed to new. In this case, a link named new shall
remain visible to other processes throughout the renaming operation and
refer either to the file referred to by new or old before the operation
began. Write access permission is required for both the directory
containing old and the directory containing new.
If the old argument points to the pathname of a directory, the new
argument shall not point to the pathname of a file that is not a
directory. If the directory named by the new argument exists, it shall
be removed and old renamed to new. In this case, a link named new shall
exist throughout the renaming operation and shall refer either to the
directory referred to by new or old before the operation began. If new
names an existing directory, it shall be required to be an empty
directory.
If the old argument points to a pathname of a symbolic link, the
symbolic link shall be renamed. If the new argument points to a
pathname of a symbolic link, the symbolic link shall be removed.
The new pathname shall not contain a path prefix that names old. Write
access permission is required for the directory containing old and the
directory containing new. If the old argument points to the pathname
of a directory, write access permission may be required for the
directory named by old, and, if it exists, the directory named by new.
If the link named by the new 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 rename()
returns, but the removal of the file contents shall be postponed until
all references to the file are closed.
Upon successful completion, rename() shall mark for update the st_ctime
and st_mtime fields of the parent directory of each file.
If the rename() function fails for any reason other than [EIO], any
file named by new shall be unaffected.
RETURN VALUE
Upon successful completion, rename() shall return 0; otherwise, -1
shall be returned, errno shall be set to indicate the error, and
neither the file named by old nor the file named by new shall be
changed or created.
ERRORS
The rename() function shall fail if:
EACCES A component of either path prefix denies search permission; or
one of the directories containing old or new denies write
permissions; or, write permission is required and is denied for
a directory pointed to by the old or new arguments.
EBUSY The directory named by old or new is currently in use by the
system or another process, and the implementation considers this
an error.
EEXIST or ENOTEMPTY
The link named by new is a directory that is not an empty
directory.
EINVAL The new directory pathname contains a path prefix that names the
old directory.
EIO A physical I/O error has occurred.
EISDIR The new argument points to a directory and the old argument
points to a file that is not a directory.
ELOOP A loop exists in symbolic links encountered during resolution of
the path argument.
EMLINK The file named by old is a directory, and the link count of the
parent directory of new would exceed {LINK_MAX}.
ENAMETOOLONG
The length of the old or new argument exceeds {PATH_MAX} or a
pathname component is longer than {NAME_MAX}.
ENOENT The link named by old does not name an existing file, or either
old or new points to an empty string.
ENOSPC The directory that would contain new cannot be extended.
ENOTDIR
A component of either path prefix is not a directory; or the old
argument names a directory and new argument names a non-
directory file.
EPERM or EACCES
The S_ISVTX flag is set on the directory containing the file
referred to by old and the caller is not the file owner, nor is
the caller the directory owner, nor does the caller have
appropriate privileges; or new 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.
EROFS The requested operation requires writing in a directory on a
read-only file system.
EXDEV The links named by new and old are on different file systems and
the implementation does not support links between file systems.
The rename() function may fail if:
EBUSY The file named by the old or new arguments is a named STREAM.
ELOOP More than {SYMLOOP_MAX} symbolic links were encountered during
resolution of the path argument.
ENAMETOOLONG
As a result of encountering a symbolic link in resolution of the
path argument, the length of the substituted pathname string
exceeded {PATH_MAX}.
ETXTBSY
The file to be renamed is a pure procedure (shared text) file
that is being executed.
The following sections are informative.
EXAMPLES
Renaming a File
The following example shows how to rename a file named /home/cnd/mod1
to /home/cnd/mod2.
#include <stdio.h>
int status;
...
status = rename("/home/cnd/mod1", "/home/cnd/mod2");
APPLICATION USAGE
Some implementations mark for update the st_ctime field of renamed
files and some do not. Applications which make use of the st_ctime
field may behave differently with respect to renamed files unless they
are designed to allow for either behavior.
RATIONALE
This rename() 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 new
parameter names a file that already exists. That specification requires
that the action of the function be atomic.
One of the reasons for introducing this function was to have a means of
renaming directories while permitting implementations to prohibit the
use of link() and unlink() with directories, thus constraining links to
directories to those made by mkdir().
The specification that if old and new refer to the same file is
intended to guarantee that:
rename("x", "x");
does not remove the file.
Renaming dot or dot-dot is prohibited in order to prevent cyclical file
system paths.
See also the descriptions of [ENOTEMPTY] and [ENAMETOOLONG] in rmdir()
and [EBUSY] in unlink() . For a discussion of [EXDEV], see link() .
FUTURE DIRECTIONS
None.
SEE ALSO
link() , rmdir() , symlink() , unlink() , the Base Definitions volume
of IEEE Std 1003.1-2001, <stdio.h>
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 .