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