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

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

[Pankaj Raghav]

This flag was added to the kernel in v6.17. As of now, only ext4
supports this flag.

Signed-off-by: Pankaj Raghav <p.raghav@samsung.com>
---
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 | 36 ++++++++++++++++++++++++++++++++++++
 1 file changed, 36 insertions(+)

diff --git a/man/man2/fallocate.2 b/man/man2/fallocate.2
index ef6586c77..b39ca5c8d 100644
--- a/man/man2/fallocate.2
+++ b/man/man2/fallocate.2
@@ -244,6 +244,41 @@ 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 allocated with written extents for
+the regions that span the holes in the file.
+After a successful call,
+subsequent reads from this range will return zeros.
+.P
+This
+.I mode
+makes use of the unmap write zeroes functionality feature that many modern
+flash-based storage offers to efficiently zero out the hole space.
+This approach means that the specified range will be physically zeroed out
+on the device (including partial blocks at the either end of the range).
+.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 (since Linux 6.17).
+.\" commit f4265b8d32c49ff95711e6fef7d05245a2905b30
 .SS Increasing file space
 Specifying the
 .B FALLOC_FL_INSERT_RANGE
@@ -385,6 +420,7 @@ or
 is
 .BR FALLOC_FL_COLLAPSE_RANGE ,
 .BR FALLOC_FL_ZERO_RANGE ,
+.BR FALLOC_FL_WRITE_ZEROES ,
 or
 .BR FALLOC_FL_INSERT_RANGE ,
 but the file referred to by

base-commit: d926b42e0ea0406d5c2556e18205eced92d053f1
-- 
2.51.2

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

[Christoph Hellwig]

On Wed, Aug 19, 2026 at 01:40:22PM +0200, Pankaj Raghav wrote:
> This flag was added to the kernel in v6.17. As of now, only ext4
> supports this flag.

block device nodes also support it.

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

[Zhang Yi]

On 8/19/2026 7:40 PM, Pankaj Raghav wrote:
> This flag was added to the kernel in v6.17. As of now, only ext4
> supports this flag.
> 
> Signed-off-by: Pankaj Raghav <p.raghav@samsung.com>

Hi, Pankaj!

Thank you for supplementing the missing man page documentation. Some
suggestions below.

> ---
> 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 | 36 ++++++++++++++++++++++++++++++++++++
>  1 file changed, 36 insertions(+)
> 
> diff --git a/man/man2/fallocate.2 b/man/man2/fallocate.2
> index ef6586c77..b39ca5c8d 100644
> --- a/man/man2/fallocate.2
> +++ b/man/man2/fallocate.2
> @@ -244,6 +244,41 @@ 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 allocated with written extents for
> +the regions that span the holes in the file.
> +After a successful call,
> +subsequent reads from this range will return zeros.
> +.P
> +This
> +.I mode
> +makes use of the unmap write zeroes functionality feature that many modern
> +flash-based storage offers to efficiently zero out the hole space.

FALLOC_FL_WRITE_ZEROES itself is relatively flexible. It does not
mandate that the filesystem must implement zeroing via unmap write
zeroes. That depends on the specific implementation of each filesystem.
Currently, ext4, xfs, and block devices (bdev) support this operation
through that approach, since writing zeros directly on devices that do
not support unmap zeroes can be very slow and thus of little practical
value.

Therefore, I would suggest referring to the description in, for
example, fallocate(1):

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

  "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."

What do you think?

> +This approach means that the specified range will be physically zeroed out
> +on the device (including partial blocks at the either end of the range).
> +.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 (since Linux 6.17).
                                      ^^^^
ext4 (only for extent-based files)

Thanks,
Yi.

> +.\" commit f4265b8d32c49ff95711e6fef7d05245a2905b30
>  .SS Increasing file space
>  Specifying the
>  .B FALLOC_FL_INSERT_RANGE
> @@ -385,6 +420,7 @@ or
>  is
>  .BR FALLOC_FL_COLLAPSE_RANGE ,
>  .BR FALLOC_FL_ZERO_RANGE ,
> +.BR FALLOC_FL_WRITE_ZEROES ,
>  or
>  .BR FALLOC_FL_INSERT_RANGE ,
>  but the file referred to by
> 
> base-commit: d926b42e0ea0406d5c2556e18205eced92d053f1

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

[Pankaj Raghav]

> FALLOC_FL_WRITE_ZEROES itself is relatively flexible. It does not
> mandate that the filesystem must implement zeroing via unmap write
> zeroes. That depends on the specific implementation of each filesystem.
> Currently, ext4, xfs, and block devices (bdev) support this operation
> through that approach, since writing zeros directly on devices that do
> not support unmap zeroes can be very slow and thus of little practical
> value.
> 
> Therefore, I would suggest referring to the description in, for
> example, fallocate(1):
> 
> https://man7.org/linux/man-pages/man1/fallocate.1.html
> 
>   "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."
> 
> What do you think?
> 

You are right. It is up to the FSs to implement however it wants.
I will use this framing instead. Thanks.

>> +This approach means that the specified range will be physically zeroed out
>> +on the device (including partial blocks at the either end of the range).
>> +.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 (since Linux 6.17).
>                                       ^^^^
> ext4 (only for extent-based files)
> 

Sounds good.

--
Pankaj

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

[Pankaj Raghav]

On 8/19/26 16:30, Christoph Hellwig wrote:
> On Wed, Aug 19, 2026 at 01:40:22PM +0200, Pankaj Raghav wrote:
>> This flag was added to the kernel in v6.17. As of now, only ext4
>> supports this flag.
> 
> block device nodes also support it.

Yeah but I did not notice any mention of block device in this man page, so I didn't mention it.
I will update my commit message in the next version.

--
Pankaj