rename(S)

rename -- changes filename

Syntax

cc . . . -lc

#include <stdio.h>

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

Description

The rename function causes the file or directory whose pathname is the string pointed to by old to be henceforth known by the pathname given by the string pointed to by new. The file or directory named old is effectively removed. If a file or directory named by the string pointed to by new exists prior to the call to the rename function, new is removed.

If the old argument and the new argument both refer to links to the same existing file, the rename function returns successfully and performs no other action.

The old and the new arguments must both point to the pathname of a file or they must both point to the pathname of a directory. If the link named by the new argument exists, it is removed and old renamed to new. In this case, a link named new exists throughout the the renaming operation and refers either to the file referred to by new or old before the operation began. 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 cannot point to the pathname of a file. If the directory named by the new argument exists, it is removed and old renamed to new. In this case, a link named new exists throughout the renaming operation and refers either to the file referred to by new or old before the operation began. Thus, if new names an existing directory, it is required to be an empty directory.

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

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

Upon successful completion, the rename function marks for update the st_ctime and st_mtime fields of the parent directory of each file.

Return value

The rename function returns zero if the operation succeeds. A return value of -1 indicates that an error has occurred and an error code has been stored in errno.

Diagnostics

If any of the following conditions occur, the rename function returns -1 and sets errno to the corresponding value:

[EACCES]: A component of either path prefix denies search permission; or one of the directories containing old or new denies write permissions; or, write permission is required and is denied for a directory pointed to the the old or new arguments.
[EBUSY]: The directory named by old or new cannot be renamed because it is being used by the system or another process and the implementation considers this to be an error.
[EEXIST]: The link named by new is a directory containing entries other than dot and dot-dot.
[ENOTEMPTY]: Same as [EEXIST].
[EINVAL]: The new directory pathname contains a path prefix that names the old directory.
[EISDIR]: The new argument points to a directory and the old argument points to a file that is not a directory.
[ENAMETOOLONG]: The length of the old or new argument exceeds {PATH_MAX} or a pathname component is longer than {NAME_MAX} while {_POSIX_NO_TRUNC} is in effect.
[ENOENT]: The link named by the old argument 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 the old argument names a directory and the new argument names a nondirectory file.
[EROFS]: The requested operation requires writing in a directory on a read-only file system.
[EXDEV]: The links named by new and old are on different file systems and the implementation does not support links between file systems.

Standards conformance

rename is conformant with: