1FALLOCATE(1)                     User Commands                    FALLOCATE(1)
2
3
4

NAME

6       fallocate - preallocate or deallocate space to a file
7

SYNOPSIS

9       fallocate [-c|-p|-z] [-o offset] -l length [-n] filename
10
11       fallocate -d [-o offset] [-l length] filename
12
13       fallocate -x [-o offset] -l length filename
14

DESCRIPTION

16       fallocate  is  used  to manipulate the allocated disk space for a file,
17       either to deallocate or preallocate it.  For filesystems which  support
18       the  fallocate system call, preallocation is done quickly by allocating
19       blocks and marking them as uninitialized, requiring no IO to  the  data
20       blocks.   This  is  much faster than creating a file by filling it with
21       zeroes.
22
23       The exit status returned by fallocate is 0 on success and 1 on failure.
24

OPTIONS

26       The length and offset arguments may be followed by  the  multiplicative
27       suffixes  KiB  (=1024),  MiB (=1024*1024), and so on for GiB, TiB, PiB,
28       EiB, ZiB, and YiB (the "iB" is optional, e.g., "K" has the same meaning
29       as  "KiB")  or  the suffixes KB (=1000), MB (=1000*1000), and so on for
30       GB, TB, PB, EB, ZB, and YB.
31
32       The   options   --collapse-range,   --dig-holes,   --punch-hole,    and
33       --zero-range are mutually exclusive.
34
35       -c, --collapse-range
36              Removes  a  byte range from a file, without leaving a hole.  The
37              byte range to be collapsed starts at offset  and  continues  for
38              length  bytes.  At the completion of the operation, the contents
39              of the file starting  at  the  location  offset+length  will  be
40              appended  at  the  location  offset, and the file will be length
41              bytes smaller.  The option --keep-size may not be specified  for
42              the collapse-range operation.
43
44              Available  since  Linux  3.15  for  ext4  (only for extent-based
45              files) and XFS.
46
47              A filesystem may place limitations on  the  granularity  of  the
48              operation,  in  order to ensure efficient implementation.  Typi‐
49              cally, offset and len must be a multiple of the filesystem logi‐
50              cal  block  size,  which varies according to the filesystem type
51              and configuration.  If a filesystem has such a requirement,  the
52              operation will fail with the error EINVAL if this requirement is
53              violated.
54
55       -d, --dig-holes
56              Detect and dig holes.  This  makes  the  file  sparse  in-place,
57              without  using  extra  disk space.  The minimum size of the hole
58              depends on filesystem  I/O  block  size  (usually  4096  bytes).
59              Also,  when  using  this  option, --keep-size is implied.  If no
60              range is specified by --offset and  --length,  then  the  entire
61              file is analyzed for holes.
62
63              You  can  think of this option as doing a "cp --sparse" and then
64              renaming the destination file to the original, without the  need
65              for extra disk space.
66
67              See --punch-hole for a list of supported filesystems.
68
69       -i, --insert-range
70              Insert  a  hole  of  length bytes from offset, shifting existing
71              data.
72
73       -l, --length length
74              Specifies the length of the range, in bytes.
75
76       -n, --keep-size
77              Do not modify the apparent length of the file.  This may  effec‐
78              tively  allocate  blocks  past  EOF, which can be removed with a
79              truncate.
80
81       -o, --offset offset
82              Specifies the beginning offset of the range, in bytes.
83
84       -p, --punch-hole
85              Deallocates space (i.e., creates  a  hole)  in  the  byte  range
86              starting  at offset and continuing for length bytes.  Within the
87              specified range, partial filesystem blocks are zeroed, and whole
88              filesystem blocks are removed from the file.  After a successful
89              call, subsequent reads from this range will return zeroes.  This
90              option may not be specified at the same time as the --zero-range
91              option.  Also, when using this option, --keep-size is implied.
92
93              Supported for XFS (since Linux 2.6.38), ext4 (since Linux  3.0),
94              Btrfs (since Linux 3.7), tmpfs (since Linux 3.5) and gfs2 (since
95              Linux 4.16).
96
97       -v, --verbose
98              Enable verbose mode.
99
100       -x, --posix
101              Enable POSIX operation mode.  In that mode allocation  operation
102              always  completes, but it may take longer time when fast alloca‐
103              tion is not supported by the underlying filesystem.
104
105       -z, --zero-range
106              Zeroes space in the byte range starting at offset and continuing
107              for length bytes.  Within the specified range, blocks are preal‐
108              located for the regions that span the holes in the file.   After
109              a  successful call, subsequent reads from this range will return
110              zeroes.
111
112              Zeroing is done within the filesystem preferably  by  converting
113              the  range into unwritten extents.  This approach means that the
114              specified range will not be physically zeroed out on the  device
115              (except  for partial blocks at the either end of the range), and
116              I/O is (otherwise) required only to update metadata.
117
118              Option --keep-size can be specified to prevent file length modi‐
119              fication.
120
121              Available  since  Linux  3.14  for  ext4  (only for extent-based
122              files) and XFS.
123
124       -V, --version
125              Display version information and exit.
126
127       -h, --help
128              Display help text and exit.
129

AUTHORS

131       Eric Sandeen ⟨sandeen@redhat.com⟩
132       Karel Zak ⟨kzak@redhat.com⟩
133

SEE ALSO

135       truncate(1), fallocate(2), posix_fallocate(3)
136

AVAILABILITY

138       The fallocate command is part of the util-linux package and  is  avail‐
139       able  from Linux Kernel Archive ⟨https://www.kernel.org/pub/linux/utils
140       /util-linux/⟩.
141
142
143
144util-linux                        April 2014                      FALLOCATE(1)
Impressum