[PATCH v3] man/man2/fallocate.2: Add doc for FALLOC_FL_WRITE_ZEROES

[PATCH v3] man/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 and
block device nodes support this flag.

Cc: Zhang Yi <yi.zhang@huaweicloud.com>
Cc: Christoph Hellwig <hch@lst.de>
Cc: Darrick J. Wong <djwong@kernel.org>
Cc: gost.dev@samsung.com
Cc: linux-ext4@vger.kernel.org
Cc: linux-xfs@vger.kernel.org
Signed-off-by: Pankaj Raghav <p.raghav@samsung.com>
---
Changes since v2:
- Changed the commit format based on Alejandro's feedback.
- I have retained "preallocated" term based on Zhang Yi's feedback[1]


Note:
This feature was recently added to XFS and it is expected to land in
v7.3. I will update this man page again once v7.3 is released.

[1] https://lore.kernel.org/linux-man/3f17d214-f69c-47b6-abf6-4437cc5840c0@huaweicloud.com/

 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
+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.
+.\" commit f4265b8d32c49ff95711e6fef7d05245a2905b30
 .SS Increasing file space
 Specifying the
 .B FALLOC_FL_INSERT_RANGE
@@ -385,6 +422,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 v3] man/man2/fallocate.2: Add doc for FALLOC_FL_WRITE_ZEROES

[Zhang Yi]

On 9/10/2026 7:20 PM, Pankaj Raghav wrote:
> This flag was added to the kernel in v6.17.  As of now, only ext4 and
> block device nodes support this flag.
> 
> Cc: Zhang Yi <yi.zhang@huaweicloud.com>
> Cc: Christoph Hellwig <hch@lst.de>
> Cc: Darrick J. Wong <djwong@kernel.org>
> Cc: gost.dev@samsung.com
> Cc: linux-ext4@vger.kernel.org
> Cc: linux-xfs@vger.kernel.org
> Signed-off-by: Pankaj Raghav <p.raghav@samsung.com>

Looks good to me.

Reviewed-by: Zhang Yi <yi.zhang@huawei.com>

> ---
> Changes since v2:
> - Changed the commit format based on Alejandro's feedback.
> - I have retained "preallocated" term based on Zhang Yi's feedback[1]
> 
> 
> Note:
> This feature was recently added to XFS and it is expected to land in
> v7.3. I will update this man page again once v7.3 is released.
> 
> [1] https://lore.kernel.org/linux-man/3f17d214-f69c-47b6-abf6-4437cc5840c0@huaweicloud.com/
> 
>  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
> +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.
> +.\" commit f4265b8d32c49ff95711e6fef7d05245a2905b30
>  .SS Increasing file space
>  Specifying the
>  .B FALLOC_FL_INSERT_RANGE
> @@ -385,6 +422,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 v3] man/man2/fallocate.2: Add doc for FALLOC_FL_WRITE_ZEROES

[Alejandro Colomar]

[-- Attachment #1: Type: text/plain, Size: 3357 bytes --]

Hi Zhang, Pankaj,

> Date: 2026-09-10 20:26:23+0800
> From: Zhang Yi <yi.zhang@huaweicloud.com>
>
> On 9/10/2026 7:20 PM, Pankaj Raghav wrote:
> > This flag was added to the kernel in v6.17.  As of now, only ext4 and
> > block device nodes support this flag.
> > 
> > Cc: Zhang Yi <yi.zhang@huaweicloud.com>
> > Cc: Christoph Hellwig <hch@lst.de>
> > Cc: Darrick J. Wong <djwong@kernel.org>
> > Cc: gost.dev@samsung.com
> > Cc: linux-ext4@vger.kernel.org
> > Cc: linux-xfs@vger.kernel.org
> > Signed-off-by: Pankaj Raghav <p.raghav@samsung.com>
> 
> Looks good to me.
> 
> Reviewed-by: Zhang Yi <yi.zhang@huawei.com>

Thanks!  I've applied the patch and the tag.


Have a lovely night!
Alex

> 
> > ---
> > Changes since v2:
> > - Changed the commit format based on Alejandro's feedback.
> > - I have retained "preallocated" term based on Zhang Yi's feedback[1]
> > 
> > 
> > Note:
> > This feature was recently added to XFS and it is expected to land in
> > v7.3. I will update this man page again once v7.3 is released.
> > 
> > [1] https://lore.kernel.org/linux-man/3f17d214-f69c-47b6-abf6-4437cc5840c0@huaweicloud.com/
> > 
> >  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
> > +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.
> > +.\" commit f4265b8d32c49ff95711e6fef7d05245a2905b30
> >  .SS Increasing file space
> >  Specifying the
> >  .B FALLOC_FL_INSERT_RANGE
> > @@ -385,6 +422,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
> 

-- 
<https://www.alejandro-colomar.es>

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 833 bytes --]