.\" 2011-09-19: Added FALLOC_FL_PUNCH_HOLE
.\" 2011-09-19: Substantial restructuring of the page
.\"
-.TH FALLOCATE 2 2013-02-12 "Linux" "Linux Programmer's Manual"
+.TH FALLOCATE 2 2018-04-30 "Linux" "Linux Programmer's Manual"
.SH NAME
fallocate \- manipulate file space
.SH SYNOPSIS
.nf
.BR "#define _GNU_SOURCE" " /* See feature_test_macros(7) */"
.B #include <fcntl.h>
-
+.PP
.BI "int fallocate(int " fd ", int " mode ", off_t " offset \
", off_t " len ");
.fi
For the portable, POSIX.1-specified method of ensuring that space
is allocated for a file, see
.BR posix_fallocate (3).
-
+.PP
.BR fallocate ()
allows the caller to directly manipulate the allocated disk space
for the file referred to by
and continuing for
.I len
bytes.
-
+.PP
The
.I mode
argument determines the operation to be performed on the given range.
.I mode
is zero) of
.BR fallocate ()
-allocates and initializes to zero the disk space
-within the range specified by
+allocates the disk space within the range specified by
.I offset
and
.IR len .
will be changed if
.IR offset + len
is greater than the file size.
+Any subregion within the range specified by
+.I offset
+and
+.IR len
+that did not contain data before the call will be initialized to zero.
This default behavior closely resembles the behavior of the
.BR posix_fallocate (3)
library function,
and is intended as a method of optimally implementing that function.
-
+.PP
After a successful call, subsequent writes into the range specified by
.IR offset
and
.IR len
are guaranteed not to fail because of lack of disk space.
-
+.PP
If the
.B FALLOC_FL_KEEP_SIZE
flag is specified in
Preallocating zeroed blocks beyond the end of the file in this manner
is useful for optimizing append workloads.
.PP
+If the
+.B FALLOC_FL_UNSHARE
+flag is specified in
+.IR mode ,
+shared file data extents will be made private to the file to guarantee
+that a subsequent write will not fail due to lack of space.
+Typically, this will be done by performing a copy-on-write operation on
+all shared data in the file.
+This flag may not be supported by all filesystems.
+.PP
Because allocation is done in block size chunks,
.BR fallocate ()
may allocate a larger range of disk space than was specified.
and continuing for
.I len
bytes.
-Within the specified range, partial file system blocks are zeroed,
-and whole file system blocks are removed from the file.
+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.
-
+subsequent reads from this range will return zeros.
+.PP
The
.BR FALLOC_FL_PUNCH_HOLE
flag must be ORed with
(as reported by
.BR stat (2))
does not change.
-
-Not all file systems support
+.PP
+Not all filesystems support
.BR FALLOC_FL_PUNCH_HOLE ;
-if a file system doesn't support the operation, an error is returned.
+if a filesystem doesn't support the operation, an error is returned.
+The operation is supported on at least the following filesystems:
+.IP * 3
+XFS (since Linux 2.6.38)
+.IP *
+ext4 (since Linux 3.0)
+.\" commit a4bb6b64e39abc0e41ca077725f2a72c868e7622
+.IP *
+Btrfs (since Linux 3.7)
+.IP *
+.BR tmpfs (5)
+(since Linux 3.5)"
+.\" commit 83e4fa9c16e4af7122e31be3eca5d57881d236fe
+.SS Collapsing file space
+.\" commit 00f5e61998dd17f5375d9dfc01331f104b83f841
+Specifying the
+.BR FALLOC_FL_COLLAPSE_RANGE
+flag (available since Linux 3.15) in
+.I mode
+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 len
+bytes.
+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.
+.PP
+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 ()
+fails with the error
+.BR EINVAL
+if this requirement is violated.
+.PP
+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.
+.PP
+No other flags may be specified in
+.IR mode
+in conjunction with
+.BR FALLOC_FL_COLLAPSE_RANGE .
+.PP
+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
+.SS Zeroing file space
+Specifying the
+.BR FALLOC_FL_ZERO_RANGE
+flag (available since Linux 3.15)
+.\" commit 409332b65d3ed8cfa7a8030f1e9d52f372219642
+in
+.I mode
+zeros space in the byte range starting at
+.I offset
+and continuing for
+.I len
+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 zeros.
+.PP
+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.
+.PP
+If the
+.B FALLOC_FL_KEEP_SIZE
+flag is additionally specified in
+.IR mode ,
+the behavior of the call is similar,
+but the file size will not be changed even if
+.IR offset + len
+is greater than the file size.
+This behavior is the same as when preallocating space with
+.B FALLOC_FL_KEEP_SIZE
+specified.
+.PP
+Not all filesystems support
+.BR FALLOC_FL_ZERO_RANGE ;
+if a filesystem doesn't support the operation, an error is returned.
+The operation is supported on at least the following filesystems:
+.IP * 3
+XFS (since Linux 3.15)
+.\" commit 376ba313147b4172f3e8cf620b9fb591f3e8cdfa
+.IP *
+ext4, for extent-based files (since Linux 3.15)
+.\" commit b8a8684502a0fc852afa0056c6bb2a9273f6fcc0
+.IP *
+SMB3 (since Linux 3.17)
+.\" commit 30175628bf7f521e9ee31ac98fa6d6fe7441a556
+.IP *
+Btrfs (since Linux 4.16)
+.\" commit f27451f229966874a8793995b8e6b74326d125df
+.SS Increasing file space
+Specifying the
+.BR FALLOC_FL_INSERT_RANGE
+flag
+(available since Linux 4.1)
+.\" commit dd46c787788d5bf5b974729d43e4c405814a4c7d
+in
+.I mode
+increases the file space by inserting a hole within the file size without
+overwriting any existing data.
+The hole will start at
+.I offset
+and continue for
+.I len
+bytes.
+When inserting the hole inside file, the contents of the file starting at
+.I offset
+will be shifted upward (i.e., to a higher file offset) by
+.I len
+bytes.
+Inserting a hole inside a file increases the file size by
+.I len
+bytes.
+.PP
+This mode has the same limitations as
+.BR FALLOC_FL_COLLAPSE_RANGE
+regarding the granularity of the operation.
+If the granularity requirements are not met,
+.BR fallocate ()
+fails with the error
+.BR EINVAL .
+If the
+.I offset
+is equal to or greater than the end of file, an error is returned.
+For such operations (i.e., inserting a hole at the end of file),
+.BR ftruncate (2)
+should be used.
+.PP
+No other flags may be specified in
+.IR mode
+in conjunction with
+.BR FALLOC_FL_INSERT_RANGE .
+.PP
+.B FALLOC_FL_INSERT_RANGE
+requires filesystem support.
+Filesystems that support this operation include
+XFS (since Linux 4.1)
+.\" commit a904b1ca5751faf5ece8600e18cd3b674afcca1b
+and ext4 (since Linux 4.2).
+.\" commit 331573febb6a224bc50322e3670da326cb7f4cfc
+.\" f2fs also has support since Linux 4.2
+.\" commit f62185d0e283e9d311e3ac1020f159d95f0aab39
.SH RETURN VALUE
+On success,
.BR fallocate ()
-returns zero on success, and \-1 on failure.
+returns zero.
+On error, \-1 is returned and
+.I errno
+is set to indicate the error.
.SH ERRORS
.TP
.B EBADF
.IR offset + len
exceeds the maximum file size.
.TP
+.B EFBIG
+.I mode
+is
+.BR FALLOC_FL_INSERT_RANGE ,
+and the current file size+\fIlen\fP exceeds the maximum file size.
+.TP
.B EINTR
-A signal was caught during execution.
+A signal was caught during execution; see
+.BR signal (7).
.TP
.B EINVAL
.I offset
was less than 0, or
.I len
-.\" FIXME (raise a kernel bug) Probably the len==0 case should be
+.\" FIXME . (raise a kernel bug) Probably the len==0 case should be
.\" a no-op, rather than an error. That would be consistent with
.\" similar APIs for the len==0 case.
.\" See "Re: [PATCH] fallocate.2: add FALLOC_FL_PUNCH_HOLE flag definition"
.\" 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_INSERT_RANGE
+and the range specified by
+.I offset
+reaches or passes the end of the file.
+.TP
+.B EINVAL
+.I mode
+is
+.BR FALLOC_FL_COLLAPSE_RANGE
+or
+.BR FALLOC_FL_INSERT_RANGE ,
+but either
+.I offset
+or
+.I len
+is not a multiple of the filesystem block size.
+.TP
+.B EINVAL
+.I mode
+contains one of
+.B FALLOC_FL_COLLAPSE_RANGE
+or
+.B FALLOC_FL_INSERT_RANGE
+and also other flags;
+no other flags are permitted with
+.BR FALLOC_FL_COLLAPSE_RANGE
+or
+.BR FALLOC_FL_INSERT_RANGE .
+.TP
+.B EINVAL
+.I mode
+is
+.BR FALLOC_FL_COLLAPSE_RANGE
+or
+.BR FALLOC_FL_ZERO_RANGE
+or
+.BR FALLOC_FL_INSERT_RANGE ,
+but the file referred to by
+.I fd
+is not a regular file.
+.\" There was an inconsistency in 3.15-rc1, that should be resolved so that all
+.\" filesystems use this error for this case. (Tytso says ex4 will change.)
+.\" http://thread.gmane.org/gmane.comp.file-systems.xfs.general/60485/focus=5521
+.\" From: Michael Kerrisk (man-pages <mtk.manpages@...>
+.\" Subject: Re: [PATCH v5 10/10] manpage: update FALLOC_FL_COLLAPSE_RANGE flag in fallocate
+.\" Newsgroups: gmane.linux.man, gmane.linux.file-systems
+.\" Date: 2014-04-17 13:40:05 GMT
+.TP
.B EIO
-An I/O error occurred while reading from or writing to a file system.
+An I/O error occurred while reading from or writing to a filesystem.
.TP
.B ENODEV
.I fd
.BR fallocate ().
.TP
.B EOPNOTSUPP
-The file system containing the file referred to by
+The filesystem containing the file referred to by
.I fd
does not support this operation;
or the
.I mode
-is not supported by the file system containing the file referred to by
+is not supported by the filesystem containing the file referred to by
.IR fd .
.TP
.B EPERM
.I fd
is marked immutable (see
.BR chattr (1)).
-Or:
+.TP
+.B EPERM
.I mode
specifies
.BR FALLOC_FL_PUNCH_HOLE
+or
+.BR FALLOC_FL_COLLAPSE_RANGE
+or
+.BR FALLOC_FL_INSERT_RANGE
and
the file referred to by
.I fd
(see
.BR chattr (1)).
.TP
+.B EPERM
+The operation was prevented by a file seal; see
+.BR fcntl (2).
+.TP
.B ESPIPE
.I fd
refers to a pipe or FIFO.
+.TP
+.B ETXTBSY
+.I mode
+specifies
+.BR FALLOC_FL_COLLAPSE_RANGE
+or
+.BR FALLOC_FL_INSERT_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.
projects / thirdparty / man-pages.git / blobdiff