RENAME(2) System Calls RENAME(2)

NAME

rename, renameat - change the name of a file

SYNOPSIS

#include <stdio.h>

int rename(const char *old, const char *new);


#include <unistd.h>

int renameat(int fromfd, const char *old, int tofd,
const char *new);


XPG3
#include <unistd.h>

int rename(const char *old, const char *new);

DESCRIPTION

The rename() function changes the name of a file. The old argument
points to the pathname of the file to be renamed. The new argument
points to the new path name of the file.


The renameat() function renames an entry in a directory, possibly
moving the entry into a different directory. See fsattr(7). If the
old argument is an absolute path, the fromfd is ignored. Otherwise
it is resolved relative to the fromfd argument rather than the
current working directory. Similarly, if the new argument is not
absolute, it is resolved relative to the tofd argument. If either
fromfd or tofd have the value AT_FDCWD, defined in <fcntl.h>, and
their respective paths are relative, the path is resolved relative to
the current working directory.


Current implementation restrictions will cause the renameat()
function to return an error if an attempt is made to rename an
extended attribute file to a regular (non-attribute) file, or to
rename a regular file to an extended attribute file.


If old and new both refer to the same existing file, the rename() and
renameat() functions return successfully and performs no other
action.


If old points to the pathname of a file that is not a directory, new
must not point to the pathname of a directory. If the link named by
new exists, it will be removed and old will be renamed to new. In
this case, a link named new must remain visible to other processes
throughout the renaming operation and will refer to either the file
referred to by new or the file referred to as old before the
operation began.


If old points to the pathname of a directory, new must not point to
the pathname of a file that is not a directory. If the directory
named by new exists, it will be removed and old will be renamed to
new. In this case, a link named new will exist throughout the
renaming operation and will refer to either the file referred to by
new or the file referred to as old before the operation began. Thus,
if new names an existing directory, it must be an empty directory.


The new pathname must not contain a path prefix that names old.
Write access permission is required for both the directory containing
old and the directory containing new. If old points to the pathname
of a directory, write access permission is required for the
directory named by old, and, if it exists, the directory named by
new.


If the directory containing old has the sticky bit set, at least one
of the following conditions listed below must be true:

o the user must own old

o the user must own the directory containing old

o old must be writable by the user

o the user must be a privileged user


If new exists, and the directory containing new is writable and has
the sticky bit set, at least one of the following conditions must be
true:

o the user must own new

o the user must own the directory containing new

o new must be writable by the user

o the user must be a privileged user


If the link named by new exists, the file's link count becomes zero
when it is removed, and no process has the file open, then the space
occupied by the file will be freed and the file will no longer be
accessible. If one or more processes have the file open when the last
link is removed, the link will be removed before rename() or
renameat() returns, but the removal of the file contents will be
postponed until all references to the file have been closed.


Upon successful completion, the rename() and renameat() functions
will mark for update the st_ctime and st_mtime fields of the parent
directory of each file.

RETURN VALUES

Upon successful completion, 0 is returned. Otherwise, -1 is returned
and errno is set to indicate an error.

ERRORS

The rename() and renameat() functions will fail if:

EACCES
A component of either path prefix denies search
permission; one of the directories containing old and
new denies write permissions; or write permission is
denied by a directory pointed to by old or new.


EBUSY
The new argument is a directory and the mount point
for a mounted file system.


EDQUOT
The directory where the new name entry is being
placed cannot be extended because the user's quota of
disk blocks on that file system has been exhausted.


EEXIST
The link named by new is a directory containing
entries other than `.' (the directory itself) and
`..' (the parent directory).


EFAULT
Either old or new references an invalid address.


EILSEQ
The path argument includes non-UTF8 characters and
the file system accepts only file names where all
characters are part of the UTF-8 character codeset.


EINVAL
The new argument directory pathname contains a path
prefix that names the old directory, or an attempt
was made to rename a regular file to an extended
attribute or from an extended attribute to a regular
file.


EIO
An I/O error occurred while making or updating a
directory entry.


EISDIR
The new argument points to a directory but old points
to a file that is not a directory.


ELOOP
Too many symbolic links were encountered in
translating the pathname.


ENAMETOOLONG
The length of old or new exceeds PATH_MAX, or a
pathname component is longer than NAME_MAX while
_POSIX_NO_TRUNC is in effect.


EMLINK
The file named by old is a directory, and the link
count of the parent directory of new would exceed
LINK_MAX.


ENOENT
The link named by old does not name an existing file,
a component of the path prefix of new 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 old names a directory and new names a file that is
not a directory, or tofd and dirfd in renameat() do
not reference a directory.


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.


The renameat() function will fail if:

ENOTSUP
An attempt was made to rename a regular file as an
attribute file or to rename an attribute file as a regular
file.

ATTRIBUTES

See attributes(7) for descriptions of the following attributes:


+--------------------+---------------------------------+
| ATTRIBUTE TYPE | ATTRIBUTE VALUE |
+--------------------+---------------------------------+
|Interface Stability | Committed |
+--------------------+---------------------------------+
|MT-Level | Async-Signal-Safe |
+--------------------+---------------------------------+
|Standard | For rename(), see standards(7). |
+--------------------+---------------------------------+

SEE ALSO

chmod(2), link(2), unlink(2), attributes(7), fsattr(7), standards(7)

NOTES

The system can deadlock if there is a loop in the file system graph.
Such a loop can occur if there is an entry in directory a, a/name1,
that is a hard link to directory b, and an entry in directory b,
b/name2, that is a hard link to directory a. When such a loop exists
and two separate processes attempt to rename a/name1 to b/name2 and
b/name2 to a/name1, the system may deadlock attempting to lock both
directories for modification. Use symbolic links instead of hard
links for directories.

September 29, 2020 RENAME(2)