NAME

rename − change the name of a file

SYNOPSIS

int rename (old, new)
char ∗old, ∗new;

DESCRIPTION

rename causes the link named old to be renamed as new. If new exists, then it is first removed.  Both old and new must be of the same type (that is, both directories or both non-directories), and must reside on the same file system. 

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

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. 

RETURN VALUE

A 0 value is returned if the operation succeeds, otherwise rename returns −1 and the global variable errno indicates the reason for the failure. 

ERRORS

rename will fail and neither of the argument files will be affected if any of the following are true:

­[EACCES] A component of either path prefix denies search permission, or one of the directories containing old or new denies write permissions. 

­[EEXIST] The link named by new is a non-empty directory. 

­[EFAULT] Path points outside the process’s allocated address space. 

­[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 path argument exceeds {PATH_MAX} in length, or a pathname component is longer than {NAME_MAX}  (see pathconf(2)). 

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

­[EPERM] The file named by old is a directory and the effective user ID is not super-user. 

­[EROFS] The requested link requires writing in a directory on a read-only file system. 

­[EXDEV] The link named by to and the file named by from are on different logical devices (file systems).  Note that this error code will not be returned if the implementation permits cross-device links. 

SEE ALSO

open(2)

CX/UX Programmer’s Reference Manual