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
The rename() function changes 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 the old argument and the new argument both refer to, and both link
to the same existing file, rename() returns successfully and performs
no other action.
If the old argument points to the pathname of a file that is not a
directory, the new argument must not point to the pathname of a direc-
tory. If the link named by the new argument exists, it is removed and
old renamed to new. In this case, a link named new will remain visible
to other processes throughout the renaming operation and will refer
either to the file referred to by new or old before the operation
began. Write access permission is required for both the directory con-
taining old and the directory containing new.
If the old argument points to the pathname of a directory, the new
argument must not point to the pathname of a file that is not a direc-
tory. If the directory named by the new argument exists, it will be
removed and old renamed to new. In this case, a link named new will
exist throughout the renaming operation and will refer either to the
file referred to by new or old before the operation began. Thus, if
new names an existing directory, it must be an empty directory.
If old points to a pathname that names a symbolic link, the symbolic
link is renamed. If new points to a pathname that names a symbolic
link, the symbolic link is removed.
The new pathname must 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 direc-
tory 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 will be freed and the file will no longer
be accessible. If one or more processes have the file open when the
last link is removed, the link will be removed before rename()
returns, but the removal of the file contents will be postponed until
all references to the file are closed.
Page 1 Reliant UNIX 5.44 Printed 11/98
rename(2) rename(2)
Upon successful completion, rename() will mark for update the stctime
and stmtime fields of the parent directory of each file.
ERRORS
The following error code descriptions are function-specific. You will
find a general description in introprm2(2) or in errno(5).
EACCES A component of either path prefix denies search permis-
sion; one of the directories containing old or new
denies write permission; or one of the directories
pointed to by old or new denies write permission.
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, or the file named by old or new
is a named stream.
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 direc-
tory has been exhausted.
EEXIST or ENOTEMPTY
The link named by new is a directory containing entries
other than "." and "..".
EFAULT old or new points outside the process' 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 direc-
tory entry.
EISDIR new points to a directory but old points to a file that
is not a directory.
EMLINK The file named by old is a directory, and the link count
of the parent directory of new would exceed LINKMAX.
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.
Page 2 Reliant UNIX 5.44 Printed 11/98
rename(2) rename(2)
ENAMETOOLONG The length of the old or new argument exceeds PATHMAX,
or the length of a component of old or new exceeds
NAMEMAX.
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 a path prefix is not a directory; or the
old parameter names a directory and the new parameter
names a file.
EPERM or EACCES
The SISVTX 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 SISVTX flag is set on the direc-
tory 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 old and new are on different file
systems.
The rename() function may fail if:
ENAMETOOLONG Pathname resolution of a symbolic link produced an
intermediate result whose length exceeds PATHMAX.
ETXTBSY The file to be renamed is a pure procedure (shared text)
file that is being executed.
RESULT
Upon successful completion, a value of 0 is returned. Otherwise, a
value of -1 is returned, errno is set to indicate the error, and nei-
ther old nor new will be changed or created.
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
Page 3 Reliant UNIX 5.44 Printed 11/98
rename(2) rename(2)
to lock both directories for modification. The superuser should
replace hard links to directories by symbolic links.
SEE ALSO
link(2), rmdir(2), symlink(2), unlink(2), stdio(5).
Page 4 Reliant UNIX 5.44 Printed 11/98