On Mon, Sep 19, 2011 at 07:08:17AM +0200, Michael Kerrisk wrote:

Hi Josef (Dave C, please also note comments below),

On Mon, Nov 15, 2010 at 6:07 PM, Josef Bacik [off-list ref] wrote:

quoted

This patch adds the relevant documenation for using fallocate with the
FALLOC_FL_PUNCH_HOLE mode.  This information comes from the implementation of
FALLOC_FL_PUNCH_HOLE that I've posted along with this man page update to outline
the definition for hole punching.  Obviously this patch is dependant upon the
current implementation being accepted.  Thanks,

Signed-off-by: Josef Bacik <redacted>
---
 man2/fallocate.2 |   15 ++++++++++++---
 1 files changed, 12 insertions(+), 3 deletions(-)

diff --git a/man2/fallocate.2 b/man2/fallocate.2
index 42eefbd..1b28916 100644
--- a/man2/fallocate.2
+++ b/man2/fallocate.2

@@ -31,9 +31,8 @@ bytes.

 The
 .I mode
-argument determines the operation to be performed on the given range.
-Currently only one flag is supported for
-.IR mode :
+argument determines the operation to be performed on the given range, the
+value can be one of the following:
 .TP
 .B FALLOC_FL_KEEP_SIZE
 This flag allocates and initializes to zero the disk space

@@ -50,6 +49,16 @@ the file size (as reported by

 .BR stat (2))
 even if it is less than
 .IR offset + len .
+.TP
+.B FALLOC_FL_PUNCH_HOLE
+This flag de-allocates the disk space within the range specified by
+.I offset
+and
+.IR len .
+This call preserves the file size (as reported by
+.BR stat (2)),
+the only change will be to the amount of space used by the file.  After a
+successful call, subsequent reads from this range will return 0's.
 .\"
 .\" Note from Amit Arora:
 .\" There were few more flags which were discussed, but none of
--
1.6.6.1

Thanks for this patch. As noted in another mail, Lucian also sent a
patch for FALLOC_FL_PUNCH_HOLE, and I applied his patch first, and
then added some pieces from yours, as well as some of my own edits.

However, the addition of a second class of operation to the man page
made it clear that some significant restructuring of the page is
required. So I substantially reworked the page, including the
preexisting material on the default "file allocation" operation (Dave
C please note).

Josef, Lucian, could I ask you to check ("man -l <file>") the final
text (below) for FALLOC_FL_PUNCH_HOLE (including the EPERM error under
ERRORS)?

Dave, could I ask you to review my reworked text for the "Allocating
disk space" subsection?

Looks OK to me.

Cheers,

Dave.
-- 
Dave Chinner
david-FqsqvQoI3Ljby3iVrkZq2A@public.gmane.org
--
To unsubscribe from this list: send the line "unsubscribe linux-man" in
the body of a message to majordomo-u79uwXL29TY76Z2rM5mHXA@public.gmane.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html