| .\" -*- nroff -*- |
| .TH FALLOCATE 1 "September 2011" "util-linux" "User Commands" |
| .SH NAME |
| fallocate \- preallocate or deallocate space to a file |
| .SH SYNOPSIS |
| .B fallocate |
| .RB [ \-n ] |
| .RB [ \-p ] |
| .RB [ \-c ] |
| .RB [ \-z ] |
| .RB [ \-o |
| .IR offset ] |
| .B \-l |
| .IR length |
| .I filename |
| .PP |
| .B fallocate |
| .RB \-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. |
| .PP |
| .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. |
| |
| The options \fB\-\-collapse-range\fP, \fB\-\-dig-holes\fP, \fB\-\-punch-hole\fP and |
| \fB\-\-zero-range\fP are mutually exclusive. |
| |
| .IP "\fB\-n, \-\-keep-size\fP" |
| 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" |
| 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, \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" |
| 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. The option |
| \fB\-\-keep\-size\fR may not be specified for colapse range operation. |
| |
| Available since Linux 3.15 for ext4 (only for extent-based files) and XFS. |
| .IP "\fB\-z, \-\-zero-range\fP" |
| 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. |
| |
| 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 range, in bytes. |
| .IP "\fB\-l, \-\-length\fP \fIlength\fP |
| Specifies the length of the range, in bytes. |
| .IP "\fB\-h, \-\-help\fP" |
| Display help text and exit. |
| .IP "\fB-v, \-\-verbose" |
| Enable verbose mode. |
| .IP "\fB-V, \-\-version" |
| Display version information and exit. |
| .SH AUTHORS |
| .UR sandeen@redhat.com |
| Eric Sandeen |
| .UE |
| .br |
| .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 . |