rename(2)
rename --
change the name of a file
Synopsis
#include <stdio.h>
int rename(const char old, const char new);
Description
rename renames a file. old is a pointer to
the pathname of the file or directory to be renamed.
new is a pointer to the new pathname of the file or directory.
Both old and new
must be of the same type (either both files, or both
directories) and must reside on the same file system.
If new already exists, it is removed.
Thus, if new names an existing directory, the directory must
not have any entries other than, possibly, ``.'' and ``..''.
When renaming directories, the new pathname must not name a
descendant of old.
The implementation of rename ensures that upon successful
completion a link named new will always exist.
If the final component of old is a symbolic link, the symbolic
link is renamed, not the file or directory to which it points.
Write permission is required for both the directory containing old
and the directory containing new.
For security reasons,
If the sticky bit is set on the destination directory,
the object being renamed cannot be a symbolic link,
and either the directory or the object being renamed
must be owned by the calling user ID.
If the destination name refers to an existing file, either this
file or the destination directory must be owned by
the calling user ID.
Return values
On success, rename returns 0.
On failure, rename returns -1 and sets errno to identify the error.
In the following conditions, rename fails and sets errno to:
rename fails, old is not changed, and no new
file is created if one or more of the following are true:
EACCES-
A component of either path prefix denies search
permission; one of the directories containing old or new
denies write permission; one of the directories
pointed to by old or new
denies write permission; or
new exists and write permission is denied on new.
EBUSY-
new is a directory and the mount point for a
mounted file system.
EEXIST-
The link named by new
is a directory containing entries other than ``.'' and ``..''.
EFAULT-
old or new points
outside the process's allocated address space.
EINVAL-
old is a parent directory of new,
or an attempt is made to rename ``.'' or ``..''.
EINTR-
A signal was caught during execution of the rename system call.
EIO-
An I/O error occurred while making or updating a
directory entry.
EISDIR-
new points to a directory
but old points to a file that is not a directory.
ELOOP-
Too many symbolic links were encountered in translating
old or new.
EMLINK-
The file named by old is a directory and the link count of the
parent directory of new would exceed {LINK_MAX}.
EMULTIHOP-
Components of pathnames require hopping to multiple remote
machines and the file system type does not allow it.
ENAMETOOLONG-
The length of the old or new argument exceeds {PATH_MAX}, or the
length of a old or new component exceeds {NAME_MAX} while
_POSIX_NO_TRUNC is in effect.
ENOENT-
A component of either old or new does not exist, or the file
referred to by either old or new does not exist.
ENOLINK-
Pathnames point to a remote machine and the link to that
machine is no longer active.
ENOSPC-
The directory that would contain new
is out of space.
ENOTDIR-
A component of either path prefix is not a
directory; or the old parameter names a directory and the new
parameter names a file.
EPERM-
The sticky bit is set on the destination directory,
and the object being renamed is a symbolic link.
The P_OWNER privilege is required to override this restriction.
EPERM-
The sticky bit is set on the destination directory,
and neither the directory nor the object being renamed
is owned by the calling user ID.
The P_OWNER privilege is required to override this restriction.
EROFS-
The requested operation requires writing
in a directory on a read-only file system.
EXDEV-
The links named by old and new
are on different file systems.
Warnings
The system can deadlock if there is a loop in the file system graph.
Such a 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.
The system administrator should replace
hard links to directories
by symbolic links.
References
link(2),
unlink(2)
© 2004 The SCO Group, Inc. All rights reserved.
UnixWare 7 Release 7.1.4 - 25 April 2004