 |
» |
|
|
|
Renames an existing file. Syntax | |
#include <stdio.h>
int rename(const char *old, const char new);
|
Parameters | |
- old
The pathname of the file to be renamed.
- new
The new pathname of the file.
Return Values | |
Upon successful completion, a value of zero will be returned, Otherwise, a value of -1 will be returned and errno will be set to indicate the error. If -1 is returned, neither the filenamed by old nor the filenamed by new, if either exists, will be changed by this function call. 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 pathname of the file. If the old argument and the new argument both refer to links to the same existing file, The rename() function will return successfully and perform no other action. The old and new arguments must be of the same type of file or directory. If the link named by the new argument exists, it will be removed and old renamed to new. Write access permission is required for both the directory containing old and the directory containing new. If the old argument points to the pathname of a directory, the new argument will not point to the pathname of a file that is not a directory. If the directory named by the new argument exists, it will be removed and old renamed to new. Thus, if new names an existing directory, it will be required to be an empty directory. The new pathname should not contain a path prefix that names old. If the link named by the new argument exists and the link count of the file becomes zero when it is removed and no process has the file open, the space occupied by the file will be freed and the file will no longer be accesable. If one or more processes have the file open when the last link is removed, the link will be removed before rename() 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() function will mark for update the st_ctime and st_mtime fields of the parent directory of each file. Errors | |
If an error occurs, errno is set to one of the following values: | EINVAL | CAUSE | More than one of the following three open flags were specified in oflag: O_WRONLY, O_RDONLY, and O_RDWR. | | | ACTION | Specify only one of the open flags in oflag. | | EISDIR | CAUSE | The pathname specifies a directory to be opened. | | | ACTION | Use opendir() to open a directory file. | | EMFILE | CAUSE | The number of open files and directories would exceed {OPEN_MAX}, the limit of opened files per process. | | | ACTION | Reduce the number of files and directories opened by the calling process. | | ENAMETOOLONG | CAUSE | One of the following: The length of the pathname exceeds the {PATH_MAX} limit (defined in the file <limits.h>).
A component of the pathname is longer than {NAME_MAX} (defined in <limits.h>), and {_POSIX_NO_TRUNC} is in effect for that directory.
| | | ACTION | Make sure that both the component's length and the full pathname
length do not exceed the {NAME_MAX} or {PATH_MAX} limits. | | ENOENT | CAUSE | The O_CREAT option is not set, and the named file does not exist; or the O_CREAT option is set, and the pathname does not exist; or pathname points to an empty string. | | | ACTION | Specify a valid pathname. | | ENOSPC | CAUSE | Creation of the file would exceed the disk space limits imposed by the MPE/iX accounting facility, or there is not enough free disk space to create the file. | | | ACTION | Extend accounting limits for the directory in which the file is located, or free up disk space. | | ENOTDIR | CAUSE | A component of the pathname is not a directory. | | | ACTION | Specify a valid pathname. | | ESYSERR | CAUSE | An operating system error has occurred that does not map directly to any of the above errors. | | | ACTION | Examine the MPE/iX error stack for the type of system error. |
See Also | |
close(), creat(), dup(), execl(), execv(), <fcntl.h>, lseek(), read(), <signal.h>, fstat(), stat(), <stat.h>, write(), umask(), POSIX.1 (Section 5.3.1) |
