original/man2/fallocate.2

   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-01-22 "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.14)
 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.14)
 224 .\" commit 376ba313147b4172f3e8cf620b9fb591f3e8cdfa
 225 .IP *
 226 ext4, for extent-based files (since Linux 3.14)
 227 .\" commit b8a8684502a0fc852afa0056c6bb2a9273f6fcc0
 228 .SH RETURN VALUE
 229 On success,
 230 .BR fallocate ()
 231 returns zero.
 232 On error, \-1 is returned and
 233 .I errno
 234 is set to indicate the error.
 235 .SH ERRORS
 236 .TP
 237 .B EBADF
 238 .I fd
 239 is not a valid file descriptor, or is not opened for writing.
 240 .TP
 241 .B EFBIG
 242 .IR offset + len
 243 exceeds the maximum file size.
 244 .TP
 245 .B EINTR
 246 A signal was caught during execution.
 247 .TP
 248 .B EINVAL
 249 .I offset
 250 was less than 0, or
 251 .I len
 252 .\" FIXME . (raise a kernel bug) Probably the len==0 case should be
 253 .\" a no-op, rather than an error. That would be consistent with
 254 .\" similar APIs for the len==0 case.
 255 .\" See "Re: [PATCH] fallocate.2: add FALLOC_FL_PUNCH_HOLE flag definition"
 256 .\" 21 Sep 2012
 257 .\" http://thread.gmane.org/gmane.linux.file-systems/48331/focus=1193526
 258 was less than or equal to 0.
 259 .TP
 260 .B EINVAL
 261 .I mode
 262 is
 263 .BR FALLOC_FL_COLLAPSE_RANGE
 264 and the range specified by
 265 .I offset
 266 plus
 267 .I len
 268 reaches or passes the end of the file.
 269 .TP
 270 .B EINVAL
 271 .I mode
 272 is
 273 .BR FALLOC_FL_COLLAPSE_RANGE ,
 274 but either
 275 .I offset
 276 or
 277 .I len
 278 is not a multiple of the filesystem block size.
 279 .TP
 280 .B EINVAL
 281 .I mode
 282 contains both
 283 .B FALLOC_FL_COLLAPSE_RANGE
 284 and other flags;
 285 no other flags are permitted with
 286 .BR FALLOC_FL_COLLAPSE_RANGE .
 287 .TP
 288 .B EINVAL
 289 .I mode
 290 is
 291 .BR FALLOC_FL_COLLAPSE_RANGE
 292 or
 293 .BR FALLOC_FL_ZERO_RANGE ,
 294 but the file referred to by
 295 .I fd
 296 is not a regular file.
 297 .\" There was a inconsistency in 3.15-rc1, that should be resolved so that all
 298 .\" filesystems use this error for this case. (Tytso says ex4 will change.)
 299 .\" http://thread.gmane.org/gmane.comp.file-systems.xfs.general/60485/focus=5521
 300 .\" From: Michael Kerrisk (man-pages <mtk.manpages@...>
 301 .\" Subject: Re: [PATCH v5 10/10] manpage: update FALLOC_FL_COLLAPSE_RANGE flag in fallocate
 302 .\" Newsgroups: gmane.linux.man, gmane.linux.file-systems
 303 .\" Date: 2014-04-17 13:40:05 GMT
 304 .TP
 305 .B EIO
 306 An I/O error occurred while reading from or writing to a filesystem.
 307 .TP
 308 .B ENODEV
 309 .I fd
 310 does not refer to a regular file or a directory.
 311 (If
 312 .I fd
 313 is a pipe or FIFO, a different error results.)
 314 .TP
 315 .B ENOSPC
 316 There is not enough space left on the device containing the file
 317 referred to by
 318 .IR fd .
 319 .TP
 320 .B ENOSYS
 321 This kernel does not implement
 322 .BR fallocate ().
 323 .TP
 324 .B EOPNOTSUPP
 325 The filesystem containing the file referred to by
 326 .I fd
 327 does not support this operation;
 328 or the
 329 .I mode
 330 is not supported by the filesystem containing the file referred to by
 331 .IR fd .
 332 .TP
 333 .B EPERM
 334 The file referred to by
 335 .I fd
 336 is marked immutable (see
 337 .BR chattr (1)).
 338 .TP
 339 .B EPERM
 340 .I mode
 341 specifies
 342 .BR FALLOC_FL_PUNCH_HOLE
 343 or
 344 .BR FALLOC_FL_COLLAPSE_RANGE
 345 and
 346 the file referred to by
 347 .I fd
 348 is marked append-only
 349 (see
 350 .BR chattr (1)).
 351 .TP
 352 .B EPERM
 353 The operation was prevented by a file seal; see
 354 .BR fcntl (2).
 355 .TP
 356 .B ESPIPE
 357 .I fd
 358 refers to a pipe or FIFO.
 359 .TP
 360 .B ETXTBSY
 361 .I mode
 362 specifies
 363 .BR FALLOC_FL_COLLAPSE_RANGE ,
 364 but the file referred to by
 365 .IR fd
 366 is currently being executed.
 367 .SH VERSIONS
 368 .BR fallocate ()
 369 is available on Linux since kernel 2.6.23.
 370 Support is provided by glibc since version 2.10.
 371 The
 372 .BR FALLOC_FL_*
 373 flags are defined in glibc headers only since version 2.18.
 374 .\" See http://sourceware.org/bugzilla/show_bug.cgi?id=14964
 375 .SH CONFORMING TO
 376 .BR fallocate ()
 377 is Linux-specific.
 378 .SH SEE ALSO
 379 .BR fallocate (1),
 380 .BR ftruncate (2),
 381 .BR posix_fadvise (3),
 382 .BR posix_fallocate (3)
 383 .SH COLOPHON
 384 This page is part of release 3.78 of the Linux
 385 .I man-pages
 386 project.
 387 A description of the project,
 388 information about reporting bugs,
 389 and the latest version of this page,
 390 can be found at
 391 \%http://www.kernel.org/doc/man\-pages/.