192 lines
5.3 KiB
Groff
192 lines
5.3 KiB
Groff
.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 .
|