]>
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 | .\" | |
4d4cecd6 | 11 | .TH FALLOCATE 2 2013-11-08 "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> |
c8250206 | 18 | |
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). |
01b7704f | 27 | |
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. | |
37 | ||
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 | |
59 | .IR len . | |
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. | |
65 | ||
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. |
f52e0be8 MK |
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 | |
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. |
d9a0b2a5 | 82 | .PP |
f52e0be8 MK |
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) | |
96575bbc | 92 | in the byte range starting at |
1c7857e9 LAG |
93 | .I offset |
94 | and continuing for | |
95 | .I len | |
f52e0be8 | 96 | bytes. |
9ee4a2b6 MK |
97 | Within the specified range, partial filesystem blocks are zeroed, |
98 | and whole filesystem blocks are removed from the file. | |
96575bbc MK |
99 | After a successful call, |
100 | subsequent reads from this range will return zeroes. | |
f52e0be8 | 101 | |
96575bbc | 102 | The |
1c7857e9 | 103 | .BR FALLOC_FL_PUNCH_HOLE |
96575bbc | 104 | flag must be ORed with |
1c7857e9 | 105 | .BR FALLOC_FL_KEEP_SIZE |
f52e0be8 MK |
106 | in |
107 | .IR mode ; | |
96575bbc MK |
108 | in other words, even when punching off the end of the file, the file size |
109 | (as reported by | |
1c7857e9 | 110 | .BR stat (2)) |
96575bbc | 111 | does not change. |
f52e0be8 | 112 | |
9ee4a2b6 | 113 | Not all filesystems support |
f52e0be8 | 114 | .BR FALLOC_FL_PUNCH_HOLE ; |
9ee4a2b6 | 115 | if a filesystem doesn't support the operation, an error is returned. |
d9a0b2a5 | 116 | .SH RETURN VALUE |
276939a6 | 117 | On success, |
d9a0b2a5 | 118 | .BR fallocate () |
47a97908 MK |
119 | returns zero. |
120 | On error, \-1 is returned and | |
121 | .I errno | |
122 | is set to indicate the error. | |
d9a0b2a5 MK |
123 | .SH ERRORS |
124 | .TP | |
125 | .B EBADF | |
126 | .I fd | |
127 | is not a valid file descriptor, or is not opened for writing. | |
128 | .TP | |
129 | .B EFBIG | |
130 | .IR offset + len | |
131 | exceeds the maximum file size. | |
132 | .TP | |
133 | .B EINTR | |
134 | A signal was caught during execution. | |
135 | .TP | |
136 | .B EINVAL | |
137 | .I offset | |
138 | was less than 0, or | |
139 | .I len | |
c0c3d019 MK |
140 | .\" FIXME (raise a kernel bug) Probably the len==0 case should be |
141 | .\" a no-op, rather than an error. That would be consistent with | |
142 | .\" similar APIs for the len==0 case. | |
143 | .\" See "Re: [PATCH] fallocate.2: add FALLOC_FL_PUNCH_HOLE flag definition" | |
144 | .\" 21 Sep 2012 | |
145 | .\" http://thread.gmane.org/gmane.linux.file-systems/48331/focus=1193526 | |
d9a0b2a5 MK |
146 | was less than or equal to 0. |
147 | .TP | |
148 | .B EIO | |
9ee4a2b6 | 149 | An I/O error occurred while reading from or writing to a filesystem. |
d9a0b2a5 MK |
150 | .TP |
151 | .B ENODEV | |
152 | .I fd | |
153 | does not refer to a regular file or a directory. | |
154 | (If | |
155 | .I fd | |
156 | is a pipe or FIFO, a different error results.) | |
157 | .TP | |
158 | .B ENOSPC | |
159 | There is not enough space left on the device containing the file | |
160 | referred to by | |
161 | .IR fd . | |
162 | .TP | |
163 | .B ENOSYS | |
7cb4d005 MK |
164 | This kernel does not implement |
165 | .BR fallocate (). | |
d9a0b2a5 MK |
166 | .TP |
167 | .B EOPNOTSUPP | |
9ee4a2b6 | 168 | The filesystem containing the file referred to by |
7cb4d005 MK |
169 | .I fd |
170 | does not support this operation; | |
171 | or the | |
d9a0b2a5 | 172 | .I mode |
9ee4a2b6 | 173 | is not supported by the filesystem containing the file referred to by |
d9a0b2a5 | 174 | .IR fd . |
45eb0d22 MK |
175 | .TP |
176 | .B EPERM | |
177 | The file referred to by | |
928b1970 | 178 | .I fd |
45eb0d22 | 179 | is marked immutable (see |
7eb92881 | 180 | .BR chattr (1)). |
54d25eca MK |
181 | Or: |
182 | .I mode | |
183 | specifies | |
184 | .BR FALLOC_FL_PUNCH_HOLE | |
185 | and | |
186 | the file referred to by | |
187 | .I fd | |
188 | is marked append-only | |
189 | (see | |
928b1970 | 190 | .BR chattr (1)). |
45eb0d22 MK |
191 | .TP |
192 | .B ESPIPE | |
193 | .I fd | |
928b1970 | 194 | refers to a pipe or FIFO. |
d9a0b2a5 MK |
195 | .SH VERSIONS |
196 | .BR fallocate () | |
d9a0b2a5 | 197 | is available on Linux since kernel 2.6.23. |
ff6db399 | 198 | Support is provided by glibc since version 2.10. |
7f26805b MK |
199 | The |
200 | .BR FALLOC_FL_* | |
201 | flags are defined in glibc headers only since version 2.18. | |
202 | .\" See http://sourceware.org/bugzilla/show_bug.cgi?id=14964 | |
90e261f2 | 203 | .SH CONFORMING TO |
d9a0b2a5 | 204 | .BR fallocate () |
8382f16d | 205 | is Linux-specific. |
d9a0b2a5 | 206 | .SH SEE ALSO |
1b946741 | 207 | .BR fallocate (1), |
d9a0b2a5 | 208 | .BR ftruncate (2), |
f0c34053 MK |
209 | .BR posix_fadvise (3), |
210 | .BR posix_fallocate (3) |