66 lines
2.5 KiB
Groff
66 lines
2.5 KiB
Groff
NAME
|
|
rename - change the name of a file
|
|
SYNOPSIS
|
|
rename(from, to)
|
|
char *from, *to;
|
|
|
|
DESCRIPTION
|
|
Rename causes the link named "from" to be renamed as "to". If to
|
|
exists, then it is first removed. Both from and to must be of the
|
|
same type (i.e., both directories or both non-directories), and
|
|
must reside on the same file system. Rename guarantees that an
|
|
instance of to 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. On systems
|
|
with a symbolic link capability, hard links to directories should
|
|
be replaced by symbolic links by the system administrator.
|
|
|
|
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 nothing will change if any of the following
|
|
are true:
|
|
|
|
[ENOTDIR]
|
|
A component of either path prefix is not a directory.
|
|
|
|
[ENOENT]
|
|
A component of either path prefix does not exist.
|
|
|
|
[EACCES]
|
|
A component of either path prefix denies search permission.
|
|
|
|
[ENOENT]
|
|
The file named by from does not exist.
|
|
|
|
[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.
|
|
|
|
[EACCES]
|
|
The requested link requires writing in a directory with a mode
|
|
that denies write permission.
|
|
|
|
[EROFS]
|
|
The requested link requires writing in a directory on a read-
|
|
only file system.
|
|
|
|
[EFAULT]
|
|
Path points outside the process's allocated address space.
|
|
|
|
SEE ALSO
|
|
open(2)
|
|
|