105 lines
3.4 KiB
Groff
105 lines
3.4 KiB
Groff
.\" -*- 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
|
|
As of the Linux Kernel v2.6.31, the fallocate system call is supported by the
|
|
btrfs, ext4, ocfs2, and xfs filesystems. Support for options needed to run with
|
|
\fI\-\-punch-hole\fR or \fI\-\-detect-holes\fR was added in Linux 2.6.38.
|
|
.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.
|
|
.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"
|
|
Punch holes in the file, the range should not exceed the length of the file.
|
|
This option may not be specified at the same time as the
|
|
.B \-z
|
|
option.
|
|
.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, \fI\-\-keep-size\fP is
|
|
implied.
|
|
.PP
|
|
.IP
|
|
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.
|
|
.IP "\fB\-c, \-\-collapse-range\fP"
|
|
Collapse a particular file range to nullify the hole. Extents beyond the range
|
|
[offset, offset+length] will be shifted to the beginning of hole. Hence this
|
|
command does not leave a hole, while \fI\-\-punch-hole\fP leaves a hole
|
|
instead of shifting extents. Both offset and length should be aligned to
|
|
the block size of filesystem.
|
|
.IP "\fB\-z, \-\-zero-range\fP"
|
|
Zero range in the file. Regions that span holes in the file will be
|
|
preallocated, this includes areas past EOF. Option
|
|
.B \-n
|
|
can be specified to prevent file length modification. Reads from the range
|
|
will return zeros. This option may not be specified at the same time as the
|
|
.B \-p
|
|
or
|
|
.B \-c
|
|
option.
|
|
.IP "\fB\-o, \-\-offset\fP \fIoffset\fP
|
|
Specifies the beginning offset of the allocation, in bytes.
|
|
.IP "\fB\-l, \-\-length\fP \fIlength\fP
|
|
Specifies the length of the allocation, 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 .
|