X-Git-Url: https://git.saurik.com/apple/xnu.git/blobdiff_plain/b0d623f7f2ae71ed96e60569f61f9a9a27016e80..0a7de7458d150b5d4dffc935ba399be265ef0a1a:/bsd/man/man2/rename.2

diff --git a/bsd/man/man2/rename.2 b/bsd/man/man2/rename.2
index cefb57810..49a562912 100644
--- a/bsd/man/man2/rename.2
+++ b/bsd/man/man2/rename.2
@@ -37,7 +37,10 @@
 .Dt RENAME 2
 .Os BSD 4.2
 .Sh NAME
-.Nm rename
+.Nm rename ,
+.Nm renameat ,
+.Nm renamex_np ,
+.Nm renameatx_np
 .Nd change the name of a file
 .Sh SYNOPSIS
 .Fd #include <stdio.h>
@@ -46,6 +49,12 @@
 .Fa "const char *old"
 .Fa "const char *new"
 .Fc
+.Ft int
+.Fn renameat "int fromfd" "const char *from" "int tofd" "const char *to"
+.Ft int
+.Fn renamex_np "const char *from" "const char *to" "unsigned int flags"
+.Ft int
+.Fn renameatx_np "int fromfd" "const char *from" "int tofd" "const char *to" "unsigned int flags"
 .Sh DESCRIPTION
 The
 .Fn rename
@@ -76,6 +85,66 @@ If the final component of
 is a symbolic link,
 the symbolic link is renamed,
 not the file or directory to which it points.
+.Pp
+The
+.Fn renameat
+system call is equivalent to
+.Fn rename
+except in the case where either
+.Fa from
+or
+.Fa to
+specifies a relative path.
+If
+.Fa from
+is a relative path, the file to be renamed is located
+relative to the directory associated with the file descriptor
+.Fa fromfd
+instead of the current working directory.
+If the
+.Fa to
+is a relative path, the same happens only relative to the directory associated
+with
+.Fa tofd .
+If the
+.Fn renameat
+is passed the special value
+.Dv AT_FDCWD
+in the
+.Fa fromfd
+or
+.Fa tofd
+parameter, the current working directory is used in the determination
+of the file for the respective path parameter.
+.Pp
+The
+.Fn renamex_np
+and
+.Fn renameatx_np
+system calls are similar to their counterparts except that they take a
+.Fa flags
+argument.
+Values for
+.Fa flags
+are constructed with below bits set:
+.Bl -tag -offset indent
+.It Dv RENAME_SWAP
+On file systems that support it (see
+.Xr getattrlist 2
+.Dv VOL_CAP_INT_RENAME_SWAP Ns ),
+it will cause the source and target to be atomically swapped.  Source and target need not be of
+the same type, i.e. it is possible to swap a file with a directory.
+EINVAL is returned in case of bitwise-inclusive OR with
+.Dv RENAME_EXCL .
+.It Dv RENAME_EXCL
+On file systems that support it (see
+.Xr getattrlist 2
+.Dv VOL_CAP_INT_RENAME_EXCL Ns ),
+it will cause
+.Dv EEXIST
+to be returned if the destination already exists. EINVAL is returned in case of bitwise-inclusive OR with
+.Dv RENAME_SWAP .
+.El
 .Sh CAVEATS
 The system can deadlock if a loop is present in the file system graph.
 This loop takes the form of an entry in directory
@@ -141,6 +210,14 @@ 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 EEXIST
+.Fa flags
+has
+.Dv RENAME_EXCL
+set but
+.Fa new
+already exists.
+.\" ===========
 .It Bq Er EFAULT
 .Em Path
 points outside the process's allocated address space.
@@ -153,6 +230,23 @@ or an attempt is made to rename
 .Ql \&.
 or
 .Ql \&.. .
+If
+.Dv RENAME_SWAP
+is used, then
+.Dv EINVAL
+will also be returned if
+.Fa new
+is a parent directory of
+.Fa old .
+If both RENAME_SWAP and RENAME_EXCL bits are set in
+.Fa flags ,
+then
+.Dv EINVAL
+will be returned.
+.\" ===========
+.It Bq Er EINVAL
+.Fa flags
+has an invalid value.
 .\" ===========
 .It Bq Er EIO
 An I/O error occurs while making or updating a directory entry.
@@ -182,6 +276,14 @@ or a path prefix of
 .Fa new
 does not exist.
 .\" ===========
+.It Bq Er ENOENT
+.Fa flags
+has
+.Dv RENAME_SWAP
+set but
+.Fa new
+does not exist.
+.\" ===========
 .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
@@ -200,6 +302,10 @@ is not a directory.
 .Fa New
 is a directory and is not empty.
 .\" ===========
+.It Bq Er ENOTSUP
+.Fa flags
+has a value that is not supported by the file system.
+.\" ===========
 .It Bq Er EPERM
 The directory containing
 .Fa old
@@ -232,6 +338,42 @@ are on different logical devices (file systems).
 Note that this error code will not be returned
 if the implementation permits cross-device links.
 .El
+.Pp
+The
+.Fn renameat
+and
+.Fn renameatx_np
+calls may also fail with:
+.Bl -tag -width Er
+.It Bq Er EBADF
+The
+.Fa from
+argument does not specify an absolute path and the
+.Fa fromfd
+argument is neither
+.Dv AT_FDCWD
+nor a valid file descriptor open for searching, or the
+.Fa to
+argument does not specify an absolute path and the
+.Fa tofd
+argument is neither
+.Dv AT_FDCWD
+nor a valid file descriptor open for searching.
+.It Bq Er ENOTDIR
+The
+.Fa from
+argument is not an absolute path and
+.Fa fromfd
+is neither
+.Dv AT_FDCWD
+nor a file descriptor associated with a directory, or the
+.Fa to
+argument is not an absolute path and
+.Fa tofd
+is neither
+.Dv AT_FDCWD
+nor a file descriptor associated with a directory.
+.El
 .Sh CONFORMANCE
 The restriction on renaming a directory whose permissions disallow writing
 is based on the fact that UFS directories contain a ".." entry.
@@ -250,3 +392,6 @@ The
 .Fn rename
 function conforms to 
 .St -p1003.1-88 .
+The
+.Fn renameat
+system call is expected to conform to POSIX.1-2008 .