Debian Codegraph @

upstream/debian-unstable/man2/fallocate.2

raw
1 .\" Copyright 2007, Silicon Graphics, Inc.
2 .\" Copyright, the authors of the Linux man-pages project
3 .\"
4 .\" SPDX-License-Identifier: GPL-2.0-only
5 .\"
6 .TH fallocate 2 2026-02-08 "Linux man-pages 6.18"
7 .SH NAME
8 fallocate \- manipulate file space
9 .SH LIBRARY
10 Standard C library
11 .RI ( libc ,\~ \-lc )
12 .SH SYNOPSIS
13 .nf
14 .BR "#define _GNU_SOURCE" " /* See feature_test_macros(7) */"
15 .B #include <fcntl.h>
16 .P
17 .BI "int fallocate(int " fd ", int " mode ", off_t " offset \
18 ", off_t " size );
19 .fi
20 .SH DESCRIPTION
21 This is a nonportable, Linux-specific system call.
22 For the portable, POSIX.1-specified method of ensuring that space
23 is allocated for a file, see
24 .BR posix_fallocate (3).
25 .P
26 .BR fallocate ()
27 allows the caller to directly manipulate the allocated disk space
28 for the file referred to by
29 .I fd
30 for the byte range starting at
31 .I offset
32 and continuing for
33 .I size
34 bytes.
35 .P
36 The
37 .I mode
38 argument determines the operation to be performed on the given range.
39 Details of the supported operations are given in the subsections below.
40 .SS Allocating disk space
41 The default operation (i.e.,
42 .I mode
43 is zero) of
44 .BR fallocate ()
45 allocates the disk space within the range specified by
46 .I offset
47 and
48 .IR size .
49 The file size (as reported by
50 .BR stat (2))
51 will be changed if
52 .IR offset + size
53 is greater than the file size.
54 Any subregion within the range specified by
55 .I offset
56 and
57 .I size
58 that did not contain data before the call will be initialized to zero.
59 This default behavior closely resembles the behavior of the
60 .BR posix_fallocate (3)
61 library function,
62 and is intended as a method of optimally implementing that function.
63 .P
64 After a successful call, subsequent writes into the range specified by
65 .I offset
66 and
67 .I size
68 are guaranteed not to fail because of lack of disk space.
69 .P
70 If the
71 .B FALLOC_FL_KEEP_SIZE
72 flag is specified in
73 .IR mode ,
74 the behavior of the call is similar,
75 but the file size will not be changed even if
76 .IR offset + size
77 is greater than the file size.
78 Preallocating zeroed blocks beyond the end of the file in this manner
79 is useful for optimizing append workloads.
80 .P
81 If the
82 .B FALLOC_FL_UNSHARE_RANGE
83 flag is specified in
84 .IR mode ,
85 shared file data extents will be made private to the file to guarantee
86 that a subsequent write will not fail due to lack of space.
87 Typically, this will be done by performing a copy-on-write operation on
88 all shared data in the file.
89 This flag may not be supported by all filesystems.
90 .P
91 Because allocation is done in block size chunks,
92 .BR fallocate ()
93 may allocate a larger range of disk space than was specified.
94 .SS Deallocating file space
95 Specifying the
96 .B FALLOC_FL_PUNCH_HOLE
97 flag (available since Linux 2.6.38) in
98 .I mode
99 deallocates space (i.e., creates a hole)
100 in the byte range starting at
101 .I offset
102 and continuing for
103 .I size
104 bytes.
105 Within the specified range, partial filesystem blocks are zeroed,
106 and whole filesystem blocks are removed from the file.
107 After a successful call,
108 subsequent reads from this range will return zeros.
109 .P
110 The
111 .B FALLOC_FL_PUNCH_HOLE
112 flag must be ORed with
113 .B FALLOC_FL_KEEP_SIZE
114 in
115 .IR mode ;
116 in other words, even when punching off the end of the file, the file size
117 (as reported by
118 .BR stat (2))
119 does not change.
120 .P
121 Not all filesystems support
122 .BR FALLOC_FL_PUNCH_HOLE ;
123 if a filesystem doesn't support the operation, an error is returned.
124 The operation is supported on at least the following filesystems:
125 .IP \[bu] 3
126 XFS (since Linux 2.6.38)
127 .IP \[bu]
128 ext4 (since Linux 3.0)
129 .\" commit a4bb6b64e39abc0e41ca077725f2a72c868e7622
130 .IP \[bu]
131 Btrfs (since Linux 3.7)
132 .IP \[bu]
133 .BR tmpfs (5)
134 (since Linux 3.5)
135 .\" commit 83e4fa9c16e4af7122e31be3eca5d57881d236fe
136 .IP \[bu]
137 .BR gfs2 (5)
138 (since Linux 4.16)
139 .\" commit 4e56a6411fbce6f859566e17298114c2434391a4
140 .SS Collapsing file space
141 .\" commit 00f5e61998dd17f5375d9dfc01331f104b83f841
142 Specifying the
143 .B FALLOC_FL_COLLAPSE_RANGE
144 flag (available since Linux 3.15) in
145 .I mode
146 removes a byte range from a file, without leaving a hole.
147 The byte range to be collapsed starts at
148 .I offset
149 and continues for
150 .I size
151 bytes.
152 At the completion of the operation,
153 the contents of the file starting at the location
154 .I offset+size
155 will be appended at the location
156 .IR offset ,
157 and the file will be
158 .I size
159 bytes smaller.
160 .P
161 A filesystem may place limitations on the granularity of the operation,
162 in order to ensure efficient implementation.
163 Typically,
164 .I offset
165 and
166 .I size
167 must be a multiple of the filesystem logical block size,
168 which varies according to the filesystem type and configuration.
169 If a filesystem has such a requirement,
170 .BR fallocate ()
171 fails with the error
172 .B EINVAL
173 if this requirement is violated.
174 .P
175 If the region specified by
176 .I offset
177 plus
178 .I size
179 reaches or passes the end of file, an error is returned;
180 instead, use
181 .BR ftruncate (2)
182 to truncate a file.
183 .P
184 No other flags may be specified in
185 .I mode
186 in conjunction with
187 .BR FALLOC_FL_COLLAPSE_RANGE .
188 .P
189 As at Linux 3.15,
190 .B FALLOC_FL_COLLAPSE_RANGE
191 is supported by
192 ext4 (only for extent-based files)
193 .\" commit 9eb79482a97152930b113b51dff530aba9e28c8e
194 and XFS.
195 .\" commit e1d8fb88a64c1f8094b9f6c3b6d2d9e6719c970d
196 .SS Zeroing file space
197 Specifying the
198 .B FALLOC_FL_ZERO_RANGE
199 flag (available since Linux 3.15)
200 .\" commit 409332b65d3ed8cfa7a8030f1e9d52f372219642
201 in
202 .I mode
203 zeros space in the byte range starting at
204 .I offset
205 and continuing for
206 .I size
207 bytes.
208 Within the specified range, blocks are preallocated for the regions
209 that span the holes in the file.
210 After a successful call, subsequent
211 reads from this range will return zeros.
212 .P
213 Zeroing is done within the filesystem preferably by converting the range into
214 unwritten extents.
215 This approach means that the specified range will not be physically zeroed
216 out on the device (except for partial blocks at the either end of the range),
217 and I/O is (otherwise) required only to update metadata.
218 .P
219 If the
220 .B FALLOC_FL_KEEP_SIZE
221 flag is additionally specified in
222 .IR mode ,
223 the behavior of the call is similar,
224 but the file size will not be changed even if
225 .IR offset + size
226 is greater than the file size.
227 This behavior is the same as when preallocating space with
228 .B FALLOC_FL_KEEP_SIZE
229 specified.
230 .P
231 Not all filesystems support
232 .BR FALLOC_FL_ZERO_RANGE ;
233 if a filesystem doesn't support the operation, an error is returned.
234 The operation is supported on at least the following filesystems:
235 .IP \[bu] 3
236 XFS (since Linux 3.15)
237 .\" commit 376ba313147b4172f3e8cf620b9fb591f3e8cdfa
238 .IP \[bu]
239 ext4, for extent-based files (since Linux 3.15)
240 .\" commit b8a8684502a0fc852afa0056c6bb2a9273f6fcc0
241 .IP \[bu]
242 SMB3 (since Linux 3.17)
243 .\" commit 30175628bf7f521e9ee31ac98fa6d6fe7441a556
244 .IP \[bu]
245 Btrfs (since Linux 4.16)
246 .\" commit f27451f229966874a8793995b8e6b74326d125df
247 .SS Increasing file space
248 Specifying the
249 .B FALLOC_FL_INSERT_RANGE
250 flag
251 (available since Linux 4.1)
252 .\" commit dd46c787788d5bf5b974729d43e4c405814a4c7d
253 in
254 .I mode
255 increases the file space by inserting a hole within the file size without
256 overwriting any existing data.
257 The hole will start at
258 .I offset
259 and continue for
260 .I size
261 bytes.
262 When inserting the hole inside file, the contents of the file starting at
263 .I offset
264 will be shifted upward (i.e., to a higher file offset) by
265 .I size
266 bytes.
267 Inserting a hole inside a file increases the file size by
268 .I size
269 bytes.
270 .P
271 This mode has the same limitations as
272 .B FALLOC_FL_COLLAPSE_RANGE
273 regarding the granularity of the operation.
274 If the granularity requirements are not met,
275 .BR fallocate ()
276 fails with the error
277 .BR EINVAL .
278 If the
279 .I offset
280 is equal to or greater than the end of file, an error is returned.
281 For such operations (i.e., inserting a hole at the end of file),
282 .BR ftruncate (2)
283 should be used.
284 .P
285 No other flags may be specified in
286 .I mode
287 in conjunction with
288 .BR FALLOC_FL_INSERT_RANGE .
289 .P
290 .B FALLOC_FL_INSERT_RANGE
291 requires filesystem support.
292 Filesystems that support this operation include
293 XFS (since Linux 4.1)
294 .\" commit a904b1ca5751faf5ece8600e18cd3b674afcca1b
295 and ext4 (since Linux 4.2).
296 .\" commit 331573febb6a224bc50322e3670da326cb7f4cfc
297 .\" f2fs also has support since Linux 4.2
298 .\" commit f62185d0e283e9d311e3ac1020f159d95f0aab39
299 .SH RETURN VALUE
300 On success,
301 .BR fallocate ()
302 returns zero.
303 On error, \-1 is returned and
304 .I errno
305 is set to indicate the error.
306 .SH ERRORS
307 .TP
308 .B EBADF
309 .I fd
310 is not a valid file descriptor, or is not opened for writing.
311 .TP
312 .B EFBIG
313 .IR offset + size
314 exceeds the maximum file size.
315 .TP
316 .B EFBIG
317 .I mode
318 is
319 .BR FALLOC_FL_INSERT_RANGE ,
320 and the current file
321 .RI size+ len
322 exceeds the maximum file size.
323 .TP
324 .B EINTR
325 A signal was caught during execution;
326 see
327 .BR signal (7).
328 .TP
329 .B EINVAL
330 .I offset
331 was less than 0, or
332 .I size
333 .\" FIXME . (raise a kernel bug) Probably the size==0 case should be
334 .\" a no-op, rather than an error. That would be consistent with
335 .\" similar APIs for the size==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 size
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 size
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 Linux 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;
451 see
452 .BR fcntl (2).
453 .TP
454 .B ESPIPE
455 .I fd
456 refers to a pipe or FIFO.
457 .TP
458 .B ETXTBSY
459 .I mode
460 specifies
461 .B FALLOC_FL_COLLAPSE_RANGE
462 or
463 .BR FALLOC_FL_INSERT_RANGE ,
464 but the file referred to by
465 .I fd
466 is currently being executed.
467 .SH STANDARDS
468 Linux.
469 .SH HISTORY
470 .TP
471 .BR fallocate ()
472 Linux 2.6.23,
473 glibc 2.10.
474 .TP
475 .B FALLOC_FL_*
476 glibc 2.18.
477 .\" See http://sourceware.org/bugzilla/show_bug.cgi?id=14964
478 .SH SEE ALSO
479 .BR fallocate (1),
480 .BR ftruncate (2),
481 .BR posix_fadvise (3),
482 .BR posix_fallocate (3)