sys-utils/fallocate.1

   1 .TH FALLOCATE 1 "April 2014" "util-linux" "User Commands"
   2 .SH NAME
   3 fallocate \- preallocate or deallocate space to a file
   4 .SH SYNOPSIS
   5 .B fallocate
   6 .RB [ \-c | \-p | \-z ]
   7 .RB [ \-o
   8 .IR offset ]
   9 .B \-l
  10 .I length
  11 .RB [ \-n ]
  12 .I filename
  13 .PP
  14 .B fallocate \-d
  15 .RB [ \-o
  16 .IR offset ]
  17 .RB [ \-l
  18 .IR length ]
  19 .I filename
  20 .PP
  21 .B fallocate \-x
  22 .RB [ \-o
  23 .IR offset ]
  24 .B \-l
  25 .I length
  26 .I filename
  27 .SH DESCRIPTION
  28 .B fallocate
  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,
  32 preallocation is done quickly by allocating blocks and marking them as
  33 uninitialized, requiring no IO to the data blocks.
  34 This is much faster than creating a file by filling it with zeroes.
  35 .PP
  36 The exit code returned by
  37 .B fallocate
  38 is 0 on success and 1 on failure.
  39 .SH OPTIONS
  40 The
  41 .I length
  42 and
  43 .I offset
  44 arguments may be followed by the multiplicative suffixes KiB (=1024),
  45 MiB (=1024*1024), and so on for GiB, TiB, PiB, EiB, ZiB, and YiB (the "iB" is
  46 optional, e.g., "K" has the same meaning as "KiB") or the suffixes
  47 KB (=1000), MB (=1000*1000), and so on for GB, TB, PB, EB, ZB, and YB.
  48 .PP
  49 The options
  50 .BR \-\-collapse\-range ", " \-\-dig\-holes ", " \-\-punch\-hole ,
  51 and
  52 .B \-\-zero\-range
  53 are mutually exclusive.
  54 .TP
  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.
  73 .sp
  74 Available since Linux 3.15 for ext4 (only for extent-based files) and XFS.
  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.
  81 .TP
  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 ,
  93 then the entire file is analyzed for holes.
  94 .sp
  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.
  99 .sp
 100 See \fB\-\-punch\-hole\fP for a list of supported filesystems.
 101 .TP
 102 .BR \-i ", " \-\-insert\-range
 103 Insert a hole of
 104 .I length
 105 bytes from
 106 .IR offset ,
 107 shifting existing data.
 108 .TP
 109 .BR \-l ", " "\-\-length " \fIlength
 110 Specifies the length of the range, in bytes.
 111 .TP
 112 .BR \-n ", " \-\-keep\-size
 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
 116 .BR \-o ", " "\-\-offset " \fIoffset
 117 Specifies the beginning offset of the range, in bytes.
 118 .TP
 119 .BR \-p ", " \-\-punch\-hole
 120 Deallocates space (i.e., creates a hole) in the byte range starting at
 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.
 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
 139 .BR \-v ", " \-\-verbose
 140 Enable verbose mode.
 141 .TP
 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.
 147 .TP
 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.
 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
 170 .BR \-V ", " \-\-version
 171 Display version information and exit.
 172 .TP
 173 .BR \-h ", " \-\-help
 174 Display help text and exit.
 175 .SH AUTHORS
 176 .MT sandeen@redhat.com
 177 Eric Sandeen
 178 .ME
 179 .br
 180 .MT kzak@redhat.com
 181 Karel Zak
 182 .ME
 183 .SH SEE ALSO
 184 .BR truncate (1),
 185 .BR fallocate (2),
 186 .BR posix_fallocate (3)
 187 .SH AVAILABILITY
 188 The fallocate command is part of the util-linux package and is available from
 189 .UR https://\:www.kernel.org\:/pub\:/linux\:/utils\:/util-linux/
 190 Linux Kernel Archive
 191 .UE .