RENAME(2) SysV RENAME(2)
NAME
rename - Rename a directory or a file within a file system
SYNOPSIS
#include <stdio.h>
int rename (old, new)
const char *old;
const char *new;
DESCRIPTION
The rename function renames a directory or a file within a file system.
The old argument identifies the file or directory to be renamed.
If the old argument and the new argument both refer to and 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
directory. If the link named by the new argument exists, it is removed
and old renamed to new. In this case, a link named new must 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
containing old and the directory containing new.
If the old argument points to the pathname of a directory, the new
argument cannot point to the pathname of a file that is not a directory.
If the directory named by the new argument exists, it will be removed and
the old renameed 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 will be required to be an empty directory.
The new pathname cannot 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 directory
named by old and if it exists, the directory named by new.
If the link named by the new argument exists, the files link count
becomes zero when it is removed, and no process has the file open, then
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 have been closed.
If the final component of the old argument is a symbolic link, the
symbolic link (not the file or directory to which it points) is renamed.
If the final component of the new argument is a symbolic link, the
symbolic link is replaced.
Upon successful completion, the rename function marks the st_ctime and
st_mtime fields of the parent directory of each file for update.
DIAGNOSTICS
Upon successful completion, the rename function returns a value of 0
(zero). Otherwise, a value of -1 is returned, and errno is set to
indicate the error. If -1 is returned, neither the file named by old or
the file named by new, if either exists, is changed by rename.
ERRORS
If the rename function fails, the file or directory name remains
unchanged and errno is set to one of the following values:
[ENOTDIR] The old argument names a directory and the new parameter names
a nondirectory or a component of either path prefix is not a
directory.
[EISDIR] The new argument names a directory and the old argument names a
nondirectory.
[ENOENT] A component of the old does not exist, or a path prefix or new
does not exist or path points to an empty string.
[EACCES] Creating the requested link requires writing in a directory
with a mode that denies write permission, or write permission
is required and denied for a directory pointed to by the old or
new argument, or a component of either pathname denies search
permission.
[EXDEV] The link named by the new argument and the file named by the
old argument are on different file systems.
[EBUSY] The directory named by the old or new argument is currently in
use by the system or by another process.
[EINVAL] the old argument is an ancestor of the new argument.
[EROFS] The requested operation requires writing in a directory on a
read-only file system.
[EEXIST] The new argument is an existing nonempty directory.
[ENOSPC] The directory that would contain new cannot be extended because
the file system is out of space.
[EFAULT] Either the to or from argument is an invalid address.
[ENAMETOOLONG]
The length of the new or old arguments exceeds PATH_MAX or a
pathname component is longer than NAME_MAX.
[EPERM] The file named by old is a directory.
[EMLINK] The number of links to the file named by path1 would exceed
LINK_MAX.
[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.
NOTES
The system can deadlock if a "circular link" is present. A circular link
occurs when an entry in directory "a" (for example, "a/foo") is a hard
link to directory "b", and an entry in directory "b" (for example,
"b/bar") is a hard link to directory "a". When such a relationship
exists and two separate processes attempt to perform "rename a/foo b/bar"
and "rename b/bar a/foo", respectively, the system may deadlock while
trying to lock both directories for modification. To prevent this
problem, a system administrator should replace all hard links to
directories with symbolic ones.
SEE ALSO
chmod(2), link(2), mkdir(2), open(2), rmdir(2), unlink(2), <stdio.h>
chmod(1), mkdir(1), mv(1), mvdir(1)