rename(2) SYSTEM CALLS rename(2)
NAME
rename - change the name of a file
SYNOPSIS
#include <stdio.h>
int rename(const char *old, const char *new);
DESCRIPTION
rename renames a file. old is a pointer to the pathname of
the file or directory to be renamed. new is a pointer to
the new pathname of the file or directory. Both old and new
must be of the same type (either both files, or both direc-
tories) and must reside on the same file system. If new
already exists, it is removed. Thus, if new names an exist-
ing directory, the directory must not have any entries other
than, possibly, ``.'' and ``..''. When renaming direc-
tories, the new pathname must not name a descendant of old.
The implementation of rename ensures that upon successful
completion a link named new will always exist. If the final
component of old is a symbolic link, the symbolic link is
renamed, not the file or directory to which it points.
Write permission is required for both the directory contain-
ing old and the directory containing new. Furthermore, if
old and new are directories, write permission is required
for the directory named by old, and if it exists, the direc-
tory named by new. rename fails, old is not changed, and no
new file is created if one or more of the following are
true:
EACCES A component of either path prefix denies
search permission; one of the direc-
tories containing old or new denies
write permission; or one of the direc-
tories pointed to by old or new denies
write permission.
EBUSY new is a directory and the mount point
for a mounted file system.
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 contain-
ing the directory has been exhausted.
EEXIST The link named by new is a directory
containing entries other than ``.'' and
``..''.
EFAULT old or new points outside the process's
allocated address space.
1
rename(2) SYSTEM CALLS rename(2)
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 directory entry.
EISDIR new points to a directory but old points
to a file that is not a directory.
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.
ENAMETOOLONG The length of the old or new argument
exceeds {PATHMAX}, or the length of a
old or new component exceeds {NAMEMAX}
while POSIXNOTRUNC 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 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 either path prefix is not
a directory; or the old parameter names
a directory and the new parameter names
a file.
EROFS The requested operation requires writing
in a directory on a read-only file sys-
tem.
EXDEV The links named by old and new are on
different file systems.
DIAGNOSTICS
Upon successful completion, a value of 0 is returned. Oth-
erwise, a value of -1 is returned and errno is set to indi-
cate the error.
2
rename(2) SYSTEM CALLS rename(2)
NOTES
The system can deadlock if there is a loop in the file sys-
tem graph. Such a loop takes the form of an entry in direc-
tory 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 direc-
tory 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 to
lock both directories for modification. The system adminis-
trator should replace hard links to directories by symbolic
links.
SEE ALSO
link(2), unlink(2)
3