rename(2) rename(2)
NAME
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.
Return Values
On success, rename returns 0. On failure, rename returns -1
and sets errno to identify the error.
Errors
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.
Copyright 1994 Novell, Inc. Page 1
rename(2) rename(2)
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.
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.
Copyright 1994 Novell, Inc. Page 2
rename(2) rename(2)
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.
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.
REFERENCES
link(2), unlink(2)
NOTICES
Warning
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.
Copyright 1994 Novell, Inc. Page 3