NAME
rename — change the name of a file
SYNOPSIS
#include <stdio.h>
int rename(const char *source, const char *target);
DESCRIPTION
The
rename()
system call causes the
source
file to be renamed to
target.
If
target
exists, it is first removed.
Both
source
and
target
must be of the same type (that is, either directories or nondirectories),
and must reside on the same file system.
If
target
can be created or if it existed before the call,
rename()
guarantees that an instance of
target
will exist, even if the system crashes in the midst of the operation.
If the final component of
source
is a symbolic link, the symbolic link is renamed,
not the file or directory to which the symbolic link points.
RETURN VALUE
rename()
returns the following values:
- 0
Successful completion.
- -1
Failure.
Neither file is affected.
errno
is set to indicate the error.
ERRORS
If
rename()
fails,
errno
is set to one of the following values.
- [EACCES]
A component of either path prefix denies search permission.
- [EACCES]
The requested link requires writing to a directory without
write permission.
- [EBUSY]
target
or
source
is an existing directory that is the mount point for a mounted file system.
- [EDQUOT]
User's disk quota block or inode limit
has been reached for this file system.
- [EEXIST]
target
is a directory and is not empty.
- [EFAULT]
source
or
target
points outside the allocated address space of the process.
Reliable detection of this error is implementation dependent.
- [EINVAL]
source
is a parent directory of
target,
or an attempt is made to rename the
.
or
..
directory.
- [EISDIR]
target
is a directory, but
source
is not.
- [ELOOP]
Too many symbolic links were encountered in translating either path name.
- [ENAMETOOLONG]
A component of either path name exceeds
NAME_MAX
bytes while
_POSIX_NO_TRUNC
is in effect, or the entire length of either path name exceeds
PATH_MAX
bytes.
- [ENOENT]
A component of the
source
path does not exist, or a path prefix of
target
does not exist.
- [ENOSPC]
The destination directory cannot be extended
because of a lack of space on the file system containing the directory.
- [ENOTDIR]
A component of either path prefix is not a directory.
- [ENOTDIR]
source
is a directory, but
target
is not.
- [EPERM]
The directory containing
source
has the sticky bit set,
and neither the containing directory nor the
source
are owned by the effective user ID.
- [EPERM]
The
target
file exists, the directory containing
target
has the sticky bit set,
and neither the containing directory nor the
target
are owned by the effective user ID.
- [EROFS]
The requested link requires writing in a directory
on a read-only file system.
- [EXDEV]
The paths named by
source
and
target
are on different logical devices (file systems).
AUTHOR
rename()
was developed by the University of California, Berkeley.
STANDARDS CONFORMANCE
rename(): AES, SVID3, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C