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