fallocate: restore man-page content that was deleted in commit 5b033bfd

Reported-by: Andreas Henriksson <andreas@fatal.se>
Signed-off-by: Benno Schulenberg <bensberg@justemail.net>

1 files changed, 120 insertions, 0 deletions

diff --git a/sys-utils/fallocate.1 b/sys-utils/fallocate.1
index f68112d88..dd9f293db 100644
--- a/sys-utils/fallocate.1
+++ b/sys-utils/fallocate.1
@@ -1,3 +1,114 @@
+.TH FALLOCATE 1 "September 2011" "util-linux" "User Commands"
+.SH NAME
+fallocate \- preallocate or deallocate space to a file
+.SH SYNOPSIS
+.B fallocate
+.RB [ \-c ]
+.RB [ \-n ]
+.RB [ \-p ]
+.RB [ \-z ]
+.RB [ \-o
+.IR offset ]
+.B \-l
+.IR length
+.I filename
+.PP
+.B fallocate \-d
+.RB [ \-o
+.IR offset ]
+.RB [ \-l
+.IR length ]
+.I filename
+.SH DESCRIPTION
+.B fallocate
+is used to manipulate the allocated disk space for a file, either to deallocate
+or preallocate it.  For filesystems which support the fallocate system call,
+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
+The exit code returned by
+.B fallocate
+is 0 on success and 1 on failure.
+.SH OPTIONS
+The \fIlength\fR and \fIoffset\fR
+arguments may be followed by the multiplicative suffixes KiB (=1024),
+MiB (=1024*1024), and so on for GiB, TiB, PiB, EiB, ZiB and YiB (the "iB" is
+optional, e.g., "K" has the same meaning as "KiB") or the suffixes
+KB (=1000), MB (=1000*1000), and so on for GB, TB, PB, EB, ZB and YB.
+.PP
+The options \fB\-\-collapse\-range\fP, \fB\-\-dig\-holes\fP, \fB\-\-punch\-hole\fP and
+\fB\-\-zero\-range\fP are mutually exclusive.
+.TP
+.BR \-c , " \-\-collapse\-range"
+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 \fIoffset\fR+\fIlength\fR will be appended at the
+location \fIoffset\fR, and the file will be \fIlength\fR bytes smaller.  The option
+\fB\-\-keep\-size\fR may not be specified for colapse range operation.
+.sp
+Available since Linux 3.15 for ext4 (only for extent-based files) and XFS.
+.TP
+.BR \-d , " \-\-dig\-holes"
+Detect and dig holes.  This makes the file sparse in-place, without using extra
+disk space.  The minimum size of the hole depends on filesystem I/O block size
+(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 the entire file is analyzed for holes.
+.sp
+You can think of this option as doing a "\fBcp --sparse\fP" and then renaming
+the destination file to the original, without the need for extra disk space.
+.sp
+See \fB\-\-punch\-hole\fP for a list of supported filesystems.
+.TP
+.BR \-l , " \-\-length " \fIlength
+Specifies the length of the range, in bytes.
+.TP
+.BR \-n , " \-\-keep\-size"
+Do not modify the apparent length of the file.  This may effectively allocate
+blocks past EOF, which can be removed with a truncate.
+.TP
+.BR \-o , " \-\-offset " \fIoffset
+Specifies the beginning offset of the range, in bytes.
+.TP
+.BR \-p , " \-\-punch\-hole"
+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.
+.sp
+Supported for XFS (since Linux 2.6.38), ext4 (since Linux 3.0),
+Btrfs (since Linux 3.7) and tmpfs (since Linux 3.5).
+.TP
+.BR \-v , " \-\-verbose"
+Enable verbose mode.
+.TP
+.BR \-z , " \-\-zero\-range"
+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.
+.sp
+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.
+.sp
+Option \fB\-\-keep\-size\fP can be specified to prevent file length
+modification.
+.sp
+Available since Linux 3.14 for ext4 (only for extent-based files) and XFS.
+.TP
+.BR \-V , " \-\-version"
+Display version information and exit.
+.TP
+.BR \-h , " \-\-help"
+Display help text and exit.
 .SH AUTHORS
 .UR sandeen@redhat.com
 Eric Sandeen
@@ -6,3 +117,12 @@ Eric Sandeen
 .UR kzak@redhat.com
 Karel Zak
 .UE
+.SH SEE ALSO
+.BR fallocate (2),
+.BR posix_fallocate (3),
+.BR truncate (1)
+.SH AVAILABILITY
+The fallocate command is part of the util-linux package and is available from
+.UR ftp://\:ftp.kernel.org\:/pub\:/linux\:/utils\:/util-linux/
+Linux Kernel Archive
+.UE .