.Sh SYNOPSIS
.Fd #include <stdio.h>
.Ft int
-.Fn rename "const char *from" "const char *to"
+.Fo rename
+.Fa "const char *old"
+.Fa "const char *new"
+.Fc
.Sh DESCRIPTION
-.Fn Rename
-causes the link named
-.Fa from
+The
+.Fn rename
+system call causes the link named
+.Fa old
to be renamed as
-.Fa to .
+.Fa new .
If
-.Fa to
+.Fa new
exists, it is first removed.
Both
-.Fa from
+.Fa old
and
-.Fa to
-must be of the same type (that is, both directories or both
-non-directories), and must reside on the same file system.
+.Fa new
+must be of the same type
+(that is, both must be either directories or non-directories)
+and must reside on the same file system.
.Pp
-.Fn Rename
-guarantees that an instance of
-.Fa to
-will always exist, even if the system should crash in
-the middle of the operation.
+The
+.Fn rename
+system call guarantees that an instance of
+.Fa new
+will always exist,
+even if the system should crash in the middle of the operation.
.Pp
If the final component of
-.Fa from
+.Fa old
is a symbolic link,
the symbolic link is renamed,
not the file or directory to which it points.
.Sh CAVEAT
-The system can deadlock if a loop in the file system graph is present.
+The system can deadlock if a loop is present in the file system graph.
This loop takes the form of an entry in directory
.Ql Pa a ,
say
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.
+.Pp
+Whether or not hard links to directories are supported is specific to
+the underlying filesystem implementation.
+.Pp
+It is recommended that any hard links to directories in an underlying
+filesystem should be replaced by symbolic links by the system administrator
+to avoid the possibility of deadlocks.
.Sh RETURN VALUES
A 0 value is returned if the operation succeeds, otherwise
.Fn rename
.Va errno
indicates the reason for the failure.
.Sh ERRORS
-.Fn Rename
-will fail and neither of the argument files will be
+The
+.Fn rename
+system call will fail and neither of the argument files will be
affected if:
.Bl -tag -width Er
+.\" ===========
+.It Bq Er EACCES
+A component of either path prefix denies search permission.
+.\" ===========
+.It Bq Er EACCES
+The requested operation requires writing in a directory
+(e.g.,
+.Fa new ,
+new/.., or old/..) whose modes disallow this.
+.\" ===========
+.It Bq Er 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.
+.\" ===========
+.It Bq Er EFAULT
+.Em Path
+points outside the process's allocated address space.
+.\" ===========
+.It Bq Er EINVAL
+.Fa Old
+is a parent directory of
+.Fa new ,
+or an attempt is made to rename
+.Ql \&.
+or
+.Ql \&.. .
+.\" ===========
+.It Bq Er EIO
+An I/O error occurs while making or updating a directory entry.
+.\" ===========
+.It Bq Er EISDIR
+.Fa new
+is a directory, but
+.Fa old
+is not a directory.
+.\" ===========
+.It Bq Er ELOOP
+Too many symbolic links are encountered in translating either pathname.
+This is taken to be indicative of a looping symbolic link.
+.\" ===========
.It Bq Er ENAMETOOLONG
-A component of a pathname exceeded
+A component of a pathname exceeds
.Dv {NAME_MAX}
-characters, or an entire path name exceeded
+characters, or an entire path name exceeds
.Dv {PATH_MAX}
characters.
+.\" ===========
.It Bq Er ENOENT
A component of the
-.Fa from
+.Fa old
path does not exist,
or a path prefix of
-.Fa to
+.Fa new
does not exist.
-.It Bq Er EACCES
-A component of either path prefix denies search permission.
-.It Bq Er EACCES
-The requested link requires writing in a directory with a mode
-that denies write permission.
+.\" ===========
+.It Bq Er 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.
+.\" ===========
+.It Bq Er ENOTDIR
+A component of either path prefix is not a directory.
+.\" ===========
+.It Bq Er ENOTDIR
+.Fa old
+is a directory, but
+.Fa new
+is not a directory.
+.\" ===========
+.It Bq Er ENOTEMPTY
+.Fa New
+is a directory and is not empty.
+.\" ===========
.It Bq Er EPERM
The directory containing
-.Fa from
+.Fa old
is marked sticky,
and neither the containing directory nor
-.Fa from
+.Fa old
are owned by the effective user ID.
+.\" ===========
.It Bq Er EPERM
The
-.Fa to
+.Fa new
file exists,
the directory containing
-.Fa to
+.Fa new
is marked sticky,
and neither the containing directory nor
-.Fa to
+.Fa new
are owned by the effective user ID.
-.It Bq Er ELOOP
-Too many symbolic links were encountered in translating either pathname.
-.It Bq Er ENOTDIR
-A component of either path prefix is not a directory.
-.It Bq Er ENOTDIR
-.Fa from
-is a directory, but
-.Fa to
-is not a directory.
-.It Bq Er EISDIR
-.Fa to
-is a directory, but
-.Fa from
-is not a directory.
-.It Bq Er EXDEV
-The link named by
-.Fa to
-and the file named by
-.Fa from
-are on different logical devices (file systems). Note that this error
-code will not be returned if the implementation permits cross-device
-links.
-.It Bq Er 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.
-.It Bq Er 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.
-.It Bq Er EIO
-An I/O error occurred while making or updating a directory entry.
+.\" ===========
.It Bq Er EROFS
The requested link requires writing in a directory on a read-only file
system.
-.It Bq Er EFAULT
-.Em Path
-points outside the process's allocated address space.
-.It Bq Er EINVAL
-.Fa From
-is a parent directory of
-.Fa to ,
-or an attempt is made to rename
-.Ql \&.
-or
-.Ql \&.. .
-.It Bq Er ENOTEMPTY
-.Fa To
-is a directory and is not empty.
+.\" ===========
+.It Bq Er EXDEV
+The link named by
+.Fa new
+and the file named by
+.Fa old
+are on different logical devices (file systems).
+Note that this error code will not be returned
+if the implementation permits cross-device links.
.El
+.Sh CONFORMANCE
+The restriction on renaming a directory whose permissions disallow writing
+is based on the fact that UFS directories contain a ".." entry.
+If renaming a directory would move it to another parent directory,
+this entry needs to be changed.
+.Pp
+This restriction has been generalized to disallow renaming
+of any write-disabled directory,
+even when this would not require a change to the ".." entry.
+For consistency, HFS+ directories emulate this behavior.
.Sh SEE ALSO
-.Xr open 2
+.Xr open 2 ,
.Xr symlink 7
.Sh STANDARDS
The
projects / apple / xnu.git / blobdiff