Manual page for RENAME(2)
rename - 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 ALSO
link(2),
open(2),
rmdir(2),
unlink(2)
Created by unroff & hp-tools.
© somebody (See intro for details). All Rights Reserved.
Last modified 11/5/97
