renameat(2)
NAME
rename, renameat - change the name of a file
SYNOPSIS
#include <stdio.h>
int rename(const char *old, const char *new);
int renameat(int fromfd, const char *old, int tofd, 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(5). 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 direc-
tory, 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 direc-
tory containing old and the directory containing new. If old
points to the pathname of a directory, write access permis-
sion 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 post-
poned 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() function will fail if:
EACCES
A component of either path prefix denies search per-
mission; 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.
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.
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 translat-
ing the pathname.
ENAMETOOLONG
The length of old or new exceeds PATH_MAX, or a path-
name 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 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 nondirectory
file, or tofd and dirfd in renameat() do not reference
a directory.
EROFS The requested operation requires writing in a direc-
tory on a read-only file system.
EXDEV The links named by old and new are on different file
systems.
EIO An I/O error occurred while making or updating a
directory entry.
The renameat() functions 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.
USAGE
When a UFS file system is mounted with logging enabled, file
system transactions that free blocks from files might not
actually add those freed blocks to the file system's free
list until some unspecified time in the future. This
behavior improves file system performance but does not con-
form to the POSIX, Single UNIX Specification, SPARC Confor-
mance Definition, System V Application Binary Interface,
System V Interface Definition, and X/Open Portability Guide
Standards, which require that freed space be available
immediately. To enable standards conformance regarding file
deletions or to address the problem of not being able to
grow files on a relatively full UFS file system even after
files have been deleted, disable UFS logging (see
mount_ufs(1M).
ATTRIBUTES
See attributes(5) for descriptions of the following attri-
butes:
____________________________________________________________
| ATTRIBUTE TYPE | ATTRIBUTE VALUE |
|_____________________________|_____________________________|
| Interface Stability | See below. |
|_____________________________|_____________________________|
| MT-Level | Async-Signal-Safe |
|_____________________________|_____________________________|
The rename() function is Standard. The renameat() function
is Evolving.
SEE ALSO
mount_ufs(1M), chmod(2), link(2), unlink(2), attributes(5),
fsattr(5)
NOTES
The system can deadlock if there is a loop in the file sys-
tem 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.
Man(1) output converted with
man2html