Re: [PATCH v2] man2/fallocate.2: add doc for FALLOC_FL_WRITE_ZEROES

[Pankaj Raghav <pankaj.raghav@linux.dev>]

On 8/22/2026 2:41 PM, Alejandro Colomar wrote:
> Hi Pankaj, Christoph,
> 
>> Date: 2026-08-20 11:04:00+0200
>> From: Pankaj Raghav <p.raghav@samsung.com>
>> Subject: Re: [PATCH v2] man2/fallocate.2: add doc for FALLOC_FL_WRITE_ZEROES
> 
> We use the full path in the prefix.  That is, 'man/man2/...: ...'.
> Also, we use regular sentence conventions for the first letter after
> the ':', so s/add/Add/.
> 

Got it.

>> This flag was added to the kernel in v6.17. As of now, only ext4 and
> 
> Please use two spaces after period.
> <https://git.kernel.org/pub/scm/docs/man-pages/man-pages.git/tree/CONTRIBUTING.d/patches/description#n44>
> 

Ok!

>> block device nodes support this flag.
>>
>> Signed-off-by: Pankaj Raghav <p.raghav@samsung.com>
> 
> Please include the CC list here too.
> 
>> ---
>> Changes since v1:
>> - Change the phrasing around zeroing and its condition (Zhang Yi)
>> - Update ext4 support only for extent-based files (Zhang Yi)
>>
>> Note:
>> This feature was recently added to XFS and it is expected to land in
>> v7.13. I will update this man page again once v7.13 is released.
>>
>>   man/man2/fallocate.2 | 38 ++++++++++++++++++++++++++++++++++++++
>>   1 file changed, 38 insertions(+)
>>
>> diff --git a/man/man2/fallocate.2 b/man/man2/fallocate.2
>> index ef6586c77..48a8c3468 100644
>> --- a/man/man2/fallocate.2
>> +++ b/man/man2/fallocate.2
>> @@ -244,6 +244,43 @@ SMB3 (since Linux 3.17)
>>   .IP \[bu]
>>   Btrfs (since Linux 4.16)
>>   .\" commit f27451f229966874a8793995b8e6b74326d125df
>> +.SS Writing zeroes in file space
>> +Specifying the
>> +.B FALLOC_FL_WRITE_ZEROES
>> +flag (available since Linux 6.17)
>> +.\" commit 7bd43cc79cab3850f34da0a31d5b042b701590ef
>> +in
>> +.I mode
>> +physically zeros space in the byte range starting at
>> +.I offset
>> +and continuing for
>> +.I size
>> +bytes.
>> +Within the specified range,
>> +blocks are preallocated for the regions that span the holes
> 
> What does it mean that "blocks are preallocated"?  That they must be
> allocated prior to this call?  I suspect not.  Otherwise, we'd be saying
> 'must be' instead of 'are'.
> 

I guess preallocate in this context means unmapped blocks where we guarantee
space for an application.

> I suspect it means that this call allocates blocks for those regions,
> but then I'm not sure we want 'pre' there.
> 

You are right. The blocks are allocated when we use FL_WRITE_ZEROES (they should 
be marked as MAPPED). I will change it here. I guess the man pages for util 
linux also needs to be changed[1]. @Zhang Yi, thoughts?

>> +in the file.
>> +After a successful call,
>> +subsequent reads from this range will return zeros and
>> +subsequent writes to that range do not require further
>> +changes to the file mapping metadata.
>> +.P
>> +Zeroing is done within the filesystem.
>> +The filesystem may use a hardware-accelerated zeroing command
>> +or may submit regular writes.
>> +The behavior depends on the filesystem design and the
>> +available hardware.
>> +.P
>> +No other flags may be specified in
>> +.I mode
>> +in conjunction with
>> +.BR FALLOC_FL_WRITE_ZEROES .
>> +.P
>> +Not all filesystems support
>> +.BR FALLOC_FL_WRITE_ZEROES ;
>> +if a filesystem doesn't support the operation, an error is returned.
>> +The operation is supported only in ext4 (only for extent-based files)
>> +since Linux 6.17.
> 
> Christoph, is this correct?  I remember you said something about block
> device nodes in v1.
> 

Even though block devices support some of the FALLOC_FL_* flags, I don't see it 
mentioned here as explicitly supported. That is why I kept it out of the 
changes. Let me know your thoughts.

Thanks for the feedback.

--
Pankaj

[1] https://man7.org/linux/man-pages/man1/fallocate.1.html