Messages in this thread | | | Date | Wed, 4 Oct 2023 09:47:24 +0100 | Subject | Re: [PATCH 2/4] readv.2: Document RWF_ATOMIC flag | From | John Garry <> |
| |
On 03/10/2023 20:25, Bart Van Assche wrote: > On 9/29/23 02:37, John Garry wrote: >> +.BR RWF_ATOMIC " (since Linux 6.7)" >> +Allows block-based filesystems to indicate that write operations will >> 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 between >> +stx_atomic_write_unit_min and stx_atomic_write_unit_max, both >> inclusive. The >> +write must be at a natural offset within the file with respect to the >> total >> +write length. 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, > > It seems wrong to me to start the first sentence with "Allows". Atomic > behavior should be mandatory if RWF_ATOMIC has been set.
Yes, I agree that this has been poorly worded. Flag RWF_ATOMIC does not indicate anything. I will fix it.
> > Additionally, shouldn't it be documented what value will be stored in > errno if the atomic write has been rejected?
So I was treating all atomic writes errors which don't follow the "rules" as low-level I/O errors, which is -EIO. However, yes, I can document this. Further to that, based on description of an error for O_DIRECT, which is to return -EINVAL for misaligned, I think that -EINVAL may be better for any atomic write rule violations. OK?
Thanks, John
| |