diff options
| -rw-r--r-- | sys-utils/fallocate.1 | 151 |
1 files changed, 98 insertions, 53 deletions
diff --git a/sys-utils/fallocate.1 b/sys-utils/fallocate.1 index 0cbb5c994..d4821dcd1 100644 --- a/sys-utils/fallocate.1 +++ b/sys-utils/fallocate.1 @@ -7,7 +7,7 @@ fallocate \- preallocate or deallocate space to a file .RB [ \-o .IR offset ] .B \-l -.IR length +.I length .RB [ \-n ] .I filename .PP @@ -21,89 +21,134 @@ fallocate \- preallocate or deallocate space to a file .B fallocate \-x .RB [ \-o .IR offset ] -.RB \-l -.IR length +.B \-l +.I 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, +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 zeroes. +uninitialized, requiring no IO to the data blocks. +This is much faster than creating a file by filling it with zeroes. .PP The exit code returned by .B fallocate is 0 on success and 1 on failure. .SH OPTIONS -The \fIlength\fR and \fIoffset\fR +The +.I length +and +.I offset 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 +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. +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. +The options +.BR \-\-collapse\-range ", " \-\-dig\-holes ", " \-\-punch\-hole , +and +.B \-\-zero\-range +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 the collapse-range operation. +.BR \-c ", " \-\-collapse\-range +Removes a byte range from a file, without leaving a hole. +The byte range to be collapsed starts at +.I offset +and continues for +.I length +bytes. +At the completion of the operation, +the contents of the file starting at the location +.IR offset + length +will be appended at the location +.IR offset , +and the file will be +.I length +bytes smaller. +The option +.B \-\-keep\-size +may not be specified for the collapse-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, +.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, +.B \-\-keep\-size +is implied. If no range is specified by +.B \-\-offset +and +.BR \-\-length , 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. +You can think of this option as doing a +.RB """" "cp \-\-sparse" """" +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 \-i , " \-\-insert\-range" -Insert a hole of \fIlength\fR bytes from \fIoffset\fR, shifting existing data. +.BR \-i ", " \-\-insert\-range +Insert a hole of +.I length +bytes from +.IR offset , +shifting existing data. .TP -.BR \-l , " \-\-length " \fIlength +.BR \-l ", " "\-\-length " \fIlength Specifies the length of the range, in bytes. .TP -.BR \-n , " \-\-keep\-size" +.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 +.BR \-o ", " "\-\-offset " \fIoffset Specifies the beginning offset of the range, in bytes. .TP -.BR \-p , " \-\-punch\-hole" +.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. +.I offset +and continuing for +.I length +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 +.B \-\-zero\-range +option. +Also, when using this option, +.B \-\-keep\-size +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" +.BR \-v ", " \-\-verbose Enable verbose mode. .TP -.BR \-x , " \-\-posix" -Enable POSIX operation mode. In that mode allocation operation always completes, -but it may take longer time when fast allocation is not supported by the underlying filesystem. +.BR \-x ", " \-\-posix +Enable POSIX operation mode. +In that mode allocation operation always completes, +but it may take longer time when fast allocation is not supported by +the underlying filesystem. .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. +.BR \-z ", " \-\-zero\-range +Zeroes space in the byte range starting at +.I offset +and continuing for +.I length +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 @@ -116,19 +161,19 @@ modification. .sp Available since Linux 3.14 for ext4 (only for extent-based files) and XFS. .TP -.BR \-V , " \-\-version" +.BR \-V ", " \-\-version Display version information and exit. .TP -.BR \-h , " \-\-help" +.BR \-h ", " \-\-help Display help text and exit. .SH AUTHORS -.UR sandeen@redhat.com +.MT sandeen@redhat.com Eric Sandeen -.UE +.ME .br -.UR kzak@redhat.com +.MT kzak@redhat.com Karel Zak -.UE +.ME .SH SEE ALSO .BR truncate (1), .BR fallocate (2), |