fallocate: make man page readable for humans

Well, let's copy & past from fallocate(2) syscall man page rather than
try to be creative with another description for the flags.

Reported-by: Bernhard Voelker <mail@bernhard-voelker.de>
Signed-off-by: Karel Zak <kzak@redhat.com>

1 files changed, 41 insertions, 28 deletions

diff --git a/sys-utils/fallocate.1 b/sys-utils/fallocate.1
index 1177cf389..0496d4a48 100644
--- a/sys-utils/fallocate.1
+++ b/sys-utils/fallocate.1
@@ -29,10 +29,6 @@ preallocation is done quickly by allocating blocks and marking them as
 uninitialized, requiring no IO to the data blocks. This is much faster than
 creating a file by filling it with zeros.
 .PP
-As of the Linux Kernel v2.6.31, the fallocate system call is supported by the
-btrfs, ext4, ocfs2, and xfs filesystems. Support for options needed to run with
-\fI\-\-punch-hole\fR or \fI\-\-detect-holes\fR was added in Linux 2.6.38.
-.PP
 The exit code returned by
 .B fallocate
 is 0 on success and 1 on failure.
@@ -46,39 +42,56 @@ KB=1000, MB=1000*1000, and so on for GB, TB, PB, EB, ZB and YB.
 Do not modify the apparent length of the file.  This may effectively allocate
 blocks past EOF, which can be removed with a truncate.
 .IP "\fB\-p, \-\-punch-hole\fP"
-Punch holes in the file, the range should not exceed the length of the file.
-This option may not be specified at the same time as the
-.B \-z
-option.
+Deallocates space (i.e., creates a hole) in the byte range starting at
+\fIoffset\fP and continuing for \fIlength\fR bytes.  Within the
+specified range, partial filesystem blocks are zeroed, and whole
+filesystem blocks are removed from the file.  After a successful
+call, subsequent reads from this range will return zeroes.  This option
+may not be specified at the same time as  the \fB\-\-zero-range\fP option.
+Also, when using this option, \fB\-\-keep-size\fP is implied.
+
+Supported for XFS (since Linux 2.6.38), ext4 (since Linux 3.0),
+Btrfs (since Linux 3.7) and tmpfs (since Linux 3.5).
 .IP "\fB\-d, \-\-dig-holes\fP"
 Detect and dig holes. Makes the file sparse in-place, without using extra disk
 space. The minimal size of the hole depends on filesystem I/O block size
-(usually 4096 bytes). Also, when using this option, \fI\-\-keep-size\fP is
-implied.
-.PP
-.IP
+(usually 4096 bytes). Also, when using this option, \fB\-\-keep-size\fP is
+implied. If no range is specified by \fB\-\-offset\fP and \fB\-\-length\fP,
+then all file is analyzed for holes.
+
 You can think of this as doing a "\fBcp --sparse\fP" and
 renaming the dest file as the original, without the need for extra disk space.
+
+See \fB\-\-punch-hole\fP for list of the supported filesystems.
 .IP "\fB\-c, \-\-collapse-range\fP"
-Collapse a particular file range to nullify the hole. Extents beyond the range
-[offset, offset+length] will be shifted to the beginning of hole. Hence this
-command does not leave a hole, while \fI\-\-punch-hole\fP leaves a hole
-instead of shifting extents. Both offset and length should be aligned to
-the block size of filesystem.
+Removes a byte range from a file, without leaving a hole.  The byte range
+to be collapsed starts at \fIoffset\fP and continues
+for \fIlength\fR bytes.  At the completion of the operation, the contents of
+the file starting at the location offset+length will be appended at the
+location offset, and the file will be \fIlength\fR bytes smaller.
+
+Available since Linux 3.15 for ext4 (only for extent-based files) and XFS.
 .IP "\fB\-z, \-\-zero-range\fP"
-Zero range in the file. Regions that span holes in the file will be
-preallocated, this includes areas past EOF. Option
-.B \-n
-can be specified to prevent file length modification. Reads from the range
-will return zeros. This option may not be specified at the same time as the
-.B \-p
-or
-.B \-c
-option.
+Zeroes space in the byte range starting at \fIoffset\fP and
+continuing for \fIlength\fR 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 zeroes.
+
+Zeroing is done within the filesystem preferably by converting the
+range into unwritten extents.  This approach means that the specified
+range will not be physically zeroed out on the device (except for
+partial blocks at the either end of the range), and I/O is
+(otherwise) required only to update metadata.
+
+Option \fB\-\-keep\-size\fP can be specified to prevent file length
+modification. This option may not be specified at the same time as the
+\fB\-\-punch-hole\fP or \fB\-\-collapse-range\fP option.
+
+Available since Linux 3.14 for ext4 (only for extent-based files) and XFS.
 .IP "\fB\-o, \-\-offset\fP \fIoffset\fP
-Specifies the beginning offset of the allocation, in bytes.
+Specifies the beginning offset of the range, in bytes.
 .IP "\fB\-l, \-\-length\fP \fIlength\fP
-Specifies the length of the allocation, in bytes.
+Specifies the length of the range, in bytes.
 .IP "\fB\-h, \-\-help\fP"
 Display help text and exit.
 .IP "\fB-v, \-\-verbose"