[PATCH 0/2] man2: Document RWF_NOAPPEND

[PATCH 0/2] man2: Document RWF_NOAPPEND

[John Garry]

This provides an update for Linux pwritev2 flag RWF_NOAPPEND.

John Garry (2):
  readv.2: Document RWF_NOAPPEND flag
  io_submit.2: Document RWF_NOAPPEND flag

 man/man2/io_submit.2 | 10 ++++++++++
 man/man2/readv.2     | 20 ++++++++++++++++++++
 2 files changed, 30 insertions(+)

-- 
2.31.1

[PATCH 1/2] readv.2: Document RWF_NOAPPEND flag

[John Garry]

Document flag introduced in Linux v6.9

Signed-off-by: John Garry <john.g.garry@oracle.com>
---
 man/man2/readv.2 | 20 ++++++++++++++++++++
 1 file changed, 20 insertions(+)

diff --git a/man/man2/readv.2 b/man/man2/readv.2
index 78232c19f..836612bbe 100644
--- a/man/man2/readv.2
+++ b/man/man2/readv.2
@@ -238,6 +238,26 @@ However, if the
 .I offset
 argument is \-1, the current file offset is updated.
 .TP
+.BR RWF_NOAPPEND " (since Linux 6.9)"
+The
+.BR pwritev2 ()
+system call does not honor the
+.B O_APPEND
+.BR open (2)
+flag.
+Historically Linux honored
+.B O_APPEND
+flag if set and ignored the offset argument, which is a bug.
+For
+.BR pwritev2 (),
+the
+.I offset
+argument is honored as expected if
+.BR RWF_NOAPPEND
+flag is set, the same as if
+.B O_APPEND
+flag were not set.
+.TP
 .BR RWF_ATOMIC " (since Linux 6.11)"
 Requires that
 writes to regular files in block-based filesystems
-- 
2.31.1

[PATCH 2/2] io_submit.2: Document RWF_NOAPPEND flag

[John Garry]

Document flag introduced in Linux v6.9

Signed-off-by: John Garry <john.g.garry@oracle.com>
---
 man/man2/io_submit.2 | 10 ++++++++++
 1 file changed, 10 insertions(+)

diff --git a/man/man2/io_submit.2 b/man/man2/io_submit.2
index c3d86b4c4..64292037d 100644
--- a/man/man2/io_submit.2
+++ b/man/man2/io_submit.2
@@ -141,6 +141,16 @@ as well the description of
 in
 .BR open (2).
 .TP
+.BR RWF_NOAPPEND " (since Linux 6.9)"
+Do not honor
+.B O_APPEND
+.BR open (2)
+flag.
+See the description of
+.B RWF_NOAPPEND
+in
+.BR pwritev2 (2).
+.TP
 .BR RWF_ATOMIC " (since Linux 6.11)"
 Write a block of data such that
 a write will never be torn from power fail or similar.
-- 
2.31.1

Re: [PATCH 1/2] readv.2: Document RWF_NOAPPEND flag

[Alejandro Colomar]

