RENAME(S) UNIX System V RENAME(S)
Name
rename - changes filename
Syntax
#include <stdio.h>
int rename (old, new)
const char *old;
const char *new;
Description
The rename function causes the file or directory whose
pathname is the string pointed to by old to be henceforth
known by the pathname given by the string pointed to by new.
The file or directory named old is effectively removed. If
a file or directory named by the string pointed to by new
exists prior to the call to the rename function, new is
removed.
If the old argument and the new argument both refer to links
to the same existing file, the rename() function returns
successfully and performs no other action.
The old and the new arguments must both point to the
pathname of a file or they must both 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 exists throughout the the renaming
operation and refers 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. If
the directory named by the new argument exists, it is
removed and old renamed to new. In this case, a link named
new exists throughout the renaming 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 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 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 of 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, the rename() function marks for
update the st_ctime and st_mtime fields of the parent
directory of each file.
Return Value
The rename function returns zero if the operation succeeds.
A return value of -1 indicates that an error has occurred
and an error code has been stored in errno.
Diagnostics
If any of the following conditions occur, the rename()
function returns -1 and sets errno to the corresponding
value:
[EACCES] A component of either path prefix denies
search permission; or one of the
directories containing old or new denies
write permissions; or, write permission
is required and is denied for a
directory pointed to the the old or new
arguments.
[EBUSY] The directory named by old or new cannot
be renamed because it is being used by
the system or another process and the
implementation considers this to be an
error.
[EEXIST] The link named by new is a directory
containing entries other than dot and
dot-dot.
[ENOTEMPTY] Same as [EEXIST].
[EINVAL] The new directory pathname contains a
path prefix that names the old
directory.
[EISDIR] The new argument points to a directory
and the old argument points to a file
that is not a directory.
[ENAMETOOLONG]
The length of the old or new argument
exceeds {PATH_MAX} or a pathname
component is longer than {NAME_MAX}
while {_POSIX_NO_TRUNC} is in effect.
[ENOENT] The link named by the old argument does
not exist or either old or new points to
an empty string.
[ENOSPC] The directory that would contain new
cannot be extended.
[ENOTDIR] A component of either path prefix is not
a directory; or the old argument names a
directory and the new argument names a
nondirectory file.
[EROFS] The requested operation requires writing
in a directory on a read-only file
system.
[EXDEV] The links named by new and old are on
different file systems and the
implementation does not support links
between file systems.
See Also
link(S), rmdir(S), unlink(S)
Standards Conformance
rename is conformant with:
IEEE POSIX Std 1003.1-1988 with C Standard Language-
Dependent System Support;
and NIST FIPS 151-1.
(printed 6/20/89)