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