[-- Attachment #1: Type: text/plain, Size: 1445 bytes --]

Hi John,

On Tue, Nov 26, 2024 at 09:08:46AM +0000, John Garry wrote:
> Document flag introduced in Linux v6.9
> 
> Signed-off-by: John Garry <john.g.garry@oracle.com>
> ---
>  man/man2/readv.2 | 20 ++++++++++++++++++++
>  1 file changed, 20 insertions(+)
> 
> diff --git a/man/man2/readv.2 b/man/man2/readv.2
> index 78232c19f..836612bbe 100644
> --- a/man/man2/readv.2
> +++ b/man/man2/readv.2
> @@ -238,6 +238,26 @@ However, if the
>  .I offset
>  argument is \-1, the current file offset is updated.
>  .TP
> +.BR RWF_NOAPPEND " (since Linux 6.9)"
> +The
> +.BR pwritev2 ()
> +system call does not honor the

The other surrounding paragraphs talk in imperative (e.g., "Do not
wait").  This should be consistent with them.  How about this?:

	Do not honor the O_APPEND open(2) flag.  This flag is meaningful
	only for pwritev2().  ...

Thanks for the patch!

Have a lovely day!
Alex

> +.B O_APPEND
> +.BR open (2)
> +flag.
> +Historically Linux honored
> +.B O_APPEND
> +flag if set and ignored the offset argument, which is a bug.
> +For
> +.BR pwritev2 (),
> +the
> +.I offset
> +argument is honored as expected if
> +.BR RWF_NOAPPEND
> +flag is set, the same as if
> +.B O_APPEND
> +flag were not set.
> +.TP
>  .BR RWF_ATOMIC " (since Linux 6.11)"
>  Requires that
>  writes to regular files in block-based filesystems
> -- 
> 2.31.1
> 

-- 
<https://www.alejandro-colomar.es/>

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 833 bytes --]

Re: [PATCH 2/2] io_submit.2: Document RWF_NOAPPEND flag

[Alejandro Colomar]

[-- Attachment #1: Type: text/plain, Size: 1096 bytes --]

Hi John,

On Tue, Nov 26, 2024 at 09:08:47AM +0000, John Garry wrote:
> Document flag introduced in Linux v6.9
> 
> Signed-off-by: John Garry <john.g.garry@oracle.com>

Please add the Cc:s also to the patch trailer section.  (That means less
work for me pasting them.:)

> ---
>  man/man2/io_submit.2 | 10 ++++++++++
>  1 file changed, 10 insertions(+)
> 
> diff --git a/man/man2/io_submit.2 b/man/man2/io_submit.2
> index c3d86b4c4..64292037d 100644
> --- a/man/man2/io_submit.2
> +++ b/man/man2/io_submit.2
> @@ -141,6 +141,16 @@ as well the description of
>  in
>  .BR open (2).
>  .TP
> +.BR RWF_NOAPPEND " (since Linux 6.9)"
> +Do not honor
> +.B O_APPEND
> +.BR open (2)
> +flag.
> +See the description of
> +.B RWF_NOAPPEND
> +in
> +.BR pwritev2 (2).

LGTM.  Thanks!  I'll wait to apply it once patch 1/2 is applied.

Have a lovely day!
Alex

> +.TP
>  .BR RWF_ATOMIC " (since Linux 6.11)"
>  Write a block of data such that
>  a write will never be torn from power fail or similar.
> -- 
> 2.31.1
> 

-- 
<https://www.alejandro-colomar.es/>

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 833 bytes --]

Re: [PATCH 1/2] readv.2: Document RWF_NOAPPEND flag

[John Garry]

On 26/11/2024 11:52, Alejandro Colomar wrote:
> Hi John,
> 
> On Tue, Nov 26, 2024 at 09:08:46AM +0000, John Garry wrote:
>> Document flag introduced in Linux v6.9
>>
>> Signed-off-by: John Garry<john.g.garry@oracle.com>
>> ---
>>   man/man2/readv.2 | 20 ++++++++++++++++++++
>>   1 file changed, 20 insertions(+)
>>
>> diff --git a/man/man2/readv.2 b/man/man2/readv.2
>> index 78232c19f..836612bbe 100644
>> --- a/man/man2/readv.2
>> +++ b/man/man2/readv.2
>> @@ -238,6 +238,26 @@ However, if the
>>   .I offset
>>   argument is \-1, the current file offset is updated.
>>   .TP
>> +.BR RWF_NOAPPEND " (since Linux 6.9)"
>> +The
>> +.BR pwritev2 ()
>> +system call does not honor the
> The other surrounding paragraphs talk in imperative (e.g., "Do not
> wait").  This should be consistent with them.  How about this?:
> 
> 	Do not honor the O_APPEND open(2) flag.  This flag is meaningful
> 	only for pwritev2().  ...
> 

That sounds fine.

> Thanks for the patch!

No worries. Let's wait a bit to see if any comments from fsdevel people.

Thanks,
John

Re: [PATCH 0/2] man2: Document RWF_NOAPPEND

[John Garry]

On 26/11/2024 09:08, John Garry wrote:
> This provides an update for Linux pwritev2 flag RWF_NOAPPEND.

Hi Alex,

I'd say that it is ok to merge these changes now (with your suggested 
modifications), as no one seems to care.

Thanks,
John

> 
> John Garry (2):
>    readv.2: Document RWF_NOAPPEND flag
>    io_submit.2: Document RWF_NOAPPEND flag
> 
>   man/man2/io_submit.2 | 10 ++++++++++
>   man/man2/readv.2     | 20 ++++++++++++++++++++
>   2 files changed, 30 insertions(+)
> 

Re: [PATCH 0/2] man2: Document RWF_NOAPPEND

[Alejandro Colomar]

[-- Attachment #1: Type: text/plain, Size: 791 bytes --]

On Mon, Dec 16, 2024 at 10:33:26AM +0000, John Garry wrote:
> On 26/11/2024 09:08, John Garry wrote:
> > This provides an update for Linux pwritev2 flag RWF_NOAPPEND.
> 
> Hi Alex,
> 
> I'd say that it is ok to merge these changes now (with your suggested
> modifications), as no one seems to care.

Hi John,

Sorry for the delay.  Would you mind sending updated patches with the
minor fixes I suggested?  Thanks!

Cheers,
Alex

> 
> Thanks,
> John
> 
> > 
> > John Garry (2):
> >    readv.2: Document RWF_NOAPPEND flag
> >    io_submit.2: Document RWF_NOAPPEND flag
> > 
> >   man/man2/io_submit.2 | 10 ++++++++++
> >   man/man2/readv.2     | 20 ++++++++++++++++++++
> >   2 files changed, 30 insertions(+)
> > 
> 

-- 
<https://www.alejandro-colomar.es/>

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 833 bytes --]

