.\"
.\" @(#)rename.2 8.1 (Berkeley) 6/4/93
.\"
-.Dd June 4, 1993
+.Dd September 18, 2008
.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>
.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
is a symbolic link,
the symbolic link is renamed,
not the file or directory to which it points.
-.Sh CAVEAT
+.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
.Ql Pa a ,
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.
+.Pp
+Moving or renaming a file or directory into a directory with inheritable ACLs does not result in ACLs being set on the file or directory. Use
+.Xr acl 3
+in conjunction with
+.Fn rename
+to set ACLs on the file or directory.
.Sh RETURN VALUES
A 0 value is returned if the operation succeeds, otherwise
.Fn rename
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.
.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.
.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
.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
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.
.Fn rename
function conforms to
.St -p1003.1-88 .
+The
+.Fn renameat
+system call is expected to conform to POSIX.1-2008 .
projects / apple / xnu.git / blobdiff