.\" Copyright (c) 2007 Silicon Graphics, Inc. All Rights Reserved
.\" Written by Dave Chinner <dgc@sgi.com>
+.\"
+.\" %%%LICENSE_START(GPLv2_ONELINE)
.\" May be distributed as per GNU General Public License version 2.
+.\" %%%LICENSE_END
.\"
.\" 2011-09-19: Added FALLOC_FL_PUNCH_HOLE
.\" 2011-09-19: Substantial restructuring of the page
.\"
-.TH FALLOCATE 2 2012-04-23 "Linux" "Linux Programmer's Manual"
+.TH FALLOCATE 2 2015-01-22 "Linux" "Linux Programmer's Manual"
.SH NAME
fallocate \- manipulate file space
.SH SYNOPSIS
.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 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.
.BR stat (2))
does not change.
-Not all file systems support
+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 *
+tmpfs (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.
+
+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 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
+.SS Zeroing file space
+Specifying the
+.BR FALLOC_FL_ZERO_RANGE
+flag (available since Linux 3.14)
+.\" commit 409332b65d3ed8cfa7a8030f1e9d52f372219642
+in
+.I mode
+zeroes 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 zeroes.
+
+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.
+
+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.
+
+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.14)
+.\" commit 376ba313147b4172f3e8cf620b9fb591f3e8cdfa
+.IP *
+ext4, for extent-based files (since Linux 3.14)
+.\" commit b8a8684502a0fc852afa0056c6bb2a9273f6fcc0
.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
.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_COLLAPSE_RANGE ,
+but either
+.I offset
+or
+.I len
+is not a multiple of the filesystem block size.
+.TP
+.B EINVAL
+.I mode
+contains both
+.B FALLOC_FL_COLLAPSE_RANGE
+and other flags;
+no other flags are permitted with
+.BR FALLOC_FL_COLLAPSE_RANGE .
+.TP
+.B EINVAL
+.I mode
+is
+.BR FALLOC_FL_COLLAPSE_RANGE
+or
+.BR FALLOC_FL_ZERO_RANGE ,
+but the file referred to by
+.I fd
+is not a regular file.
+.\" There was a 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
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 ,
+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.
Support is provided by glibc since version 2.10.
+The
+.BR FALLOC_FL_*
+flags are defined in glibc headers only since version 2.18.
+.\" See http://sourceware.org/bugzilla/show_bug.cgi?id=14964
.SH CONFORMING TO
.BR fallocate ()
is Linux-specific.
.SH SEE ALSO
+.BR fallocate (1),
.BR ftruncate (2),
.BR posix_fadvise (3),
.BR posix_fallocate (3)
+.SH COLOPHON
+This page is part of release 3.79 of the Linux
+.I man-pages
+project.
+A description of the project,
+information about reporting bugs,
+and the latest version of this page,
+can be found at
+\%http://www.kernel.org/doc/man\-pages/.
OSDN Git Service