Re: [PATCH 1/2] readv.2: Document RWF_NOAPPEND flag

[Alejandro Colomar]

[-- Attachment #1: Type: text/plain, Size: 1511 bytes --]

Hi John,

On Tue, Nov 26, 2024 at 11:57:44AM +0000, John Garry wrote:
> On 26/11/2024 11:52, Alejandro Colomar wrote:
> > Hi John,
> > 
> > On Tue, Nov 26, 2024 at 09:08:46AM +0000, John Garry wrote:
> > > Document flag introduced in Linux v6.9
> > > 
> > > Signed-off-by: John Garry<john.g.garry@oracle.com>
> > > ---
> > >   man/man2/readv.2 | 20 ++++++++++++++++++++
> > >   1 file changed, 20 insertions(+)
> > > 
> > > diff --git a/man/man2/readv.2 b/man/man2/readv.2
> > > index 78232c19f..836612bbe 100644
> > > --- a/man/man2/readv.2
> > > +++ b/man/man2/readv.2
> > > @@ -238,6 +238,26 @@ However, if the
> > >   .I offset
> > >   argument is \-1, the current file offset is updated.
> > >   .TP
> > > +.BR RWF_NOAPPEND " (since Linux 6.9)"
> > > +The
> > > +.BR pwritev2 ()
> > > +system call does not honor the
> > The other surrounding paragraphs talk in imperative (e.g., "Do not
> > wait").  This should be consistent with them.  How about this?:
> > 
> > 	Do not honor the O_APPEND open(2) flag.  This flag is meaningful
> > 	only for pwritev2().  ...
> > 
> 
> That sounds fine.
> 
> > Thanks for the patch!
> 
> No worries. Let's wait a bit to see if any comments from fsdevel people.

I've applied this patch already.  Thanks!
<https://www.alejandro-colomar.es/src/alx/linux/man-pages/man-pages.git/commit/?h=contrib&id=64fc4bb4ae09a4559a5789a6ede952c0f8570b39>

Cheers,
Alex

> 
> Thanks,
> John
> 

-- 
<https://www.alejandro-colomar.es/>

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 833 bytes --]

Re: [PATCH 2/2] io_submit.2: Document RWF_NOAPPEND flag

[Alejandro Colomar]

[-- Attachment #1: Type: text/plain, Size: 1083 bytes --]

Hi John,

On Tue, Nov 26, 2024 at 09:08:47AM +0000, John Garry wrote:
> Document flag introduced in Linux v6.9
> 
> Signed-off-by: John Garry <john.g.garry@oracle.com>

I've applied this patch.  Thanks!
<https://www.alejandro-colomar.es/src/alx/linux/man-pages/man-pages.git/commit/?h=contrib&id=58dcfdd953c1546cb6aea81c2209d6bb076dc246>

Cheers,
Alex

> ---
>  man/man2/io_submit.2 | 10 ++++++++++
>  1 file changed, 10 insertions(+)
> 
> diff --git a/man/man2/io_submit.2 b/man/man2/io_submit.2
> index c3d86b4c4..64292037d 100644
> --- a/man/man2/io_submit.2
> +++ b/man/man2/io_submit.2
> @@ -141,6 +141,16 @@ as well the description of
>  in
>  .BR open (2).
>  .TP
> +.BR RWF_NOAPPEND " (since Linux 6.9)"
> +Do not honor
> +.B O_APPEND
> +.BR open (2)
> +flag.
> +See the description of
> +.B RWF_NOAPPEND
> +in
> +.BR pwritev2 (2).
> +.TP
>  .BR RWF_ATOMIC " (since Linux 6.11)"
>  Write a block of data such that
>  a write will never be torn from power fail or similar.
> -- 
> 2.31.1
> 

-- 
<https://www.alejandro-colomar.es/>

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 833 bytes --]