| blob | 4b81d23e31ea8b6697b492c6020cb5292897a101 |
1 .\" Copyright (c) 2007 Silicon Graphics, Inc. All Rights Reserved
2 .\" Written by Dave Chinner <dgc@sgi.com>
3 .\"
4 .\" SPDX-License-Identifier: GPL-2.0-only
5 .\"
6 .\" 2011-09-19: Added FALLOC_FL_PUNCH_HOLE
7 .\" 2011-09-19: Substantial restructuring of the page
8 .\"
9 .TH FALLOCATE 2 2022-09-09 "Linux man-pages (unreleased)"
10 .SH NAME
11 fallocate \- manipulate file space
12 .SH LIBRARY
13 Standard C library
14 .RI ( libc ", " \-lc )
15 .SH SYNOPSIS
16 .nf
17 .BR "#define _GNU_SOURCE" " /* See feature_test_macros(7) */"
18 .B #include <fcntl.h>
19 .PP
20 .BI "int fallocate(int " fd ", int " mode ", off_t " offset \
21 ", off_t " len ");"
22 .fi
23 .SH DESCRIPTION
24 This is a nonportable, Linux-specific system call.
25 For the portable, POSIX.1-specified method of ensuring that space
26 is allocated for a file, see
27 .BR posix_fallocate (3).
28 .PP
29 .BR fallocate ()
30 allows the caller to directly manipulate the allocated disk space
31 for the file referred to by
32 .I fd
33 for the byte range starting at
34 .I offset
35 and continuing for
36 .I len
37 bytes.
38 .PP
39 The
40 .I mode
41 argument determines the operation to be performed on the given range.
42 Details of the supported operations are given in the subsections below.
43 .SS Allocating disk space
44 The default operation (i.e.,
45 .I mode
46 is zero) of
47 .BR fallocate ()
48 allocates the disk space within the range specified by
49 .I offset
50 and
51 .IR len .
52 The file size (as reported by
53 .BR stat (2))
54 will be changed if
55 .IR offset + len
56 is greater than the file size.
57 Any subregion within the range specified by
58 .I offset
59 and
60 .I len
61 that did not contain data before the call will be initialized to zero.
62 This default behavior closely resembles the behavior of the
63 .BR posix_fallocate (3)
64 library function,
65 and is intended as a method of optimally implementing that function.
66 .PP
67 After a successful call, subsequent writes into the range specified by
68 .I offset
69 and
70 .I len
71 are guaranteed not to fail because of lack of disk space.
72 .PP
73 If the
74 .B FALLOC_FL_KEEP_SIZE
75 flag is specified in
76 .IR mode ,
77 the behavior of the call is similar,
78 but the file size will not be changed even if
79 .IR offset + len
80 is greater than the file size.
81 Preallocating zeroed blocks beyond the end of the file in this manner
82 is useful for optimizing append workloads.
83 .PP
84 If the
85 .B FALLOC_FL_UNSHARE_RANGE
86 flag is specified in
87 .IR mode ,
88 shared file data extents will be made private to the file to guarantee
89 that a subsequent write will not fail due to lack of space.
90 Typically, this will be done by performing a copy-on-write operation on
91 all shared data in the file.
92 This flag may not be supported by all filesystems.
93 .PP
94 Because allocation is done in block size chunks,
95 .BR fallocate ()
96 may allocate a larger range of disk space than was specified.
97 .SS Deallocating file space
98 Specifying the
99 .B FALLOC_FL_PUNCH_HOLE
100 flag (available since Linux 2.6.38) in
101 .I mode
102 deallocates space (i.e., creates a hole)
103 in the byte range starting at
104 .I offset
105 and continuing for
106 .I len
107 bytes.
108 Within the specified range, partial filesystem blocks are zeroed,
109 and whole filesystem blocks are removed from the file.
110 After a successful call,
111 subsequent reads from this range will return zeros.
112 .PP
113 The
114 .B FALLOC_FL_PUNCH_HOLE
115 flag must be ORed with
116 .B FALLOC_FL_KEEP_SIZE
117 in
118 .IR mode ;
119 in other words, even when punching off the end of the file, the file size
120 (as reported by
121 .BR stat (2))
122 does not change.
123 .PP
124 Not all filesystems support
125 .BR FALLOC_FL_PUNCH_HOLE ;
126 if a filesystem doesn't support the operation, an error is returned.
127 The operation is supported on at least the following filesystems:
128 .IP * 3
129 XFS (since Linux 2.6.38)
130 .IP *
131 ext4 (since Linux 3.0)
132 .\" commit a4bb6b64e39abc0e41ca077725f2a72c868e7622
133 .IP *
134 Btrfs (since Linux 3.7)
135 .IP *
136 .BR tmpfs (5)
137 (since Linux 3.5)
138 .\" commit 83e4fa9c16e4af7122e31be3eca5d57881d236fe
139 .IP *
140 .BR gfs2 (5)
141 (since Linux 4.16)
142 .\" commit 4e56a6411fbce6f859566e17298114c2434391a4
143 .SS Collapsing file space
144 .\" commit 00f5e61998dd17f5375d9dfc01331f104b83f841
145 Specifying the
146 .B FALLOC_FL_COLLAPSE_RANGE
147 flag (available since Linux 3.15) in
148 .I mode
149 removes a byte range from a file, without leaving a hole.
150 The byte range to be collapsed starts at
151 .I offset
152 and continues for
153 .I len
154 bytes.
155 At the completion of the operation,
156 the contents of the file starting at the location
157 .I offset+len
158 will be appended at the location
159 .IR offset ,
160 and the file will be
161 .I len
162 bytes smaller.
163 .PP
164 A filesystem may place limitations on the granularity of the operation,
165 in order to ensure efficient implementation.
166 Typically,
167 .I offset
168 and
169 .I len
170 must be a multiple of the filesystem logical block size,
171 which varies according to the filesystem type and configuration.
172 If a filesystem has such a requirement,
173 .BR fallocate ()
174 fails with the error
175 .B EINVAL
176 if this requirement is violated.
177 .PP
178 If the region specified by
179 .I offset
180 plus
181 .I len
182 reaches or passes the end of file, an error is returned;
183 instead, use
184 .BR ftruncate (2)
185 to truncate a file.
186 .PP
187 No other flags may be specified in
188 .I mode
189 in conjunction with
190 .BR FALLOC_FL_COLLAPSE_RANGE .
191 .PP
192 As at Linux 3.15,
193 .B FALLOC_FL_COLLAPSE_RANGE
194 is supported by
195 ext4 (only for extent-based files)
196 .\" commit 9eb79482a97152930b113b51dff530aba9e28c8e
197 and XFS.
198 .\" commit e1d8fb88a64c1f8094b9f6c3b6d2d9e6719c970d
199 .SS Zeroing file space
200 Specifying the
201 .B FALLOC_FL_ZERO_RANGE
202 flag (available since Linux 3.15)
203 .\" commit 409332b65d3ed8cfa7a8030f1e9d52f372219642
204 in
205 .I mode
206 zeros space in the byte range starting at
207 .I offset
208 and continuing for
209 .I len
210 bytes.
211 Within the specified range, blocks are preallocated for the regions
212 that span the holes in the file.
213 After a successful call, subsequent
214 reads from this range will return zeros.
215 .PP
216 Zeroing is done within the filesystem preferably by converting the range into
217 unwritten extents.
218 This approach means that the specified range will not be physically zeroed
219 out on the device (except for partial blocks at the either end of the range),
220 and I/O is (otherwise) required only to update metadata.
221 .PP
222 If the
223 .B FALLOC_FL_KEEP_SIZE
224 flag is additionally specified in
225 .IR mode ,
226 the behavior of the call is similar,
227 but the file size will not be changed even if
228 .IR offset + len
229 is greater than the file size.
230 This behavior is the same as when preallocating space with
231 .B FALLOC_FL_KEEP_SIZE
232 specified.
233 .PP
234 Not all filesystems support
235 .BR FALLOC_FL_ZERO_RANGE ;
236 if a filesystem doesn't support the operation, an error is returned.
237 The operation is supported on at least the following filesystems:
238 .IP * 3
239 XFS (since Linux 3.15)
240 .\" commit 376ba313147b4172f3e8cf620b9fb591f3e8cdfa
241 .IP *
242 ext4, for extent-based files (since Linux 3.15)
243 .\" commit b8a8684502a0fc852afa0056c6bb2a9273f6fcc0
244 .IP *
245 SMB3 (since Linux 3.17)
246 .\" commit 30175628bf7f521e9ee31ac98fa6d6fe7441a556
247 .IP *
248 Btrfs (since Linux 4.16)
249 .\" commit f27451f229966874a8793995b8e6b74326d125df
250 .SS Increasing file space
251 Specifying the
252 .B FALLOC_FL_INSERT_RANGE
253 flag
254 (available since Linux 4.1)
255 .\" commit dd46c787788d5bf5b974729d43e4c405814a4c7d
256 in
257 .I mode
258 increases the file space by inserting a hole within the file size without
259 overwriting any existing data.
260 The hole will start at
261 .I offset
262 and continue for
263 .I len
264 bytes.
265 When inserting the hole inside file, the contents of the file starting at
266 .I offset
267 will be shifted upward (i.e., to a higher file offset) by
268 .I len
269 bytes.
270 Inserting a hole inside a file increases the file size by
271 .I len
272 bytes.
273 .PP
274 This mode has the same limitations as
275 .B FALLOC_FL_COLLAPSE_RANGE
276 regarding the granularity of the operation.
277 If the granularity requirements are not met,
278 .BR fallocate ()
279 fails with the error
280 .BR EINVAL .
281 If the
282 .I offset
283 is equal to or greater than the end of file, an error is returned.
284 For such operations (i.e., inserting a hole at the end of file),
285 .BR ftruncate (2)
286 should be used.
287 .PP
288 No other flags may be specified in
289 .I mode
290 in conjunction with
291 .BR FALLOC_FL_INSERT_RANGE .
292 .PP
293 .B FALLOC_FL_INSERT_RANGE
294 requires filesystem support.
295 Filesystems that support this operation include
296 XFS (since Linux 4.1)
297 .\" commit a904b1ca5751faf5ece8600e18cd3b674afcca1b
298 and ext4 (since Linux 4.2).
299 .\" commit 331573febb6a224bc50322e3670da326cb7f4cfc
300 .\" f2fs also has support since Linux 4.2
301 .\" commit f62185d0e283e9d311e3ac1020f159d95f0aab39
302 .SH RETURN VALUE
303 On success,
304 .BR fallocate ()
305 returns zero.
306 On error, \-1 is returned and
307 .I errno
308 is set to indicate the error.
309 .SH ERRORS
310 .TP
311 .B EBADF
312 .I fd
313 is not a valid file descriptor, or is not opened for writing.
314 .TP
315 .B EFBIG
316 .IR offset + len
317 exceeds the maximum file size.
318 .TP
319 .B EFBIG
320 .I mode
321 is
322 .BR FALLOC_FL_INSERT_RANGE ,
323 and the current file size+\fIlen\fP exceeds the maximum file size.
324 .TP
325 .B EINTR
326 A signal was caught during execution; see
327 .BR signal (7).
328 .TP
329 .B EINVAL
330 .I offset
331 was less than 0, or
332 .I len
333 .\" FIXME . (raise a kernel bug) Probably the len==0 case should be
334 .\" a no-op, rather than an error. That would be consistent with
335 .\" similar APIs for the len==0 case.
336 .\" See "Re: [PATCH] fallocate.2: add FALLOC_FL_PUNCH_HOLE flag definition"
337 .\" 21 Sep 2012
338 .\" http://thread.gmane.org/gmane.linux.file-systems/48331/focus=1193526
339 was less than or equal to 0.
340 .TP
341 .B EINVAL
342 .I mode
343 is
344 .B FALLOC_FL_COLLAPSE_RANGE
345 and the range specified by
346 .I offset
347 plus
348 .I len
349 reaches or passes the end of the file.
350 .TP
351 .B EINVAL
352 .I mode
353 is
354 .B FALLOC_FL_INSERT_RANGE
355 and the range specified by
356 .I offset
357 reaches or passes the end of the file.
358 .TP
359 .B EINVAL
360 .I mode
361 is
362 .B FALLOC_FL_COLLAPSE_RANGE
363 or
364 .BR FALLOC_FL_INSERT_RANGE ,
365 but either
366 .I offset
367 or
368 .I len
369 is not a multiple of the filesystem block size.
370 .TP
371 .B EINVAL
372 .I mode
373 contains one of
374 .B FALLOC_FL_COLLAPSE_RANGE
375 or
376 .B FALLOC_FL_INSERT_RANGE
377 and also other flags;
378 no other flags are permitted with
379 .B FALLOC_FL_COLLAPSE_RANGE
380 or
381 .BR FALLOC_FL_INSERT_RANGE .
382 .TP
383 .B EINVAL
384 .I mode
385 is
386 .BR FALLOC_FL_COLLAPSE_RANGE ,
387 .BR FALLOC_FL_ZERO_RANGE ,
388 or
389 .BR FALLOC_FL_INSERT_RANGE ,
390 but the file referred to by
391 .I fd
392 is not a regular file.
393 .\" There was an inconsistency in 3.15-rc1, that should be resolved so that all
394 .\" filesystems use this error for this case. (Tytso says ex4 will change.)
395 .\" http://thread.gmane.org/gmane.comp.file-systems.xfs.general/60485/focus=5521
396 .\" From: Michael Kerrisk (man-pages <mtk.manpages@...>
397 .\" Subject: Re: [PATCH v5 10/10] manpage: update FALLOC_FL_COLLAPSE_RANGE flag in fallocate
398 .\" Newsgroups: gmane.linux.man, gmane.linux.file-systems
399 .\" Date: 2014-04-17 13:40:05 GMT
400 .TP
401 .B EIO
402 An I/O error occurred while reading from or writing to a filesystem.
403 .TP
404 .B ENODEV
405 .I fd
406 does not refer to a regular file or a directory.
407 (If
408 .I fd
409 is a pipe or FIFO, a different error results.)
410 .TP
411 .B ENOSPC
412 There is not enough space left on the device containing the file
413 referred to by
414 .IR fd .
415 .TP
416 .B ENOSYS
417 This kernel does not implement
418 .BR fallocate ().
419 .TP
420 .B EOPNOTSUPP
421 The filesystem containing the file referred to by
422 .I fd
423 does not support this operation;
424 or the
425 .I mode
426 is not supported by the filesystem containing the file referred to by
427 .IR fd .
428 .TP
429 .B EPERM
430 The file referred to by
431 .I fd
432 is marked immutable (see
433 .BR chattr (1)).
434 .TP
435 .B EPERM
436 .I mode
437 specifies
438 .BR FALLOC_FL_PUNCH_HOLE ,
439 .BR FALLOC_FL_COLLAPSE_RANGE ,
440 or
441 .B FALLOC_FL_INSERT_RANGE
442 and
443 the file referred to by
444 .I fd
445 is marked append-only
446 (see
447 .BR chattr (1)).
448 .TP
449 .B EPERM
450 The operation was prevented by a file seal; see
451 .BR fcntl (2).
452 .TP
453 .B ESPIPE
454 .I fd
455 refers to a pipe or FIFO.
456 .TP
457 .B ETXTBSY
458 .I mode
459 specifies
460 .B FALLOC_FL_COLLAPSE_RANGE
461 or
462 .BR FALLOC_FL_INSERT_RANGE ,
463 but the file referred to by
464 .I fd
465 is currently being executed.
466 .SH VERSIONS
467 .BR fallocate ()
468 is available on Linux since kernel 2.6.23.
469 Support is provided by glibc since version 2.10.
470 The
471 .B FALLOC_FL_*
472 flags are defined in glibc headers only since version 2.18.
473 .\" See http://sourceware.org/bugzilla/show_bug.cgi?id=14964
474 .SH STANDARDS
475 .BR fallocate ()
476 is Linux-specific.
477 .SH SEE ALSO
478 .BR fallocate (1),
479 .BR ftruncate (2),
480 .BR posix_fadvise (3),
481 .BR posix_fallocate (3)