mirror of https://github.com/mkerrisk/man-pages
fallocate.2: Greatly expanded description of FALLOC_FL_COLLAPSE_RANGE
Reviewed-by: Christoph Hellwig <hch@infradead.org> Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
This commit is contained in:
Michael Kerrisk
parent
f78da076c9
commit
1ecfa5b30e
101
man2/fallocate.2
101
man2/fallocate.2
|
|
@ -1,6 +1,5 @@
|
|||
.\" Copyright (c) 2007 Silicon Graphics, Inc. All Rights Reserved
|
||||
.\" Written by Dave Chinner <dgc@sgi.com>
|
||||
.\" Updated by Namjae Jeon <namjae.jeon@samsung.com>
|
||||
.\"
|
||||
.\" %%%LICENSE_START(GPLv2_ONELINE)
|
||||
.\" May be distributed as per GNU General Public License version 2.
|
||||
|
|
@ -8,7 +7,6 @@
|
|||
.\"
|
||||
.\" 2011-09-19: Added FALLOC_FL_PUNCH_HOLE
|
||||
.\" 2011-09-19: Substantial restructuring of the page
|
||||
.\" 2014-02-19: Added FALLOC_FL_COLLAPSE_RANGE
|
||||
.\"
|
||||
.TH FALLOCATE 2 2014-04-17 "Linux" "Linux Programmer's Manual"
|
||||
.SH NAME
|
||||
|
|
@ -127,28 +125,61 @@ Btrfs (since Linux 3.7)
|
|||
tmpfs (since Linux 3.5)
|
||||
.\" commit 83e4fa9c16e4af7122e31be3eca5d57881d236fe
|
||||
.SS Collapsing file space
|
||||
.\" commit 00f5e61998dd17f5375d9dfc01331f104b83f841
|
||||
Specifying the
|
||||
.BR FALLOC_FL_COLLAPSE_RANGE
|
||||
flag in
|
||||
flag (available since Linux 3.15) in
|
||||
.I mode
|
||||
collapses space in the byte range starting at
|
||||
removes a byte range from a file, without leaving a hole.
|
||||
The byte range to be collapsed starts at
|
||||
.I offset
|
||||
and continuing for
|
||||
and continues for
|
||||
.I len
|
||||
bytes.
|
||||
Within the specified range, it first de-allocates blocks and eliminates
|
||||
the hole created in this process by shifting data blocks into the hole.
|
||||
At the completion of the operation,
|
||||
the contents of the file starting at the location
|
||||
.I offset+len
|
||||
will be appended at the location
|
||||
.IR offset ,
|
||||
and the file will be
|
||||
.I len
|
||||
bytes smaller.
|
||||
|
||||
Different filesystem may implement different limitations on the granularity of
|
||||
the operation.
|
||||
Most filesystem will limit operations to filesystem block size
|
||||
boundaries, but this boundary may be larger or smaller depending
|
||||
on the filesystem and/or the configuration of the filesystem or file.
|
||||
A filesystem may place limitations on the granularity of the operation,
|
||||
in order to ensure efficient implementation.
|
||||
Typically,
|
||||
.I offset
|
||||
and
|
||||
.I 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,
|
||||
.BR fallocate ()
|
||||
will fail with the error
|
||||
.BR EINVAL
|
||||
if this requirement is violated.
|
||||
|
||||
If a filesystem has such a limitation on granularity,
|
||||
it will fail with the error
|
||||
.BR EINVAL .
|
||||
If the region specified by
|
||||
.I offset
|
||||
plus
|
||||
.I len
|
||||
reaches or passes the end of file, an error is returned;
|
||||
instead, use
|
||||
.BR ftruncate (2)
|
||||
to truncate a file.
|
||||
|
||||
No other flags may be specified in
|
||||
.IR mode
|
||||
in conjunction with
|
||||
.BR FALLOC_FL_COLLAPSE_RANGE .
|
||||
|
||||
As at Linux 3.15,
|
||||
.B FALLOC_FL_COLLAPSE_RANGE
|
||||
is supported by
|
||||
ext4 (only for extent-based files)
|
||||
.\" commit 9eb79482a97152930b113b51dff530aba9e28c8e
|
||||
and XFS.
|
||||
.\" commit e1d8fb88a64c1f8094b9f6c3b6d2d9e6719c970d
|
||||
.SH RETURN VALUE
|
||||
On success,
|
||||
.BR fallocate ()
|
||||
|
|
@ -181,6 +212,36 @@ was less than 0, or
|
|||
.\" http://thread.gmane.org/gmane.linux.file-systems/48331/focus=1193526
|
||||
was less than or equal to 0.
|
||||
.TP
|
||||
.B EINVAL
|
||||
.I mode
|
||||
is
|
||||
.BR FALLOC_FL_COLLAPSE_RANGE
|
||||
and the range specified by
|
||||
.I offset
|
||||
plus
|
||||
.I len
|
||||
reaches or passes the end of the file.
|
||||
.TP
|
||||
.B EINVAL
|
||||
.I mode
|
||||
is
|
||||
.BR FALLOC_FL_COLLAPSE_RANGE ,
|
||||
but either
|
||||
.I offset
|
||||
or
|
||||
.I len
|
||||
is not a multiple of the filesystem block size.
|
||||
.TP
|
||||
.B EINVAL
|
||||
mode contains both
|
||||
.B FALLOC_FL_COLLAPSE_RANGE
|
||||
and other flags;
|
||||
no other flags are permitted with
|
||||
.BR FALLOC_FL_COLLAPSE_RANGE .
|
||||
.\" FIXME Document error when FALLOC_FL_COLLAPSE_RANGE
|
||||
.\" is given a nonregular file. As at 3.15-rc1, XFS gives
|
||||
.\" EINVAL, but ext4 gives EOPNOTSUPP.
|
||||
.TP
|
||||
.B EIO
|
||||
An I/O error occurred while reading from or writing to a filesystem.
|
||||
.TP
|
||||
|
|
@ -218,6 +279,8 @@ Or:
|
|||
.I mode
|
||||
specifies
|
||||
.BR FALLOC_FL_PUNCH_HOLE
|
||||
or
|
||||
.BR FALLOC_FL_COLLAPSE_RANGE
|
||||
and
|
||||
the file referred to by
|
||||
.I fd
|
||||
|
|
@ -228,6 +291,14 @@ is marked append-only
|
|||
.B ESPIPE
|
||||
.I fd
|
||||
refers to a pipe or FIFO.
|
||||
.TP
|
||||
.B ETXTBSY
|
||||
.I mode
|
||||
specifies
|
||||
.BR FALLOC_FL_COLLAPSE_RANGE ,
|
||||
but the file referred to by
|
||||
.IR fd
|
||||
is currently being executed.
|
||||
.SH VERSIONS
|
||||
.BR fallocate ()
|
||||
is available on Linux since kernel 2.6.23.
|
||||
|
|
|
|||
Loading…
Reference in New Issue