rename(2)rename(2)NAMErename - change the name of a file
SYNOPSIS
#include <stdio.h>
int rename(const char *old, const char *new);
DESCRIPTIONrename 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.
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; one of the directories
pointed to by old or new denies write permission; or
new exists and write permission is denied on new.
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 ``..''.
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 ``..''.
Page 1
rename(2)rename(2)
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
{PATH_MAX}, or the length of a old or new component
exceeds {NAME_MAX} while _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 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.
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
Page 2
rename(2)rename(2)
directories by symbolic links.
SEE ALSOlink(2), unlink(2)chmod(2), open(2).
Page 3
