Re: [PATCH 11/11] ext4: add cross rename support

Re: [PATCH 11/11] ext4: add cross rename support

[Michael Kerrisk (man-pages)]

Hi Miklos,

> The code changes are pushed to the git tree and the updated man page is below.

Now that renameat2() is in 3.15, I've taken these changes. This had to be 
manually does, because I'd done some major reworking on the pages since you 
originally wrote your text. So, I may have injected some errors.

I did a little light reworking of the text and added VERSIONS and 
CONFORMING TO pieces. I also added a couple of FIXMEs, to note points 
that will need to be updated once glibc support is (presumably) added.
(Carlos, what's the usual process for triggering that sort of thing?)

Could you please review the diff below (now against rename(2)).

Cheers,

Michael

diff --git a/man2/rename.2 b/man2/rename.2
index 9f9eda4..73b00ff 100644
--- a/man2/rename.2
+++ b/man2/rename.2
@@ -30,9 +30,9 @@
 .\" Modified Thu Mar  3 09:49:35 2005 by Michael Haardt <michael-8s1n8bisGiQ@public.gmane.org>
 .\" 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,10 @@ 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 +65,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 +168,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 +343,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,16 +362,55 @@ 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
+An invalid flag was specified in
+.IR flags ,
+or both
+.B RENAME_NOREPLACE
+and
+.B RENAME_EXCHANGE
+were specified.
+.TP
+.B EINVAL
+The filesystem does not support one of the flags in
+.IR flags .
+.TP
+.B ENOENT
+.I flags
+contains
+.B RENAME_EXCHANGE
+and
+.IR newpath
+does not exist.
 .SH VERSIONS
 .BR renameat ()
 was added to Linux in kernel 2.6.16;
 library support was added to glibc in version 2.4.
+
+.BR renameat2 ()
+was added to Linux in kernel 3.15.
+.\" FIXME glibc support is pending.
 .SH CONFORMING TO
 .BR rename ():
 4.3BSD, C89, C99, POSIX.1-2001, POSIX.1-2008.
 
 .BR renameat ():
 POSIX.1-2008.
+
+.BR renameat2()
+is Linux-specific.
 .SH BUGS
 On NFS filesystems, you can not assume that if the operation
 failed, the file was not renamed.


-- 
Michael Kerrisk
Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/
Linux/UNIX System Programming Training: http://man7.org/training/

Re: [PATCH 11/11] ext4: add cross rename support

[Miklos Szeredi]

On Sat, Apr 19, 2014 at 11:08 AM, Michael Kerrisk (man-pages)
<mtk.manpages@gmail.com> wrote:
> Hi Miklos,
>
>> The code changes are pushed to the git tree and the updated man page is below.
>
> Now that renameat2() is in 3.15, I've taken these changes. This had to be
> manually does, because I'd done some major reworking on the pages since you
> originally wrote your text. So, I may have injected some errors.
>
> I did a little light reworking of the text and added VERSIONS and
> CONFORMING TO pieces. I also added a couple of FIXMEs, to note points
> that will need to be updated once glibc support is (presumably) added.
> (Carlos, what's the usual process for triggering that sort of thing?)
>
> Could you please review the diff below (now against rename(2)).

Looks okay.

One comment on the current rename.2 page:

  #include <fcntl.h>           /* Definition of AT_* constants */

AT_ constants are not used in renameat() hence this seems unneeded.

Not sure where the RENAME_ constants need to go once renameat2() is
added to glibc, possibly to <stdio.h> since they are closely related
to rename.

Thanks,
Miklos

Re: [PATCH 11/11] ext4: add cross rename support

[Michael Kerrisk (man-pages)]

On 04/23/2014 04:21 PM, Miklos Szeredi wrote:
> On Sat, Apr 19, 2014 at 11:08 AM, Michael Kerrisk (man-pages)
> <mtk.manpages-Re5JQEeQqe8AvxtiuMwx3w@public.gmane.org> wrote:
>> Hi Miklos,
>>
>>> The code changes are pushed to the git tree and the updated man page is below.
>>
>> Now that renameat2() is in 3.15, I've taken these changes. This had to be
>> manually does, because I'd done some major reworking on the pages since you
>> originally wrote your text. So, I may have injected some errors.
>>
>> I did a little light reworking of the text and added VERSIONS and
>> CONFORMING TO pieces. I also added a couple of FIXMEs, to note points
>> that will need to be updated once glibc support is (presumably) added.
>> (Carlos, what's the usual process for triggering that sort of thing?)
>>
>> Could you please review the diff below (now against rename(2)).
> 
> Looks okay.

Thanks for checking it.

> One comment on the current rename.2 page:
> 
>   #include <fcntl.h>           /* Definition of AT_* constants */
> 
> AT_ constants are not used in renameat() hence this seems unneeded.

I think you overlooked AT_FDCWD? (It is true though that that comment 
is boilerplate across the *at() pages, some of which have several 
AT_* constants.)

> Not sure where the RENAME_ constants need to go once renameat2() is
> added to glibc, possibly to <stdio.h> since they are closely related
> to rename.

Will you be prodding the glibc folks about this?

Thanks,

Michael


-- 
Michael Kerrisk
Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/
Linux/UNIX System Programming Training: http://man7.org/training/
--
To unsubscribe from this list: send the line "unsubscribe linux-man" in
the body of a message to majordomo-u79uwXL29TY76Z2rM5mHXA@public.gmane.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html