]>
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 | .\" |
c850ff7e | 4 | .\" SPDX-License-Identifier: GPL-2.0-only |
d9a0b2a5 | 5 | .\" |
f52e0be8 MK |
6 | .\" 2011-09-19: Added FALLOC_FL_PUNCH_HOLE |
7 | .\" 2011-09-19: Substantial restructuring of the page | |
8 | .\" | |
4c1c5274 | 9 | .TH fallocate 2 (date) "Linux man-pages (unreleased)" |
d9a0b2a5 MK |
10 | .SH NAME |
11 | fallocate \- manipulate file space | |
1e4cd379 AC |
12 | .SH LIBRARY |
13 | Standard C library | |
8fc3b2cf | 14 | .RI ( libc ", " \-lc ) |
d9a0b2a5 MK |
15 | .SH SYNOPSIS |
16 | .nf | |
86b91fdf | 17 | .BR "#define _GNU_SOURCE" " /* See feature_test_macros(7) */" |
ff6db399 | 18 | .B #include <fcntl.h> |
dbfe9c70 | 19 | .PP |
ff6db399 | 20 | .BI "int fallocate(int " fd ", int " mode ", off_t " offset \ |
9bfc9cb1 | 21 | ", off_t " len ");" |
c8250206 | 22 | .fi |
d9a0b2a5 | 23 | .SH DESCRIPTION |
d603cc27 | 24 | This is a nonportable, Linux-specific system call. |
01b7704f MK |
25 | For the portable, POSIX.1-specified method of ensuring that space |
26 | is allocated for a file, see | |
8c56fcec | 27 | .BR posix_fallocate (3). |
efeece04 | 28 | .PP |
d9a0b2a5 MK |
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. | |
efeece04 | 38 | .PP |
d9a0b2a5 MK |
39 | The |
40 | .I mode | |
41 | argument determines the operation to be performed on the given range. | |
f52e0be8 MK |
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 () | |
c166fac5 | 48 | allocates the disk space within the range specified by |
d9a0b2a5 MK |
49 | .I offset |
50 | and | |
51 | .IR len . | |
f52e0be8 MK |
52 | The file size (as reported by |
53 | .BR stat (2)) | |
54 | will be changed if | |
381ee84e | 55 | .IR offset + len |
f52e0be8 | 56 | is greater than the file size. |
4d4cecd6 | 57 | Any subregion within the range specified by |
c166fac5 CH |
58 | .I offset |
59 | and | |
1ae6b2c7 | 60 | .I len |
c166fac5 | 61 | that did not contain data before the call will be initialized to zero. |
f52e0be8 MK |
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. | |
efeece04 | 66 | .PP |
f52e0be8 | 67 | After a successful call, subsequent writes into the range specified by |
1ae6b2c7 | 68 | .I offset |
f52e0be8 | 69 | and |
1ae6b2c7 | 70 | .I len |
d9a0b2a5 | 71 | are guaranteed not to fail because of lack of disk space. |
efeece04 | 72 | .PP |
f52e0be8 MK |
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 | |
381ee84e | 79 | .IR offset + len |
f52e0be8 MK |
80 | is greater than the file size. |
81 | Preallocating zeroed blocks beyond the end of the file in this manner | |
d9a0b2a5 | 82 | is useful for optimizing append workloads. |
efeece04 | 83 | .PP |
63a599c6 | 84 | If the |
6131983d | 85 | .B FALLOC_FL_UNSHARE_RANGE |
63a599c6 DW |
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. | |
d9a0b2a5 | 93 | .PP |
f52e0be8 MK |
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 | |
1ae6b2c7 | 99 | .B FALLOC_FL_PUNCH_HOLE |
f52e0be8 MK |
100 | flag (available since Linux 2.6.38) in |
101 | .I mode | |
102 | deallocates space (i.e., creates a hole) | |
96575bbc | 103 | in the byte range starting at |
1c7857e9 LAG |
104 | .I offset |
105 | and continuing for | |
106 | .I len | |
f52e0be8 | 107 | bytes. |
9ee4a2b6 MK |
108 | Within the specified range, partial filesystem blocks are zeroed, |
109 | and whole filesystem blocks are removed from the file. | |
96575bbc | 110 | After a successful call, |
d2cb1ef1 | 111 | subsequent reads from this range will return zeros. |
efeece04 | 112 | .PP |
96575bbc | 113 | The |
1ae6b2c7 | 114 | .B FALLOC_FL_PUNCH_HOLE |
96575bbc | 115 | flag must be ORed with |
1ae6b2c7 | 116 | .B FALLOC_FL_KEEP_SIZE |
f52e0be8 MK |
117 | in |
118 | .IR mode ; | |
96575bbc MK |
119 | in other words, even when punching off the end of the file, the file size |
120 | (as reported by | |
1c7857e9 | 121 | .BR stat (2)) |
96575bbc | 122 | does not change. |
efeece04 | 123 | .PP |
9ee4a2b6 | 124 | Not all filesystems support |
f52e0be8 | 125 | .BR FALLOC_FL_PUNCH_HOLE ; |
9ee4a2b6 | 126 | if a filesystem doesn't support the operation, an error is returned. |
ce430f41 | 127 | The operation is supported on at least the following filesystems: |
cdede5cd | 128 | .IP \[bu] 3 |
49995543 | 129 | XFS (since Linux 2.6.38) |
cdede5cd | 130 | .IP \[bu] |
49995543 MK |
131 | ext4 (since Linux 3.0) |
132 | .\" commit a4bb6b64e39abc0e41ca077725f2a72c868e7622 | |
cdede5cd | 133 | .IP \[bu] |
49995543 | 134 | Btrfs (since Linux 3.7) |
cdede5cd | 135 | .IP \[bu] |
b30b425b | 136 | .BR tmpfs (5) |
3bf86e7d | 137 | (since Linux 3.5) |
49995543 | 138 | .\" commit 83e4fa9c16e4af7122e31be3eca5d57881d236fe |
cdede5cd | 139 | .IP \[bu] |
3bf86e7d AP |
140 | .BR gfs2 (5) |
141 | (since Linux 4.16) | |
142 | .\" commit 4e56a6411fbce6f859566e17298114c2434391a4 | |
ea56dddf | 143 | .SS Collapsing file space |
1ecfa5b3 | 144 | .\" commit 00f5e61998dd17f5375d9dfc01331f104b83f841 |
f78da076 | 145 | Specifying the |
1ae6b2c7 | 146 | .B FALLOC_FL_COLLAPSE_RANGE |
1ecfa5b3 | 147 | flag (available since Linux 3.15) in |
ea56dddf | 148 | .I mode |
1ecfa5b3 MK |
149 | removes a byte range from a file, without leaving a hole. |
150 | The byte range to be collapsed starts at | |
ea56dddf | 151 | .I offset |
1ecfa5b3 | 152 | and continues for |
ea56dddf | 153 | .I len |
f78da076 | 154 | bytes. |
1ecfa5b3 MK |
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. | |
efeece04 | 163 | .PP |
1ecfa5b3 MK |
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 () | |
26cd31fd | 174 | fails with the error |
1ae6b2c7 | 175 | .B EINVAL |
1ecfa5b3 | 176 | if this requirement is violated. |
efeece04 | 177 | .PP |
1ecfa5b3 MK |
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. | |
efeece04 | 186 | .PP |
1ecfa5b3 | 187 | No other flags may be specified in |
1ae6b2c7 | 188 | .I mode |
1ecfa5b3 MK |
189 | in conjunction with |
190 | .BR FALLOC_FL_COLLAPSE_RANGE . | |
efeece04 | 191 | .PP |
1ecfa5b3 MK |
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 | |
7dc489e3 | 199 | .SS Zeroing file space |
44e4132a | 200 | Specifying the |
1ae6b2c7 | 201 | .B FALLOC_FL_ZERO_RANGE |
4a401602 | 202 | flag (available since Linux 3.15) |
44e4132a MK |
203 | .\" commit 409332b65d3ed8cfa7a8030f1e9d52f372219642 |
204 | in | |
7dc489e3 | 205 | .I mode |
d2cb1ef1 | 206 | zeros space in the byte range starting at |
7dc489e3 LC |
207 | .I offset |
208 | and continuing for | |
209 | .I len | |
210 | bytes. | |
211 | Within the specified range, blocks are preallocated for the regions | |
44e4132a MK |
212 | that span the holes in the file. |
213 | After a successful call, subsequent | |
d2cb1ef1 | 214 | reads from this range will return zeros. |
efeece04 | 215 | .PP |
7c7960f8 MK |
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 | |
4cb27742 | 219 | out on the device (except for partial blocks at the either end of the range), |
b9ddebe2 | 220 | and I/O is (otherwise) required only to update metadata. |
efeece04 | 221 | .PP |
7dc489e3 LC |
222 | If the |
223 | .B FALLOC_FL_KEEP_SIZE | |
7c7960f8 | 224 | flag is additionally specified in |
7dc489e3 LC |
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 | |
44e4132a | 229 | is greater than the file size. |
a1fa36af | 230 | This behavior is the same as when preallocating space with |
7dc489e3 LC |
231 | .B FALLOC_FL_KEEP_SIZE |
232 | specified. | |
efeece04 | 233 | .PP |
7dc489e3 LC |
234 | Not all filesystems support |
235 | .BR FALLOC_FL_ZERO_RANGE ; | |
236 | if a filesystem doesn't support the operation, an error is returned. | |
44e4132a | 237 | The operation is supported on at least the following filesystems: |
cdede5cd | 238 | .IP \[bu] 3 |
4a401602 | 239 | XFS (since Linux 3.15) |
7dc489e3 | 240 | .\" commit 376ba313147b4172f3e8cf620b9fb591f3e8cdfa |
cdede5cd | 241 | .IP \[bu] |
4a401602 | 242 | ext4, for extent-based files (since Linux 3.15) |
7dc489e3 | 243 | .\" commit b8a8684502a0fc852afa0056c6bb2a9273f6fcc0 |
cdede5cd | 244 | .IP \[bu] |
adf507a3 MK |
245 | SMB3 (since Linux 3.17) |
246 | .\" commit 30175628bf7f521e9ee31ac98fa6d6fe7441a556 | |
cdede5cd | 247 | .IP \[bu] |
511e0bd0 MK |
248 | Btrfs (since Linux 4.16) |
249 | .\" commit f27451f229966874a8793995b8e6b74326d125df | |
7da70a01 | 250 | .SS Increasing file space |
7da70a01 | 251 | Specifying the |
1ae6b2c7 | 252 | .B FALLOC_FL_INSERT_RANGE |
ec9a2be0 MK |
253 | flag |
254 | (available since Linux 4.1) | |
255 | .\" commit dd46c787788d5bf5b974729d43e4c405814a4c7d | |
256 | in | |
7da70a01 | 257 | .I mode |
ec9a2be0 | 258 | increases the file space by inserting a hole within the file size without |
7da70a01 NJ |
259 | overwriting any existing data. |
260 | The hole will start at | |
261 | .I offset | |
262 | and continue for | |
263 | .I len | |
264 | bytes. | |
ec9a2be0 | 265 | When inserting the hole inside file, the contents of the file starting at |
7da70a01 | 266 | .I offset |
ec9a2be0 | 267 | will be shifted upward (i.e., to a higher file offset) by |
7da70a01 NJ |
268 | .I len |
269 | bytes. | |
ec9a2be0 | 270 | Inserting a hole inside a file increases the file size by |
7da70a01 NJ |
271 | .I len |
272 | bytes. | |
efeece04 | 273 | .PP |
ec9a2be0 | 274 | This mode has the same limitations as |
1ae6b2c7 | 275 | .B FALLOC_FL_COLLAPSE_RANGE |
ec9a2be0 | 276 | regarding the granularity of the operation. |
7da70a01 NJ |
277 | If the granularity requirements are not met, |
278 | .BR fallocate () | |
26cd31fd | 279 | fails with the error |
d8012462 | 280 | .BR EINVAL . |
7da70a01 NJ |
281 | If the |
282 | .I offset | |
ec9a2be0 MK |
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) | |
7da70a01 | 286 | should be used. |
efeece04 | 287 | .PP |
7da70a01 | 288 | No other flags may be specified in |
1ae6b2c7 | 289 | .I mode |
7da70a01 NJ |
290 | in conjunction with |
291 | .BR FALLOC_FL_INSERT_RANGE . | |
efeece04 | 292 | .PP |
7da70a01 | 293 | .B FALLOC_FL_INSERT_RANGE |
bb2f7580 MK |
294 | requires filesystem support. |
295 | Filesystems that support this operation include | |
296 | XFS (since Linux 4.1) | |
7da70a01 | 297 | .\" commit a904b1ca5751faf5ece8600e18cd3b674afcca1b |
bb2f7580 MK |
298 | and ext4 (since Linux 4.2). |
299 | .\" commit 331573febb6a224bc50322e3670da326cb7f4cfc | |
300 | .\" f2fs also has support since Linux 4.2 | |
301 | .\" commit f62185d0e283e9d311e3ac1020f159d95f0aab39 | |
d9a0b2a5 | 302 | .SH RETURN VALUE |
276939a6 | 303 | On success, |
d9a0b2a5 | 304 | .BR fallocate () |
47a97908 MK |
305 | returns zero. |
306 | On error, \-1 is returned and | |
307 | .I errno | |
308 | is set to indicate the error. | |
d9a0b2a5 MK |
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 | |
7da70a01 NJ |
319 | .B EFBIG |
320 | .I mode | |
321 | is | |
322 | .BR FALLOC_FL_INSERT_RANGE , | |
ec9a2be0 | 323 | and the current file size+\fIlen\fP exceeds the maximum file size. |
7da70a01 | 324 | .TP |
d9a0b2a5 | 325 | .B EINTR |
bb14af39 MK |
326 | A signal was caught during execution; see |
327 | .BR signal (7). | |
d9a0b2a5 MK |
328 | .TP |
329 | .B EINVAL | |
330 | .I offset | |
331 | was less than 0, or | |
332 | .I len | |
bea08fec | 333 | .\" FIXME . (raise a kernel bug) Probably the len==0 case should be |
c0c3d019 MK |
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 | |
d9a0b2a5 MK |
339 | was less than or equal to 0. |
340 | .TP | |
1ecfa5b3 MK |
341 | .B EINVAL |
342 | .I mode | |
343 | is | |
1ae6b2c7 | 344 | .B FALLOC_FL_COLLAPSE_RANGE |
1ecfa5b3 MK |
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 | |
1ae6b2c7 | 354 | .B FALLOC_FL_INSERT_RANGE |
7da70a01 NJ |
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 | |
1ae6b2c7 | 362 | .B FALLOC_FL_COLLAPSE_RANGE |
7da70a01 NJ |
363 | or |
364 | .BR FALLOC_FL_INSERT_RANGE , | |
1ecfa5b3 MK |
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 | |
718778ad | 372 | .I mode |
ec9a2be0 | 373 | contains one of |
1ecfa5b3 | 374 | .B FALLOC_FL_COLLAPSE_RANGE |
7da70a01 NJ |
375 | or |
376 | .B FALLOC_FL_INSERT_RANGE | |
ec9a2be0 | 377 | and also other flags; |
1ecfa5b3 | 378 | no other flags are permitted with |
1ae6b2c7 | 379 | .B FALLOC_FL_COLLAPSE_RANGE |
7da70a01 NJ |
380 | or |
381 | .BR FALLOC_FL_INSERT_RANGE . | |
718778ad SP |
382 | .TP |
383 | .B EINVAL | |
2af4d967 MK |
384 | .I mode |
385 | is | |
1ae6b2c7 AC |
386 | .BR FALLOC_FL_COLLAPSE_RANGE , |
387 | .BR FALLOC_FL_ZERO_RANGE , | |
7da70a01 NJ |
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. | |
b324e17d | 393 | .\" There was an inconsistency in Linux 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 | |
1ae6b2c7 AC |
438 | .BR FALLOC_FL_PUNCH_HOLE , |
439 | .BR FALLOC_FL_COLLAPSE_RANGE , | |
1ecfa5b3 | 440 | or |
1ae6b2c7 | 441 | .B FALLOC_FL_INSERT_RANGE |
54d25eca MK |
442 | and |
443 | the file referred to by | |
444 | .I fd | |
445 | is marked append-only | |
446 | (see | |
928b1970 | 447 | .BR chattr (1)). |
45eb0d22 | 448 | .TP |
fbab10e5 MK |
449 | .B EPERM |
450 | The operation was prevented by a file seal; see | |
451 | .BR fcntl (2). | |
452 | .TP | |
45eb0d22 MK |
453 | .B ESPIPE |
454 | .I fd | |
928b1970 | 455 | refers to a pipe or FIFO. |
1ecfa5b3 MK |
456 | .TP |
457 | .B ETXTBSY | |
458 | .I mode | |
459 | specifies | |
1ae6b2c7 | 460 | .B FALLOC_FL_COLLAPSE_RANGE |
7da70a01 NJ |
461 | or |
462 | .BR FALLOC_FL_INSERT_RANGE , | |
1ecfa5b3 | 463 | but the file referred to by |
1ae6b2c7 | 464 | .I fd |
1ecfa5b3 | 465 | is currently being executed. |
4131356c AC |
466 | .SH STANDARDS |
467 | Linux. | |
468 | .SH HISTORY | |
469 | .TP | |
d9a0b2a5 | 470 | .BR fallocate () |
4131356c AC |
471 | Linux 2.6.23, |
472 | glibc 2.10. | |
473 | .TP | |
1ae6b2c7 | 474 | .B FALLOC_FL_* |
4131356c | 475 | glibc 2.18. |
7f26805b | 476 | .\" See http://sourceware.org/bugzilla/show_bug.cgi?id=14964 |
d9a0b2a5 | 477 | .SH SEE ALSO |
1b946741 | 478 | .BR fallocate (1), |
d9a0b2a5 | 479 | .BR ftruncate (2), |
f0c34053 MK |
480 | .BR posix_fadvise (3), |
481 | .BR posix_fallocate (3) |