RENAME(2)RENAME(2)NAMErename - change the name of a file
SYNOPSIS
#include <stdio.h>
int rename(const char *old, const char *new);
DESCRIPTION
The rename function causes the link named old to be renamed as new.
If both old and new refer to links to the same file, then rename will
return successfully without performing any renaming operation.
Both old and new must refer to files of the same type (that is, both
directories or both non-directories), and they must reside on the same
file system. If new exists, then it is first removed before old is
renamed. Write access is required for the parent directory containing
old and the parent directory containing new. If both arguments refer
to directories and new exists, then it must contain no entries other
than “.” and “..”. The new pathname should not be a descendant of old—
that is, the new pathname should not contain a path prefix that names
old.
If the final component of old is a symbolic link, then the symbolic
link is renamed, not the file or directory to which it points.
The rename function guarantees that an instance of new will always
exist, even if the system should crash in the middle of the renaming
operation.
If the link count of new becomes zero when it is removed and no process
has the file open, then the space occupied by the file is reclaimed by
the system. If any process has the file open when the last link is
removed, then the link is removed by rename, but the space occupied by
the file is not reclaimed until all references to the file have been
closed.
Upon successful completion, rename marks for update the st_ctime and
st_mtime fields of the parent directory of each named file.
CAVEAT
The system can deadlock if a loop in the file system graph is present.
This 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. Hard links to directories
should be replaced by symbolic links by the system administrator.
RETURN VALUE
Upon successful completion, the rename function returns a value of
zero. Otherwise, a value of -1 is returned and errno is set to
indicate the error.
ERRORS
If any of the following conditions occurs, rename returns -1 and sets
errno to the corresponding value:
[EACCES] A component of either path prefix denies search
permission.
[EACCES] The requested link requires writing in a directory with
a mode that denies write permission.
[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.
[EFAULT] Either old or new points outside the process's allocated
address space.
[EINVAL] Either pathname contains a character with the high-order
bit set.
[EINVAL] The new pathname contains a path prefix that names old,
or an attempt is made to rename “.” or “..”.
[EIO] An I/O error occurred while making or updating a
directory entry.
[EISDIR] The new pathname is a directory, but old is not a
directory.
[ELOOP] Too many symbolic links were encountered in translating
either pathname.
[EMLINK] (POSIX only) The old argument names a directory and the
link count of the parent directory of new would exceed
{LINK_MAX}.
[ENAMETOOLONG] A component of path exceeds 255 characters, or the
entire pathname exceeds 1023 characters. For POSIX
applications these values are given by the constants
{NAME_MAX} and {PATH_MAX}, respectively.
[ENOENT] A component of the old pathname does not exist, or a
path prefix of new does not exist.
[ENOENT] Either old or new points to an empty string.
[ENOSPC] The directory in which the entry for the new name is
being placed cannot be extended because there is no
space left on the file system containing the directory.
[ENOTDIR] A component of either path prefix is not a directory.
[ENOTDIR] The old pathname is a directory, but new is not a
directory.
[ENOTEMPTY] The new argument names a directory and is not empty.
[EPERM] The directory containing old is marked sticky, and
neither the containing directory nor old are owned by
the effective user ID.
[EPERM] The new file exists, the directory containing new is
marked sticky, and neither the containing directory nor
new are owned by the effective user ID.
[EROFS] The requested link requires writing in a directory on a
read-only file system.
[EXDEV] The link named by new and the file named by old are on
different logical devices (file systems).
SEE ALSOlink(2), open(2), rmdir(2), unlink(2)
August 1, 1992 RENAME(2)
