xnu-1228.7.58.tar.gz

[apple/xnu.git] / bsd / man / man2 / rename.2

diff --git a/bsd/man/man2/rename.2 b/bsd/man/man2/rename.2
index 4167485d30af291ec4abc5a4861399e05d2f9836..39487e6c29a016163144e8f9eab2c183c5ff2eca 100644 (file)
--- a/bsd/man/man2/rename.2
+++ b/bsd/man/man2/rename.2
@@ -42,36 +42,42 @@
 .Sh SYNOPSIS
 .Fd #include <stdio.h>
 .Ft int
 .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
 .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
 to be renamed as

-.Fa to .
+.Fa new .

 If 
 If 

-.Fa to
+.Fa new

 exists, it is first removed.
 Both 
 exists, it is first removed.
 Both 

-.Fa from
+.Fa old

 and
 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
 .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
 .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
 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
 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.
 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
 .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
 .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
 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
 .It Bq Er ENAMETOOLONG

-A component of a pathname exceeded 
+A component of a pathname exceeds 

 .Dv {NAME_MAX}
 .Dv {NAME_MAX}

-characters, or an entire path name exceeded 
+characters, or an entire path name exceeds

 .Dv {PATH_MAX}
 characters.
 .Dv {PATH_MAX}
 characters.

+.\" ===========

 .It Bq Er ENOENT
 A component of the
 .It Bq Er ENOENT
 A component of the

-.Fa from
+.Fa old

 path does not exist,
 or a path prefix of
 path does not exist,
 or a path prefix of

-.Fa to
+.Fa new

 does not exist.
 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
 .It Bq Er EPERM
 The directory containing

-.Fa from
+.Fa old

 is marked sticky,
 and neither the containing directory nor
 is marked sticky,
 and neither the containing directory nor

-.Fa from
+.Fa old

 are owned by the effective user ID.
 are owned by the effective user ID.

+.\" ===========

 .It Bq Er EPERM
 The
 .It Bq Er EPERM
 The

-.Fa to
+.Fa new

 file exists,
 the directory containing
 file exists,
 the directory containing

-.Fa to
+.Fa new

 is marked sticky,
 and neither the containing directory nor
 is marked sticky,
 and neither the containing directory nor

-.Fa to
+.Fa new

 are owned by the effective user ID.
 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 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
 .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
 .Sh SEE ALSO

-.Xr open 2
+.Xr open 2 ,

 .Xr symlink 7
 .Sh STANDARDS
 The
 .Xr symlink 7
 .Sh STANDARDS
 The