rename(2P) INTERACTIVE UNIX System (POSIX) rename(2P)
NAME
rename - change the name of a file
SYNOPSIS
int rename (old, new)
char *old;
char *new;
DESCRIPTION
rename() renames the file. The old parameter points to the
path name of the file to be renamed. The new parameter
points to the new path name of the file. Both old and new
must be of the same type (either both directories, or both
non-directories), and must reside on the same file system.
If new exists, then it is first removed. Thus, if new names
an existing directory, the directory must not have any
entries other than, possibly, ``.'' and ``..''. When
renaming directories, the new path name must not name a des-
cendant of old. Implementation of rename() ensures that a
link named new will always exist.
Write permission is required for both the directory contain-
ing old and the directory containing new. If rename() is
applied to a directory, write access permission is also
required for the directory named by old, and if it exists,
the directory named by new.
If the link named by new exists and the file's link count
becomes zero 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 have been closed.
RETURN VALUES
Upon successful completion, a value of 0 is returned. Other-
wise, a value of -1 is returned, and errno is set to indi-
cate the error.
DIAGNOSTICS
rename() will fail, old will not be changed, and no new will
be created if one or more of the following are true:
[EACCES]
A component of either path prefix denies search permis-
sion; or one of the directories containing old or new
denies write permissions; or write permission is denied
by a directory pointed to by the old or new parameters.
[EBUSY]
Rev. 1.1 Page 1
rename(2P) INTERACTIVE UNIX System (POSIX) rename(2P)
The new is a directory and the mount point for a
mounted file system.
[EEXIST]
The link named by new is a directory containing entries
other than ``.'' and ``..''.
[EFAULT]
The old or new parameter 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 system
call.
[EIO]
An I/O error occurred while making or updating a direc-
tory entry.
[EISDIR]
The new parameter points to a directory, but the old
parameter points to a file that is not a directory.
[ELOOP]
Too many symbolic links were encountered in translating
the path name.
[EMULTIHOP]
Components of path names require hopping to multiple
remote machines and file system type does not allow it.
[ENAMETOOLONG]
The length of either the old or new component exceeds
{NAME_MAX}, or the length of old or new exceeds
{PATH_MAX} characters and {_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]
Path names 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]
Rev. 1.1 Page 2
rename(2P) INTERACTIVE UNIX System (POSIX) rename(2P)
A component of either path prefix is not a directory;
or the old parameter names a directory and the new
parameter names a non-directory 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.
SEE ALSO
link(2), rmdir(2), unlink(2).
Rev. 1.1 Page 3