RENAME(2-POSIX) RISC/os Reference Manual RENAME(2-POSIX)
NAME
rename - change the name of a file
SYNOPSIS
int rename(old, new)
char *old, *new;
DESCRIPTION
rename causes the link named old to be renamed as new. If
new exists, then it is first removed. Both old and new must
be of the same type (that is, both directories or both non-
directories), and must reside on the same file system.
rename guarantees that an instance of new will always exist,
even if the system should crash in the middle of the opera-
tion. Write access permission is required for both the
directory containing new and the directory containing old.
If old points to the pathname of a directory, new must also
point to a pathname that is a directory. If the directory
named by new exists, it is removed and old renamed to new.
In this case, a link named new exists throughout the renam-
ing operation and refers either to the file referred to by
new or old before the operation began. Thus, if new names
an existing directory, it is required to be an empty direc-
tory.
The new pathname must not contain a path prefix that names
old. Write access permission is required for the directory
containing old and the directory containing new. If old
points to the pathname of a directory, write access permis-
sion may be required for the directory named by old, and, if
it exists, the directory named by new.
If the link named by new exists and the file's link count
becomes zero when it is removed and no process has the file
open, the space occupied by the file is freed and the file
is no longer accessible. If one or more processes have the
file open when the last link is removed, the link is removed
before rename returns, but the removal of the file contents
is postponed 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
file.
If the final component of old is a symbolic link, the sym-
bolic link is renamed, not the file or directory to which it
points.
Printed 1/15/91 Page 1
RENAME(2-POSIX) RISC/os Reference Manual RENAME(2-POSIX)
CAVEAT
The system can deadlock if a loop in the file system graph
is present. This loop takes the form of an entry in direc-
tory ``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 modifi-
cation. Hard links to directories should be replaced by
symbolic links by the system administrator.
RETURN VALUE
A 0 value is returned if the operation succeeds, otherwise
rename returns -1 and the global variable errno indicates
the reason for the failure.
ERRORS
rename will fail and neither of the argument files will be
affected if any of the following are true:
[ENAMETOOLONG] A component of either pathname exceeded
{NAME_MAX} characters, or the entire
length of either path name exceeded
{PATH_MAX} characters while
{POSIX_NO_TRUNC} was in effect.
[ENOENT] A component of the old path does not
exist, or a path prefix of new does not
exist, or either new or old points to an
empty string.
[EACCES] A component of either path prefix denies
search permission, or the requested link
requires writing in a directory with a
mode that denies write permission.
[EPERM] The directory containing old is marked
sticky, and neither the containing
directory nor old are owned by the
effective user ID, or the new file
exists, the directory containing new is
marked sticky, and neither the contain-
ing directory nor new are owned by the
effective user ID.
[ELOOP] Too many symbolic links were encountered
in translating either pathname.
[ENOTDIR] A component of either path prefix is not
a directory, or old is a directory, but
new is not a directory.
Page 2 Printed 1/15/91
RENAME(2-POSIX) RISC/os Reference Manual RENAME(2-POSIX)
[EISDIR] new is a directory, but old is not a
directory.
[EXDEV] The link named by new and the file named
by old are on different logical devices
(file systems). Note that this error
code will not be returned if the imple-
mentation permits cross-device links.
[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 direc-
tory.
[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 contain-
ing the directory has been exhausted.
[EIO] An I/O error occurred while making or
updating a directory entry.
[EROFS] The requested link requires writing in a
directory on a read-only file system.
[EFAULT] path points outside the process's allo-
cated address space.
[EINVAL] old is a parent directory of new, or an
attempt is made to rename ``.'' or
``..''.
[ENOTEMPTY] new is a directory and is not empty.
[EBUSY] The directory named by new or old cannot
be renamed because it is being used by
the system or another process.
SEE ALSO
open(2).
Printed 1/15/91 Page 3