]>
Commit | Line | Data |
---|---|---|
49b7f95e | 1 | .TH FALLOCATE 1 "April 2014" "util-linux" "User Commands" |
0167ca82 BS |
2 | .SH NAME |
3 | fallocate \- preallocate or deallocate space to a file | |
4 | .SH SYNOPSIS | |
5 | .B fallocate | |
49b7f95e | 6 | .RB [ \-c | \-p | \-z ] |
0167ca82 BS |
7 | .RB [ \-o |
8 | .IR offset ] | |
9 | .B \-l | |
9c56988a | 10 | .I length |
47f9b35e | 11 | .RB [ \-n ] |
0167ca82 BS |
12 | .I filename |
13 | .PP | |
14 | .B fallocate \-d | |
15 | .RB [ \-o | |
16 | .IR offset ] | |
17 | .RB [ \-l | |
18 | .IR length ] | |
19 | .I filename | |
833f9a7a DC |
20 | .PP |
21 | .B fallocate \-x | |
22 | .RB [ \-o | |
23 | .IR offset ] | |
9c56988a BIG |
24 | .B \-l |
25 | .I length | |
833f9a7a | 26 | .I filename |
0167ca82 BS |
27 | .SH DESCRIPTION |
28 | .B fallocate | |
9c56988a BIG |
29 | is used to manipulate the allocated disk space for a file, |
30 | either to deallocate or preallocate it. | |
31 | For filesystems which support the fallocate system call, | |
0167ca82 | 32 | preallocation is done quickly by allocating blocks and marking them as |
9c56988a BIG |
33 | uninitialized, requiring no IO to the data blocks. |
34 | This is much faster than creating a file by filling it with zeroes. | |
0167ca82 BS |
35 | .PP |
36 | The exit code returned by | |
37 | .B fallocate | |
38 | is 0 on success and 1 on failure. | |
39 | .SH OPTIONS | |
9c56988a BIG |
40 | The |
41 | .I length | |
42 | and | |
43 | .I offset | |
0167ca82 | 44 | arguments may be followed by the multiplicative suffixes KiB (=1024), |
9c56988a | 45 | MiB (=1024*1024), and so on for GiB, TiB, PiB, EiB, ZiB, and YiB (the "iB" is |
0167ca82 | 46 | optional, e.g., "K" has the same meaning as "KiB") or the suffixes |
9c56988a | 47 | KB (=1000), MB (=1000*1000), and so on for GB, TB, PB, EB, ZB, and YB. |
0167ca82 | 48 | .PP |
9c56988a BIG |
49 | The options |
50 | .BR \-\-collapse\-range ", " \-\-dig\-holes ", " \-\-punch\-hole , | |
51 | and | |
52 | .B \-\-zero\-range | |
53 | are mutually exclusive. | |
0167ca82 | 54 | .TP |
9c56988a BIG |
55 | .BR \-c ", " \-\-collapse\-range |
56 | Removes a byte range from a file, without leaving a hole. | |
57 | The byte range to be collapsed starts at | |
58 | .I offset | |
59 | and continues for | |
60 | .I length | |
61 | bytes. | |
62 | At the completion of the operation, | |
63 | the contents of the file starting at the location | |
64 | .IR offset + length | |
65 | will be appended at the location | |
66 | .IR offset , | |
67 | and the file will be | |
68 | .I length | |
69 | bytes smaller. | |
70 | The option | |
71 | .B \-\-keep\-size | |
72 | may not be specified for the collapse-range operation. | |
0167ca82 BS |
73 | .sp |
74 | Available since Linux 3.15 for ext4 (only for extent-based files) and XFS. | |
562adaed KZ |
75 | .sp |
76 | A filesystem may place limitations on the granularity of the operation, in | |
77 | order to ensure efficient implementation. Typically, offset and len must be a | |
78 | multiple of the filesystem logical block size, which varies according to the | |
79 | filesystem type and configuration. If a filesystem has such a requirement, | |
80 | the operation will fail with the error EINVAL if this requirement is violated. | |
0167ca82 | 81 | .TP |
9c56988a BIG |
82 | .BR \-d ", " \-\-dig\-holes |
83 | Detect and dig holes. | |
84 | This makes the file sparse in-place, without using extra disk space. | |
85 | The minimum size of the hole depends on filesystem I/O block size | |
86 | (usually 4096 bytes). | |
87 | Also, when using this option, | |
88 | .B \-\-keep\-size | |
89 | is implied. If no range is specified by | |
90 | .B \-\-offset | |
91 | and | |
92 | .BR \-\-length , | |
0167ca82 BS |
93 | then the entire file is analyzed for holes. |
94 | .sp | |
9c56988a BIG |
95 | You can think of this option as doing a |
96 | .RB """" "cp \-\-sparse" """" | |
97 | and then renaming the destination file to the original, | |
98 | without the need for extra disk space. | |
0167ca82 BS |
99 | .sp |
100 | See \fB\-\-punch\-hole\fP for a list of supported filesystems. | |
101 | .TP | |
9c56988a BIG |
102 | .BR \-i ", " \-\-insert\-range |
103 | Insert a hole of | |
104 | .I length | |
105 | bytes from | |
106 | .IR offset , | |
107 | shifting existing data. | |
b4390656 | 108 | .TP |
9c56988a | 109 | .BR \-l ", " "\-\-length " \fIlength |
0167ca82 BS |
110 | Specifies the length of the range, in bytes. |
111 | .TP | |
9c56988a | 112 | .BR \-n ", " \-\-keep\-size |
0167ca82 BS |
113 | Do not modify the apparent length of the file. This may effectively allocate |
114 | blocks past EOF, which can be removed with a truncate. | |
115 | .TP | |
9c56988a | 116 | .BR \-o ", " "\-\-offset " \fIoffset |
0167ca82 BS |
117 | Specifies the beginning offset of the range, in bytes. |
118 | .TP | |
9c56988a | 119 | .BR \-p ", " \-\-punch\-hole |
0167ca82 | 120 | Deallocates space (i.e., creates a hole) in the byte range starting at |
9c56988a BIG |
121 | .I offset |
122 | and continuing for | |
123 | .I length | |
124 | bytes. | |
125 | Within the specified range, partial filesystem blocks are zeroed, | |
126 | and whole filesystem blocks are removed from the file. | |
127 | After a successful call, | |
128 | subsequent reads from this range will return zeroes. | |
129 | This option may not be specified at the same time as the | |
130 | .B \-\-zero\-range | |
131 | option. | |
132 | Also, when using this option, | |
133 | .B \-\-keep\-size | |
134 | is implied. | |
0167ca82 BS |
135 | .sp |
136 | Supported for XFS (since Linux 2.6.38), ext4 (since Linux 3.0), | |
137 | Btrfs (since Linux 3.7) and tmpfs (since Linux 3.5). | |
138 | .TP | |
9c56988a | 139 | .BR \-v ", " \-\-verbose |
0167ca82 BS |
140 | Enable verbose mode. |
141 | .TP | |
9c56988a BIG |
142 | .BR \-x ", " \-\-posix |
143 | Enable POSIX operation mode. | |
144 | In that mode allocation operation always completes, | |
145 | but it may take longer time when fast allocation is not supported by | |
146 | the underlying filesystem. | |
833f9a7a | 147 | .TP |
9c56988a BIG |
148 | .BR \-z ", " \-\-zero\-range |
149 | Zeroes space in the byte range starting at | |
150 | .I offset | |
151 | and continuing for | |
152 | .I length | |
153 | bytes. | |
154 | Within the specified range, blocks are preallocated for the regions | |
155 | that span the holes in the file. | |
156 | After a successful call, | |
157 | subsequent reads from this range will return zeroes. | |
0167ca82 BS |
158 | .sp |
159 | Zeroing is done within the filesystem preferably by converting the | |
160 | range into unwritten extents. This approach means that the specified | |
161 | range will not be physically zeroed out on the device (except for | |
162 | partial blocks at the either end of the range), and I/O is | |
163 | (otherwise) required only to update metadata. | |
164 | .sp | |
165 | Option \fB\-\-keep\-size\fP can be specified to prevent file length | |
166 | modification. | |
167 | .sp | |
168 | Available since Linux 3.14 for ext4 (only for extent-based files) and XFS. | |
169 | .TP | |
9c56988a | 170 | .BR \-V ", " \-\-version |
0167ca82 BS |
171 | Display version information and exit. |
172 | .TP | |
9c56988a | 173 | .BR \-h ", " \-\-help |
0167ca82 | 174 | Display help text and exit. |
d46a5499 | 175 | .SH AUTHORS |
9c56988a | 176 | .MT sandeen@redhat.com |
1d803460 | 177 | Eric Sandeen |
9c56988a | 178 | .ME |
1d803460 | 179 | .br |
9c56988a | 180 | .MT kzak@redhat.com |
1d803460 | 181 | Karel Zak |
9c56988a | 182 | .ME |
0167ca82 | 183 | .SH SEE ALSO |
f053ff1e | 184 | .BR truncate (1), |
0167ca82 | 185 | .BR fallocate (2), |
f053ff1e | 186 | .BR posix_fallocate (3) |
0167ca82 BS |
187 | .SH AVAILABILITY |
188 | The fallocate command is part of the util-linux package and is available from | |
d673b74e | 189 | .UR https://\:www.kernel.org\:/pub\:/linux\:/utils\:/util-linux/ |
0167ca82 BS |
190 | Linux Kernel Archive |
191 | .UE . |