| .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 . |