1fallocate(2) System Calls Manual fallocate(2)
2
6 fallocate - manipulate file space
7
9 Standard C library (libc, -lc)
10
12 #define _GNU_SOURCE /* See feature_test_macros(7) */
13 #include <fcntl.h>
14 int fallocate(int fd, int mode, off_t offset, off_t len);
16
18 This is a nonportable, Linux-specific system call. For the portable,
19 POSIX.1-specified method of ensuring that space is allocated for a
20 file, see posix_fallocate(3).
21 fallocate() allows the caller to directly manipulate the allocated disk
23 space for the file referred to by fd for the byte range starting at
24 offset and continuing for len bytes.
25 The mode argument determines the operation to be performed on the given
27 range. Details of the supported operations are given in the subsec‐
28 tions below.
29 Allocating disk space
31 The default operation (i.e., mode is zero) of fallocate() allocates the
32 disk space within the range specified by offset and len. The file size
33 (as reported by stat(2)) will be changed if offset+len is greater than
34 the file size. Any subregion within the range specified by offset and
35 len that did not contain data before the call will be initialized to
36 zero. This default behavior closely resembles the behavior of the
37 posix_fallocate(3) library function, and is intended as a method of op‐
38 timally implementing that function.
39 After a successful call, subsequent writes into the range specified by
41 offset and len are guaranteed not to fail because of lack of disk
42 space.
43 If the FALLOC_FL_KEEP_SIZE flag is specified in mode, the behavior of
45 the call is similar, but the file size will not be changed even if off‐
46 set+len is greater than the file size. Preallocating zeroed blocks be‐
47 yond the end of the file in this manner is useful for optimizing append
48 workloads.
49 If the FALLOC_FL_UNSHARE_RANGE flag is specified in mode, shared file
51 data extents will be made private to the file to guarantee that a sub‐
52 sequent write will not fail due to lack of space. Typically, this will
53 be done by performing a copy-on-write operation on all shared data in
54 the file. This flag may not be supported by all filesystems.
55 Because allocation is done in block size chunks, fallocate() may allo‐
57 cate a larger range of disk space than was specified.
58 Deallocating file space
60 Specifying the FALLOC_FL_PUNCH_HOLE flag (available since Linux 2.6.38)
61 in mode deallocates space (i.e., creates a hole) in the byte range
62 starting at offset and continuing for len bytes. Within the specified
63 range, partial filesystem blocks are zeroed, and whole filesystem
64 blocks are removed from the file. After a successful call, subsequent
65 reads from this range will return zeros.
66 The FALLOC_FL_PUNCH_HOLE flag must be ORed with FALLOC_FL_KEEP_SIZE in
68 mode; in other words, even when punching off the end of the file, the
69 file size (as reported by stat(2)) does not change.
70 Not all filesystems support FALLOC_FL_PUNCH_HOLE; if a filesystem
72 doesn't support the operation, an error is returned. The operation is
73 supported on at least the following filesystems:
74 • XFS (since Linux 2.6.38)
76 • ext4 (since Linux 3.0)
78 • Btrfs (since Linux 3.7)
80 • tmpfs(5) (since Linux 3.5)
82 • gfs2(5) (since Linux 4.16)
84 Collapsing file space
86 Specifying the FALLOC_FL_COLLAPSE_RANGE flag (available since Linux
87 3.15) in mode removes a byte range from a file, without leaving a hole.
88 The byte range to be collapsed starts at offset and continues for len
89 bytes. At the completion of the operation, the contents of the file
90 starting at the location offset+len will be appended at the location
91 offset, and the file will be len bytes smaller.
92 A filesystem may place limitations on the granularity of the operation,
94 in order to ensure efficient implementation. Typically, offset and len
95 must be a multiple of the filesystem logical block size, which varies
96 according to the filesystem type and configuration. If a filesystem
97 has such a requirement, fallocate() fails with the error EINVAL if this
98 requirement is violated.
99 If the region specified by offset plus len reaches or passes the end of
101 file, an error is returned; instead, use ftruncate(2) to truncate a
102 file.
103 No other flags may be specified in mode in conjunction with FAL‐
105 LOC_FL_COLLAPSE_RANGE.
106 As at Linux 3.15, FALLOC_FL_COLLAPSE_RANGE is supported by ext4 (only
108 for extent-based files) and XFS.
109 Zeroing file space
111 Specifying the FALLOC_FL_ZERO_RANGE flag (available since Linux 3.15)
112 in mode zeros space in the byte range starting at offset and continuing
113 for len bytes. Within the specified range, blocks are preallocated for
114 the regions that span the holes in the file. After a successful call,
115 subsequent reads from this range will return zeros.
116 Zeroing is done within the filesystem preferably by converting the
118 range into unwritten extents. This approach means that the specified
119 range will not be physically zeroed out on the device (except for par‐
120 tial blocks at the either end of the range), and I/O is (otherwise) re‐
121 quired only to update metadata.
122 If the FALLOC_FL_KEEP_SIZE flag is additionally specified in mode, the
124 behavior of the call is similar, but the file size will not be changed
125 even if offset+len is greater than the file size. This behavior is the
126 same as when preallocating space with FALLOC_FL_KEEP_SIZE specified.
127 Not all filesystems support FALLOC_FL_ZERO_RANGE; if a filesystem
129 doesn't support the operation, an error is returned. The operation is
130 supported on at least the following filesystems:
131 • XFS (since Linux 3.15)
133 • ext4, for extent-based files (since Linux 3.15)
135 • SMB3 (since Linux 3.17)
137 • Btrfs (since Linux 4.16)
139 Increasing file space
141 Specifying the FALLOC_FL_INSERT_RANGE flag (available since Linux 4.1)
142 in mode increases the file space by inserting a hole within the file
143 size without overwriting any existing data. The hole will start at
144 offset and continue for len bytes. When inserting the hole inside
145 file, the contents of the file starting at offset will be shifted up‐
146 ward (i.e., to a higher file offset) by len bytes. Inserting a hole
147 inside a file increases the file size by len bytes.
148 This mode has the same limitations as FALLOC_FL_COLLAPSE_RANGE regard‐
150 ing the granularity of the operation. If the granularity requirements
151 are not met, fallocate() fails with the error EINVAL. If the offset is
152 equal to or greater than the end of file, an error is returned. For
153 such operations (i.e., inserting a hole at the end of file), ftrun‐
154 cate(2) should be used.
155 No other flags may be specified in mode in conjunction with FAL‐
157 LOC_FL_INSERT_RANGE.
158 FALLOC_FL_INSERT_RANGE requires filesystem support. Filesystems that
160 support this operation include XFS (since Linux 4.1) and ext4 (since
161 Linux 4.2).
162
164 On success, fallocate() returns zero. On error, -1 is returned and er‐
165 rno is set to indicate the error.
166
168 EBADF fd is not a valid file descriptor, or is not opened for writing.
169 EFBIG offset+len exceeds the maximum file size.
171 EFBIG mode is FALLOC_FL_INSERT_RANGE, and the current file size+len
173 exceeds the maximum file size.
174 EINTR A signal was caught during execution; see signal(7).
176 EINVAL offset was less than 0, or len was less than or equal to 0.
178 EINVAL mode is FALLOC_FL_COLLAPSE_RANGE and the range specified by off‐
180 set plus len reaches or passes the end of the file.
181 EINVAL mode is FALLOC_FL_INSERT_RANGE and the range specified by offset
183 reaches or passes the end of the file.
184 EINVAL mode is FALLOC_FL_COLLAPSE_RANGE or FALLOC_FL_INSERT_RANGE, but
186 either offset or len is not a multiple of the filesystem block
187 size.
188 EINVAL mode contains one of FALLOC_FL_COLLAPSE_RANGE or FALLOC_FL_IN‐
190 SERT_RANGE and also other flags; no other flags are permitted
191 with FALLOC_FL_COLLAPSE_RANGE or FALLOC_FL_INSERT_RANGE.
192 EINVAL mode is FALLOC_FL_COLLAPSE_RANGE, FALLOC_FL_ZERO_RANGE, or FAL‐
194 LOC_FL_INSERT_RANGE, but the file referred to by fd is not a
195 regular file.
196 EIO An I/O error occurred while reading from or writing to a
198 filesystem.
199 ENODEV fd does not refer to a regular file or a directory. (If fd is a
201 pipe or FIFO, a different error results.)
202 ENOSPC There is not enough space left on the device containing the file
204 referred to by fd.
205 ENOSYS This kernel does not implement fallocate().
207 EOPNOTSUPP
209 The filesystem containing the file referred to by fd does not
210 support this operation; or the mode is not supported by the
211 filesystem containing the file referred to by fd.
212 EPERM The file referred to by fd is marked immutable (see chattr(1)).
214 EPERM mode specifies FALLOC_FL_PUNCH_HOLE, FALLOC_FL_COLLAPSE_RANGE,
216 or FALLOC_FL_INSERT_RANGE and the file referred to by fd is
217 marked append-only (see chattr(1)).
218 EPERM The operation was prevented by a file seal; see fcntl(2).
220 ESPIPE fd refers to a pipe or FIFO.
222 ETXTBSY
224 mode specifies FALLOC_FL_COLLAPSE_RANGE or FALLOC_FL_IN‐
225 SERT_RANGE, but the file referred to by fd is currently being
226 executed.
227
229 Linux.
230
232 fallocate()
233 Linux 2.6.23, glibc 2.10.
234 FALLOC_FL_*
236 glibc 2.18.
237
239 fallocate(1), ftruncate(2), posix_fadvise(3), posix_fallocate(3)
240Linux man-pages 6.05 2023-03-30 fallocate(2)