| .\" 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 2019-11-19 "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 |
| .SH DESCRIPTION |
| This is a nonportable, Linux-specific system call. |
| 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 |
| .I fd |
| for the byte range starting at |
| .I offset |
| and continuing for |
| .I len |
| bytes. |
| .PP |
| The |
| .I mode |
| argument determines the operation to be performed on the given range. |
| Details of the supported operations are given in the subsections below. |
| .SS Allocating disk space |
| The default operation (i.e., |
| .I mode |
| is zero) of |
| .BR fallocate () |
| allocates the disk space within the range specified by |
| .I offset |
| and |
| .IR len . |
| The file size (as reported by |
| .BR stat (2)) |
| 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 |
| .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. |
| 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. |
| .SS Deallocating file space |
| Specifying the |
| .BR FALLOC_FL_PUNCH_HOLE |
| flag (available since Linux 2.6.38) in |
| .I mode |
| deallocates space (i.e., creates a hole) |
| in the byte range starting at |
| .I offset |
| and continuing for |
| .I len |
| 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 zeros. |
| .PP |
| The |
| .BR FALLOC_FL_PUNCH_HOLE |
| flag must be ORed with |
| .BR FALLOC_FL_KEEP_SIZE |
| in |
| .IR mode ; |
| in other words, even when punching off the end of the file, the file size |
| (as reported by |
| .BR stat (2)) |
| does not change. |
| .PP |
| Not all filesystems support |
| .BR FALLOC_FL_PUNCH_HOLE ; |
| 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 |
| .IP * |
| .BR gfs2 (5) |
| (since Linux 4.16) |
| .\" commit 4e56a6411fbce6f859566e17298114c2434391a4 |
| .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 error, \-1 is returned and |
| .I errno |
| is set to indicate the error. |
| .SH ERRORS |
| .TP |
| .B EBADF |
| .I fd |
| is not a valid file descriptor, or is not opened for writing. |
| .TP |
| .B EFBIG |
| .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; 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 |
| .\" 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" |
| .\" 21 Sep 2012 |
| .\" 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 filesystem. |
| .TP |
| .B ENODEV |
| .I fd |
| does not refer to a regular file or a directory. |
| (If |
| .I fd |
| is a pipe or FIFO, a different error results.) |
| .TP |
| .B ENOSPC |
| There is not enough space left on the device containing the file |
| referred to by |
| .IR fd . |
| .TP |
| .B ENOSYS |
| This kernel does not implement |
| .BR fallocate (). |
| .TP |
| .B EOPNOTSUPP |
| The filesystem containing the file referred to by |
| .I fd |
| does not support this operation; |
| or the |
| .I mode |
| is not supported by the filesystem containing the file referred to by |
| .IR fd . |
| .TP |
| .B EPERM |
| The file referred to by |
| .I fd |
| is marked immutable (see |
| .BR chattr (1)). |
| .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 |
| is marked append-only |
| (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. |
| 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) |