rename or renameat Subroutine
Purpose
Renames a directory or a file.
Library
Standard C Library (libc.a)
Syntax
#include <stdio.h>const char *FromPath, *ToPath;
int renameat (DirFileDescriptor1, FromPath, DirFileDescriptor2,
ToPath)
int DirFileDescriptor1, DirFileDescriptor2;
const char *FromPath, *ToPath;
Description
The rename and renameat subroutines rename a directory or a file within a file system. The renameat subroutine is equivalent to the rename subroutine if both DirFileDescriptor1 and DirFileDescriptor2 are AT_FDCWD or both the FromPath and ToPath parameters are absolute path names.
To use either subroutine, the calling process must have write and search permission in the parent directories of both the FromPath and ToPath parameters. If either directory pointed at by the DirFileDescriptor1 or DirFileDescriptor2 parameter in the renameat subroutine was opened without the O_SEARCH open flag, the subroutine checks to determine whether directory searches are permitted for that directory using the current permissions of the directory. However, if either directory was opened with the O_SEARCH open flag, the subroutine does not perform the check for that directory. If the path defined in the FromPath parameter is a directory, the calling process must have write and search permission to the FromPath directory as well. If both the FromPath and ToPath parameters refer to the same existing file, both subroutines return successfully and perform no other action.
The components of both the FromPath and ToPath parameters must be of the same type (that is, both directories or both non-directories) and must reside on the same file system. If the ToPath file already exists, it is first removed. Removing it guarantees that a link named ToPath will exist throughout the operation. This link refers to the file named by either the ToPath or FromPath parameter before the operation began.
If the final component of the FromPath parameter is a symbolic link, the symbolic link (not the file or directory to which it points) is renamed. If the ToPath is a symbolic link, the link is destroyed.
If the parent directory of the FromPath parameter has the Sticky bit attribute (described in the <sys/mode.h> file), the calling process must have an effective user ID equal to the owner ID of the FromPath parameter, or to the owner ID of the parent directory of the FromPath parameter.
A user who is not the owner of the file or directory must have root user authority to use the rename subroutine.
If the FromPath and ToPath parameters name directories, the following must be true:
- The directory specified by the FromPath parameter is not an ancestor of ToPath. For example, the FromPath path name must not contain a path prefix that names the directory specified by the ToPath parameter.
- The directory specified in the FromPath parameter must be well-formed. A well-formed directory contains both . (dot) and .. (dot dot) entries. That is, the . (dot) entry in the FromPath directory refers to the same directory as that in the FromPath parameter. The .. (dot dot) entry in the FromPath directory refers to the directory that contains an entry for FromPath.
- The directory specified by the ToPath parameter, if it exists, must be well-formed (as defined previously).
Parameters
| Item | Description |
|---|---|
| DirFileDescriptor1 | Specifies the file descriptor of an open directory. |
| DirFileDescriptor2 | Specifies the file descriptor of an open directory. |
| FromPath | Identifies the file or directory to be renamed. If DirFileDescriptor1 is specified and FromPath is a relative path name, then FromPath is considered relative to the directory specified by DirFileDescriptor1. |
| ToPath | Identifies the new path name of the file or directory to be renamed. If DirFileDescriptor2 is specified and ToPath is a relative path name, then ToPath is considered relative to the directory specified by DirFileDescriptor2. If ToPath is an existing file or empty directory, it is replaced by FromPath. If ToPath specifies a directory that is not empty, the rename subroutine exits with an error. |
Return Values
Upon successful completion, the rename and renameat subroutines return a value of 0. Otherwise, a value of -1 is returned, and the errno global variable is set to indicate the error.
Error Codes
The rename or renameat subroutine is unsuccessful and the file or directory name remains unchanged if one or more of the following are true:
| Item | Description |
|---|---|
| EACCES | Creating the requested link requires writing in a directory mode that denies the process write permission. |
| EBUSY | The directory named by the FromPath or ToPath parameter is currently in use by the system, or the file named by FromPath or ToPath is a named STREAM. |
| EDQUOT | The directory that would contain the path specified by the ToPath parameter cannot be extended because the user's or group's quota of disk blocks on the file system containing the directory is exhausted. |
| EEXIST | The ToPath parameter specifies an existing directory that is not empty. |
| EINVAL | The path specified in the FromPath or ToPath parameter is not a well-formed directory (FromPath is an ancestor of ToPath), or an attempt has been made to rename . (dot) or .. (dot dot). |
| EISDIR | The ToPath parameter names a directory and the FromPath parameter names a non-directory. |
| EMLINK | The FromPath parameter names a directory that is larger than the maximum link count of the parent directory of the ToPath parameter. |
| ENOENT | A component of either path does not exist, the file named by the FromPath parameter does not exist, or a symbolic link was named, but the file to which it refers does not exist. |
| ENOSPC | The directory that would contain the path specified in the ToPath parameter cannot be extended because the file system is out of space. |
| ENOTDIR | The FromPath parameter names a directory and the ToPath parameter names a non-directory. |
| ENOTEMPTY | The ToPath parameter specifies an existing directory that is not empty. |
| EROFS | The requested operation requires writing in a directory on a read-only file system. |
| ETXTBSY | The ToPath parameter names a shared text file that is currently being used. |
| EXDEV | The link named by the ToPath parameter and the file named by the FromPath parameter are on different file systems. |
The renameat subroutine is unsuccessful and the file or directory name remains unchanged if one or more of the following are true:
| Item | Description |
|---|---|
| EACCES | The directory pointed at by the DirFileDescriptor1 or DirFileDescriptor2 parameter was not opened with the O_SEARCH flag and the permissions of the directory do not permit directory searches. |
| EBADF | A Path parameter does not specify an absolute path and the corresponding DirFileDescriptor parameter is neither AT_FDCWD nor a valid file descriptor. |
| ENOTDIR | A Path parameter does not specify an absolute path and the corresponding DirFileDescriptor parameter is neither AT_FDCWD nor a file descriptor associated with a directory. |
If Network File System (NFS) is installed on the system, the rename and renameat subroutines can be unsuccessful if the following is true:
| Item | Description |
|---|---|
| ETIMEDOUT | The connection timed out. |
The rename and renameat subroutines can be unsuccessful for other reasons. See Base Operating System error codes for services that require path-name resolution for a list of additional errors.