rename.2: Document renameat2()

Some light edits to this patch by mtk.

Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>

diff --git a/man2/rename.2 b/man2/rename.2
index 9f9eda48b54856104199899f1747703fc29e40f1..895d22c208d77ba258deaa172a7b37f88db9cd4f 100644 (file)
--- a/man2/rename.2
+++ b/man2/rename.2
@@ -30,9 +30,9 @@
 .\" Modified Thu Mar  3 09:49:35 2005 by Michael Haardt <michael@moria.de>
 .\" 2007-03-25, mtk, added various text to DESCRIPTION.
 .\"
-.TH RENAME 2 2014-02-21 "Linux" "Linux Programmer's Manual"
+.TH RENAME 2 2014-04-19 "Linux" "Linux Programmer's Manual"
 .SH NAME
-rename, renameat \- change the name or location of a file
+rename, renameat, renameat2 \- change the name or location of a file
 .SH SYNOPSIS
 .nf
 .B #include <stdio.h>
@@ -44,6 +44,9 @@ rename, renameat \- change the name or location of a file
 .sp
 .BI "int renameat(int " olddirfd ", const char *" oldpath ,
 .BI "             int " newdirfd ", const char *" newpath );
+
+.BI "int renameat2(int " olddirfd ", const char *" oldpath ,
+.BI "              int " newdirfd ", const char *" newpath ", unsigned int " flags );
 .fi
 .sp
 .in -4n
@@ -61,6 +64,7 @@ _XOPEN_SOURCE\ >=\ 700 || _POSIX_C_SOURCE\ >=\ 200809L
 .TP
 Before glibc 2.10:
 _ATFILE_SOURCE
+.\" FIXME need to define FTMs for renameat2(), once it hits glibc
 .RE
 .ad
 .PD
@@ -163,6 +167,38 @@ See
 .BR openat (2)
 for an explanation of the need for
 .BR renameat ().
+.SS renameat2()
+.BR renameat2 ()
+has an additional
+.I flags
+argument.
+A
+.BR renameat2 ()
+call with a zero
+.I flags
+argument is equivalent to
+.BR renameat ().
+
+The
+.I flags
+argument is a bit mask consisting of zero or more of the following flags:
+.TP
+.B RENAME_NOREPLACE
+Don't overwrite
+.IR newpath .
+of the rename.
+Return an error if
+.IR newpath
+already exists.
+.TP
+.B RENAME_EXCHANGE
+Atomically exchange
+.IR oldpath
+and
+.IR newpath .
+Both pathnames must exist
+but may be of different types (e.g., one could be a non-empty directory
+and the other a symbolic link).
 .SH RETURN VALUE
 On success, zero is returned.
 On error, \-1 is returned, and
@@ -306,7 +342,9 @@ does not work across different mount points,
 even if the same filesystem is mounted on both.)
 .PP
 The following additional errors can occur for
-.BR renameat ():
+.BR renameat ()
+and
+.BR renameat2 ():
 .TP
 .B EBADF
 .I olddirfd
@@ -323,6 +361,31 @@ or similar for
 .I newpath
 and
 .I newdirfd
+.PP
+The following additional errors can occur for
+.BR renameat2 ():
+.TP
+.B EEXIST
+.I flags
+contains
+.B RENAME_NOREPLACE
+and
+.I newpath
+already exists.
+.TP 
+.B EINVAL
+Invalid combination of
+.IR flags .
+.TP
+.B EINVAL
+The filesystem does not support one of the flags in
+.IR flags .
+.TP
+.B ENOENT
+.I flags
+contain
+.B RENAME_EXCHANGE
+and the target of the rename does not exist.
 .SH VERSIONS
 .BR renameat ()
 was added to Linux in kernel 2.6.16;