X-Git-Url: https://git.saurik.com/apple/xnu.git/blobdiff_plain/9bccf70c0258c7cac2dcb80011b2a964d884c552..935ed37a5c468c8a1c07408573c08b8b7ef80e8b:/bsd/man/man2/rename.2 diff --git a/bsd/man/man2/rename.2 b/bsd/man/man2/rename.2 index 4167485d3..39487e6c2 100644 --- a/bsd/man/man2/rename.2 +++ b/bsd/man/man2/rename.2 @@ -42,36 +42,42 @@ .Sh SYNOPSIS .Fd #include .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 @@ -94,8 +100,13 @@ and 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 @@ -103,98 +114,130 @@ returns -1 and the global variable .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