diff options
| author | Himanshu Madhani <himanshu.madhani@oracle.com> | 2024-07-22 09:57:22 +0000 |
|---|---|---|
| committer | Alejandro Colomar <alx@kernel.org> | 2024-07-31 12:18:23 +0200 |
| commit | 8c967453fc1c4bd5274d90db22fc857d87e13d12 (patch) | |
| tree | cdcefa31a9ae46b37f2181cb38de5a7548b22cf4 | |
| parent | d4de003f2d752e514f0d28e1df62583fab186a9e (diff) | |
| download | man-pages-8c967453fc1c4bd5274d90db22fc857d87e13d12.tar.gz | |
readv.2: Document RWF_ATOMIC flag
Add RWF_ATOMIC flag description for pwritev2().
Signed-off-by: Himanshu Madhani <himanshu.madhani@oracle.com>
[jpg: complete rewrite]
Signed-off-by: John Garry <john.g.garry@oracle.com>
Cc: <linux-fsdevel@vger.kernel.org>
Cc: Jens Axboe <axboe@kernel.dk>
Cc: Christoph Hellwig <hch@lst.de>
Cc: Dave Chinner <dchinner@redhat.com>
Cc: "Martin K. Petersen" <martin.petersen@oracle.com>
Message-ID: <20240722095723.597846-3-john.g.garry@oracle.com>
Reviewed-by: Darrick J. Wong <djwong@kernel.org>
[alx: semantic newlines; srcfix]
Signed-off-by: Alejandro Colomar <alx@kernel.org>
| -rw-r--r-- | man/man2/readv.2 | 65 |
1 files changed, 65 insertions, 0 deletions
diff --git a/man/man2/readv.2 b/man/man2/readv.2 index e369acdeca..78232c19ff 100644 --- a/man/man2/readv.2 +++ b/man/man2/readv.2 @@ -237,6 +237,54 @@ 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 +.B RWF_SYNC +is specified for +.BR pwritev2 ()). .SH RETURN VALUE On success, .BR readv (), @@ -280,9 +328,26 @@ values overflows an value. .TP .B EINVAL +If +.B 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 +.B 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. |