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
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 directories) and must reside on the same
file system.
If new already exists, it is removed. Thus, if new names an existing
directory, the directory must not have any entries other than,
possibly, ``.'' and ``..''. When renaming directories, 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 containing 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 directory 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 directories containing old
or new denies write permission; or one of the
directories 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
containing the directory has been exhausted.
EEXIST The link named by new is a directory containing
entries other than ``.'' and ``..''.
7/91 Page 1
rename(2) rename(2)
EFAULT old or new 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
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 system.
EXDEV The links named by old and new are on different
file systems.
DIAGNOSTICS
Upon successful completion, a value of 0 is returned. Otherwise, a
value of -1 is returned and errno is set to indicate the error.
Page 2 7/91
rename(2) rename(2)
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
to lock both directories for modification. The system administrator
should replace hard links to directories by symbolic links.
SEE ALSO
link(2), unlink(2).
7/91 Page 3