On Mon, Jul 22, 2024 at 09:57:22AM +0000, John Garry wrote: > From: Himanshu Madhani <himanshu.madhani@xxxxxxxxxx> > > Add RWF_ATOMIC flag description for pwritev2(). > > Signed-off-by: Himanshu Madhani <himanshu.madhani@xxxxxxxxxx> > [jpg: complete rewrite] > Signed-off-by: John Garry <john.g.garry@xxxxxxxxxx> Sounds good to me now! Thanks for taking care of the documentation! Reviewed-by: Darrick J. Wong <djwong@xxxxxxxxxx> --D > --- > man/man2/readv.2 | 61 ++++++++++++++++++++++++++++++++++++++++++++++++ > 1 file changed, 61 insertions(+) > > diff --git a/man/man2/readv.2 b/man/man2/readv.2 > index eecde06dc..7737eb65c 100644 > --- a/man/man2/readv.2 > +++ b/man/man2/readv.2 > @@ -237,6 +237,50 @@ the data is always appended to the end of the file. > However, if the > .I offset > argument is \-1, the current file offset is updated. > +.TP > +.BR RWF_ATOMIC " (since Linux 6.11)" > +Requires that writes to regular files in block-based filesystems be issued with > +torn-write protection. > +Torn-write protection means that for a power or any other hardware failure, > +all or none of the data from the write will be stored, > +but never a mix of old and new data. > +This flag is meaningful only for > +.BR pwritev2 (), > +and its effect applies only to the data range written by the system call. > +The total write length must be power-of-2 and must be sized in the range > +.RI [ stx_atomic_write_unit_min , > +.IR stx_atomic_write_unit_max ]. > +The write must be at a naturally-aligned offset within the file with respect to > +the total write length. > +For example, > +a write of length 32KiB at a file offset of 32KiB is permitted, > +however a write of length 32KiB at a file offset of 48KiB is not permitted. > +The upper limit of > +.I iovcnt > +for > +.BR pwritev2 () > +is given by the value in > +.I stx_atomic_write_segments_max. > +Torn-write protection only works with > +.B O_DIRECT > +flag, > +i.e. buffered writes are not supported. > +To guarantee consistency from the write between a file's in-core state with the > +storage device, > +.B O_SYNC > +or > +.B O_DSYNC > +must be specified for > +.BR open (2). > +The same synchronized I/O guarantees as described in > +.BR open (2) > +are provided when these flags or their equivalent flags and system calls are > +used (e.g. > +if > +.BR RWF_SYNC > +is specified for > +.BR pwritev2 () > +). > .SH RETURN VALUE > On success, > .BR readv (), > @@ -280,9 +324,26 @@ values overflows an > value. > .TP > .B EINVAL > +If > +.BR RWF_ATOMIC > +is specified, > +the combination of the sum of the > +.I iov_len > +values and the > +.I offset > +value does not comply with the length and offset torn-write protection rules. > +.TP > +.B EINVAL > The vector count, > .IR iovcnt , > is less than zero or greater than the permitted maximum. > +If > +.BR RWF_ATOMIC > +is specified, > +this maximum is given by the > +.I stx_atomic_write_segments_max > +value from > +.I statx. > .TP > .B EOPNOTSUPP > An unknown flag is specified in \fIflags\fP. > -- > 2.31.1 > >
