RENAME

Section: System Calls (2)
Updated: August 1, 1992
Index Return to Main Contents
 

NAME

rename - change the name of a file  

SYNOPSIS

#include <stdio.h>

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

DESCRIPTION

The rename function causes the link named old to be renamed as new.

If both old and new refer to links to the same file, then rename will return successfully without performing any renaming operation.

Both old and new must refer to files of the same type (that is, both directories or both non-directories), and they must reside on the same file system. If new exists, then it is first removed before old is renamed. Write access is required for the parent directory containing old and the parent directory containing new. If both arguments refer to directories and new exists, then it must contain no entries other than ``.'' and ``..''. The new pathname should not be a descendant of old---that is, the new pathname should not contain a path prefix that names old.

If the final component of old is a symbolic link, then the symbolic link is renamed, not the file or directory to which it points.

The rename function guarantees that an instance of new will always exist, even if the system should crash in the middle of the renaming operation.

If the link count of new becomes zero when it is removed and no process has the file open, then the space occupied by the file is reclaimed by the system. If any process has the file open when the last link is removed, then the link is removed by rename, but the space occupied by the file is not reclaimed until all references to the file have been closed.

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

CAVEAT

The system can deadlock if a loop in the file system graph is present. This loop takes the form of an entry in directory ``a'', say ``a/foo'', being a hard link to directory ``b'', and an entry in directory ``b'', say ``b/bar'', being a hard link to directory ``a''. When such a loop exists and two separate processes attempt to perform ``rename a/foo b/bar'' and ``rename b/bar a/foo'', respectively, the system may deadlock attempting to lock both directories for modification. Hard links to directories should be replaced by symbolic links by the system administrator.  

RETURN VALUE

Upon successful completion, the rename function returns a value of zero. Otherwise, a value of -1 is returned and errno is set to indicate the error.  

ERRORS

If any of the following conditions occurs, rename returns -1 and sets errno to the corresponding value:
[EACCES]
A component of either path prefix denies search permission.
[EACCES]
The requested link requires writing in a directory with a mode that denies write permission.
[EDQUOT]
The directory in which the entry for the new name is being placed cannot be extended because the user's quota of disk blocks on the file system containing the directory has been exhausted.
[EFAULT]
Either old or new points outside the process's allocated address space.
[EINVAL]
Either pathname contains a character with the high-order bit set.
[EINVAL]
The new pathname contains a path prefix that names old, or an attempt is made to rename ``.'' or ``..''.
[EIO]
An I/O error occurred while making or updating a directory entry.
[EISDIR]
The new pathname is a directory, but old is not a directory.
[ELOOP]
Too many symbolic links were encountered in translating either pathname.
[EMLINK]
(POSIX only) The old argument names a directory and the link count of the parent directory of new would exceed {LINK_MAX}.
[ENAMETOOLONG]
A component of path exceeds 255 characters, or the entire pathname exceeds 1023 characters. For POSIX applications these values are given by the constants {NAME_MAX} and {PATH_MAX}, respectively.
[ENOENT]
A component of the old pathname does not exist, or a path prefix of new does not exist.
[ENOENT]
Either old or new points to an empty string.
[ENOSPC]
The directory in which the entry for the new name is being placed cannot be extended because there is no space left on the file system containing the directory.
[ENOTDIR]
A component of either path prefix is not a directory.
[ENOTDIR]
The old pathname is a directory, but new is not a directory.
[ENOTEMPTY]
The new argument names a directory and is not empty.
[EPERM]
The directory containing old is marked sticky, and neither the containing directory nor old are owned by the effective user ID.
[EPERM]
The new file exists, the directory containing new is marked sticky, and neither the containing directory nor new are owned by the effective user ID.
[EROFS]
The requested link requires writing in a directory on a read-only file system.
[EXDEV]
The link named by new and the file named by old are on different logical devices (file systems).
 

SEE ALSO

link(2), open(2), rmdir(2), unlink(2)

 

Index

NAME
SYNOPSIS
DESCRIPTION
CAVEAT
RETURN VALUE
ERRORS
SEE ALSO
This document was created by man2html, using the manual pages.
Time: 17:22:57 GMT, March 25, 2025