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

[Pankaj Raghav <p.raghav@samsung.com>]

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