NAME

rename - rename a file

 SYNOPSIS

#include <stdio.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 pathname of the file.

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

If the old argument points to the pathname of a file that is not a directory, the new argument must not 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 will remain visible to other processes throughout the renaming operation and will refer 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 must 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. In this case, a link named new will exist throughout the renaming operation and will refer either to the file referred to by new or old before the operation began. Thus, if new names an existing directory, it must be an empty directory.

If old points to a pathname that names a symbolic link, the symbolic link is renamed. If new points to a pathname that names a symbolic link, the symbolic link is removed.

The new pathname must not 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 0 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 accessible. 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 are closed.

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

 RETURN VALUE

Upon successful completion, rename() returns 0. Otherwise, -1 is returned, errno is set to indicate the error, and neither the file named by old nor the file named by new will be changed or created.

 ERRORS

The rename() function will fail if:

[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 by the old or new arguments.

[EBUSY]

The directory named by old or new is currently in use by the system or another process, and the implementation considers this an error.

[EEXIST] or [ENOTEMPTY]

The link named by new is a directory that is not an empty directory.

[EINVAL]

The new directory pathname contains a path prefix that names the old directory.

[EIO]

A physical I/O error has occurred.

[EISDIR]

The new argument points to a directory and the old argument points to a file that is not a directory.

[ELOOP]

Too many symbolic links were encountered in resolving either pathname.

[EMLINK]

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

[ENAMETOOLONG]

The length of the old or new argument exceeds {PATH_MAX} or a pathname component is longer than {NAME_MAX}.

[ENOENT]

The link named by old does not name an existing file, 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 new argument names a non-directory file.

[EPERM] or [EACCES]

The S_ISVTX flag is set on the directory containing the file referred to by old and the caller is not the file owner, nor is the caller the directory owner, nor does the caller have appropriate privileges; or new refers to an existing file, the S_ISVTX flag is set on the directory containing this file and the caller is not the file owner, nor is the caller the directory owner, nor does the caller have appropriate privileges.

[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.

The rename() function may fail if:

[EBUSY]

The file named by the old  or new arguments is a named STREAM.

[ENAMETOOLONG]

Pathname resolution of a symbolic link produced an intermediate result whose length exceeds {PATH_MAX}.

[ETXTBSY]

The file to be renamed is a pure procedure (shared text) file that is being executed.

 EXAMPLES

None.

 APPLICATION USAGE

None.

 FUTURE DIRECTIONS

None.

 SEE ALSO

link(), rmdir(), symlink(), unlink(), <stdio.h>.

DERIVATION

Derived from the POSIX.1-1988 standard.