diff options
Diffstat (limited to 'sys-utils/fallocate.1')
| -rw-r--r-- | sys-utils/fallocate.1 | 191 |
1 files changed, 191 insertions, 0 deletions
diff --git a/sys-utils/fallocate.1 b/sys-utils/fallocate.1 new file mode 100644 index 0000000..fe5072a --- /dev/null +++ b/sys-utils/fallocate.1 @@ -0,0 +1,191 @@ +.TH FALLOCATE 1 "April 2014" "util-linux" "User Commands" +.SH NAME +fallocate \- preallocate or deallocate space to a file +.SH SYNOPSIS +.B fallocate +.RB [ \-c | \-p | \-z ] +.RB [ \-o +.IR offset ] +.B \-l +.I length +.RB [ \-n ] +.I filename +.PP +.B fallocate \-d +.RB [ \-o +.IR offset ] +.RB [ \-l +.IR length ] +.I filename +.PP +.B fallocate \-x +.RB [ \-o +.IR offset ] +.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, +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. +.PP +The exit code returned by +.B fallocate +is 0 on success and 1 on failure. +.SH OPTIONS +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 +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 +.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 +.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. +.sp +A filesystem may place limitations on the granularity of the operation, in +order to ensure efficient implementation. Typically, offset and len must be a +multiple of the filesystem logical block size, which varies according to the +filesystem type and configuration. If a filesystem has such a requirement, +the operation will fail with the error EINVAL if this requirement is violated. +.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, +.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 +.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 +.I length +bytes from +.IR offset , +shifting existing data. +.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 +.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 +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. +.TP +.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 +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 +.MT sandeen@redhat.com +Eric Sandeen +.ME +.br +.MT kzak@redhat.com +Karel Zak +.ME +.SH SEE ALSO +.BR truncate (1), +.BR fallocate (2), +.BR posix_fallocate (3) +.SH AVAILABILITY +The fallocate command is part of the util-linux package and is available from +.UR https://\:www.kernel.org\:/pub\:/linux\:/utils\:/util-linux/ +Linux Kernel Archive +.UE . |