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 2016-03-15 "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
  83 If the
  84 .B FALLOC_FL_UNSHARE
  85 flag is specified in
  86 .IR mode ,
  87 shared file data extents will be made private to the file to guarantee
  88 that a subsequent write will not fail due to lack of space.
  89 Typically, this will be done by performing a copy-on-write operation on
  90 all shared data in the file.
  91 This flag may not be supported by all filesystems.
  92 .PP
  93 Because allocation is done in block size chunks,
  94 .BR fallocate ()
  95 may allocate a larger range of disk space than was specified.
  96 .SS Deallocating file space
  97 Specifying the
  98 .BR FALLOC_FL_PUNCH_HOLE
  99 flag (available since Linux 2.6.38) in
 100 .I mode
 101 deallocates space (i.e., creates a hole)
 102 in the byte range starting at
 103 .I offset
 104 and continuing for
 105 .I len
 106 bytes.
 107 Within the specified range, partial filesystem blocks are zeroed,
 108 and whole filesystem blocks are removed from the file.
 109 After a successful call,
 110 subsequent reads from this range will return zeroes.
 111
 112 The
 113 .BR FALLOC_FL_PUNCH_HOLE
 114 flag must be ORed with
 115 .BR FALLOC_FL_KEEP_SIZE
 116 in
 117 .IR mode ;
 118 in other words, even when punching off the end of the file, the file size
 119 (as reported by
 120 .BR stat (2))
 121 does not change.
 122
 123 Not all filesystems support
 124 .BR FALLOC_FL_PUNCH_HOLE ;
 125 if a filesystem doesn't support the operation, an error is returned.
 126 The operation is supported on at least the following filesystems:
 127 .IP * 3
 128 XFS (since Linux 2.6.38)
 129 .IP *
 130 ext4 (since Linux 3.0)
 131 .\" commit a4bb6b64e39abc0e41ca077725f2a72c868e7622
 132 .IP *
 133 Btrfs (since Linux 3.7)
 134 .IP *
 135 .BR tmpfs "(5) (since Linux 3.5)"
 136 .\" commit 83e4fa9c16e4af7122e31be3eca5d57881d236fe
 137 .SS Collapsing file space
 138 .\" commit 00f5e61998dd17f5375d9dfc01331f104b83f841
 139 Specifying the
 140 .BR FALLOC_FL_COLLAPSE_RANGE
 141 flag (available since Linux 3.15) in
 142 .I mode
 143 removes a byte range from a file, without leaving a hole.
 144 The byte range to be collapsed starts at
 145 .I offset
 146 and continues for
 147 .I len
 148 bytes.
 149 At the completion of the operation,
 150 the contents of the file starting at the location
 151 .I offset+len
 152 will be appended at the location
 153 .IR offset ,
 154 and the file will be
 155 .I len
 156 bytes smaller.
 157
 158 A filesystem may place limitations on the granularity of the operation,
 159 in order to ensure efficient implementation.
 160 Typically,
 161 .I offset
 162 and
 163 .I len
 164 must be a multiple of the filesystem logical block size,
 165 which varies according to the filesystem type and configuration.
 166 If a filesystem has such a requirement,
 167 .BR fallocate ()
 168 will fail with the error
 169 .BR EINVAL
 170 if this requirement is violated.
 171
 172 If the region specified by
 173 .I offset
 174 plus
 175 .I len
 176 reaches or passes the end of file, an error is returned;
 177 instead, use
 178 .BR ftruncate (2)
 179 to truncate a file.
 180
 181 No other flags may be specified in
 182 .IR mode
 183 in conjunction with
 184 .BR FALLOC_FL_COLLAPSE_RANGE .
 185
 186 As at Linux 3.15,
 187 .B FALLOC_FL_COLLAPSE_RANGE
 188 is supported by
 189 ext4 (only for extent-based files)
 190 .\" commit 9eb79482a97152930b113b51dff530aba9e28c8e
 191 and XFS.
 192 .\" commit e1d8fb88a64c1f8094b9f6c3b6d2d9e6719c970d
 193 .SS Zeroing file space
 194 Specifying the
 195 .BR FALLOC_FL_ZERO_RANGE
 196 flag (available since Linux 3.15)
 197 .\" commit 409332b65d3ed8cfa7a8030f1e9d52f372219642
 198 in
 199 .I mode
 200 zeroes space in the byte range starting at
 201 .I offset
 202 and continuing for
 203 .I len
 204 bytes.
 205 Within the specified range, blocks are preallocated for the regions
 206 that span the holes in the file.
 207 After a successful call, subsequent
 208 reads from this range will return zeroes.
 209
 210 Zeroing is done within the filesystem preferably by converting the range into
 211 unwritten extents.
 212 This approach means that the specified range will not be physically zeroed
 213 out on the device (except for partial blocks at the either end of the range),
 214 and I/O is (otherwise) required only to update metadata.
 215
 216 If the
 217 .B FALLOC_FL_KEEP_SIZE
 218 flag is additionally specified in
 219 .IR mode ,
 220 the behavior of the call is similar,
 221 but the file size will not be changed even if
 222 .IR offset + len
 223 is greater than the file size.
 224 This behavior is the same as when preallocating space with
 225 .B FALLOC_FL_KEEP_SIZE
 226 specified.
 227
 228 Not all filesystems support
 229 .BR FALLOC_FL_ZERO_RANGE ;
 230 if a filesystem doesn't support the operation, an error is returned.
 231 The operation is supported on at least the following filesystems:
 232 .IP * 3
 233 XFS (since Linux 3.15)
 234 .\" commit 376ba313147b4172f3e8cf620b9fb591f3e8cdfa
 235 .IP *
 236 ext4, for extent-based files (since Linux 3.15)
 237 .\" commit b8a8684502a0fc852afa0056c6bb2a9273f6fcc0
 238 .IP *
 239 SMB3 (since Linux 3.17)
 240 .\" commit 30175628bf7f521e9ee31ac98fa6d6fe7441a556
 241 .SS Increasing file space
 242 Specifying the
 243 .BR FALLOC_FL_INSERT_RANGE
 244 flag
 245 (available since Linux 4.1)
 246 .\" commit dd46c787788d5bf5b974729d43e4c405814a4c7d
 247 in
 248 .I mode
 249 increases the file space by inserting a hole within the file size without
 250 overwriting any existing data.
 251 The hole will start at
 252 .I offset
 253 and continue for
 254 .I len
 255 bytes.
 256 When inserting the hole inside file, the contents of the file starting at
 257 .I offset
 258 will be shifted upward (i.e., to a higher file offset) by
 259 .I len
 260 bytes.
 261 Inserting a hole inside a file increases the file size by
 262 .I len
 263 bytes.
 264
 265 This mode has the same limitations as
 266 .BR FALLOC_FL_COLLAPSE_RANGE
 267 regarding the granularity of the operation.
 268 If the granularity requirements are not met,
 269 .BR fallocate ()
 270 will fail with the error
 271 .BR EINVAL.
 272 If the
 273 .I offset
 274 is equal to or greater than the end of file, an error is returned.
 275 For such operations (i.e., inserting a hole at the end of file),
 276 .BR ftruncate (2)
 277 should be used.
 278
 279 No other flags may be specified in
 280 .IR mode
 281 in conjunction with
 282 .BR FALLOC_FL_INSERT_RANGE .
 283
 284 .B FALLOC_FL_INSERT_RANGE
 285 requires filesystem support.
 286 Filesystems that support this operation include
 287 XFS (since Linux 4.1)
 288 .\" commit a904b1ca5751faf5ece8600e18cd3b674afcca1b
 289 and ext4 (since Linux 4.2).
 290 .\" commit 331573febb6a224bc50322e3670da326cb7f4cfc
 291 .\" f2fs also has support since Linux 4.2
 292 .\"     commit f62185d0e283e9d311e3ac1020f159d95f0aab39
 293 .SH RETURN VALUE
 294 On success,
 295 .BR fallocate ()
 296 returns zero.
 297 On error, \-1 is returned and
 298 .I errno
 299 is set to indicate the error.
 300 .SH ERRORS
 301 .TP
 302 .B EBADF
 303 .I fd
 304 is not a valid file descriptor, or is not opened for writing.
 305 .TP
 306 .B EFBIG
 307 .IR offset + len
 308 exceeds the maximum file size.
 309 .TP
 310 .B EFBIG
 311 .I mode
 312 is
 313 .BR FALLOC_FL_INSERT_RANGE ,
 314 and the current file size+\fIlen\fP exceeds the maximum file size.
 315 .TP
 316 .B EINTR
 317 A signal was caught during execution; see
 318 .BR signal (7).
 319 .TP
 320 .B EINVAL
 321 .I offset
 322 was less than 0, or
 323 .I len
 324 .\" FIXME . (raise a kernel bug) Probably the len==0 case should be
 325 .\" a no-op, rather than an error. That would be consistent with
 326 .\" similar APIs for the len==0 case.
 327 .\" See "Re: [PATCH] fallocate.2: add FALLOC_FL_PUNCH_HOLE flag definition"
 328 .\" 21 Sep 2012
 329 .\" http://thread.gmane.org/gmane.linux.file-systems/48331/focus=1193526
 330 was less than or equal to 0.
 331 .TP
 332 .B EINVAL
 333 .I mode
 334 is
 335 .BR FALLOC_FL_COLLAPSE_RANGE
 336 and the range specified by
 337 .I offset
 338 plus
 339 .I len
 340 reaches or passes the end of the file.
 341 .TP
 342 .B EINVAL
 343 .I mode
 344 is
 345 .BR FALLOC_FL_INSERT_RANGE
 346 and the range specified by
 347 .I offset
 348 reaches or passes the end of the file.
 349 .TP
 350 .B EINVAL
 351 .I mode
 352 is
 353 .BR FALLOC_FL_COLLAPSE_RANGE
 354 or
 355 .BR FALLOC_FL_INSERT_RANGE ,
 356 but either
 357 .I offset
 358 or
 359 .I len
 360 is not a multiple of the filesystem block size.
 361 .TP
 362 .B EINVAL
 363 .I mode
 364 contains one of
 365 .B FALLOC_FL_COLLAPSE_RANGE
 366 or
 367 .B FALLOC_FL_INSERT_RANGE
 368 and also other flags;
 369 no other flags are permitted with
 370 .BR FALLOC_FL_COLLAPSE_RANGE
 371 or
 372 .BR FALLOC_FL_INSERT_RANGE .
 373 .TP
 374 .B EINVAL
 375 .I mode
 376 is
 377 .BR FALLOC_FL_COLLAPSE_RANGE
 378 or
 379 .BR FALLOC_FL_ZERO_RANGE
 380 or
 381 .BR FALLOC_FL_INSERT_RANGE ,
 382 but the file referred to by
 383 .I fd
 384 is not a regular file.
 385 .\" There was a inconsistency in 3.15-rc1, that should be resolved so that all
 386 .\" filesystems use this error for this case. (Tytso says ex4 will change.)
 387 .\" http://thread.gmane.org/gmane.comp.file-systems.xfs.general/60485/focus=5521
 388 .\" From: Michael Kerrisk (man-pages <mtk.manpages@...>
 389 .\" Subject: Re: [PATCH v5 10/10] manpage: update FALLOC_FL_COLLAPSE_RANGE flag in fallocate
 390 .\" Newsgroups: gmane.linux.man, gmane.linux.file-systems
 391 .\" Date: 2014-04-17 13:40:05 GMT
 392 .TP
 393 .B EIO
 394 An I/O error occurred while reading from or writing to a filesystem.
 395 .TP
 396 .B ENODEV
 397 .I fd
 398 does not refer to a regular file or a directory.
 399 (If
 400 .I fd
 401 is a pipe or FIFO, a different error results.)
 402 .TP
 403 .B ENOSPC
 404 There is not enough space left on the device containing the file
 405 referred to by
 406 .IR fd .
 407 .TP
 408 .B ENOSYS
 409 This kernel does not implement
 410 .BR fallocate ().
 411 .TP
 412 .B EOPNOTSUPP
 413 The filesystem containing the file referred to by
 414 .I fd
 415 does not support this operation;
 416 or the
 417 .I mode
 418 is not supported by the filesystem containing the file referred to by
 419 .IR fd .
 420 .TP
 421 .B EPERM
 422 The file referred to by
 423 .I fd
 424 is marked immutable (see
 425 .BR chattr (1)).
 426 .TP
 427 .B EPERM
 428 .I mode
 429 specifies
 430 .BR FALLOC_FL_PUNCH_HOLE
 431 or
 432 .BR FALLOC_FL_COLLAPSE_RANGE
 433 or
 434 .BR FALLOC_FL_INSERT_RANGE
 435 and
 436 the file referred to by
 437 .I fd
 438 is marked append-only
 439 (see
 440 .BR chattr (1)).
 441 .TP
 442 .B EPERM
 443 The operation was prevented by a file seal; see
 444 .BR fcntl (2).
 445 .TP
 446 .B ESPIPE
 447 .I fd
 448 refers to a pipe or FIFO.
 449 .TP
 450 .B ETXTBSY
 451 .I mode
 452 specifies
 453 .BR FALLOC_FL_COLLAPSE_RANGE
 454 or
 455 .BR FALLOC_FL_INSERT_RANGE ,
 456 but the file referred to by
 457 .IR fd
 458 is currently being executed.
 459 .SH VERSIONS
 460 .BR fallocate ()
 461 is available on Linux since kernel 2.6.23.
 462 Support is provided by glibc since version 2.10.
 463 The
 464 .BR FALLOC_FL_*
 465 flags are defined in glibc headers only since version 2.18.
 466 .\" See http://sourceware.org/bugzilla/show_bug.cgi?id=14964
 467 .SH CONFORMING TO
 468 .BR fallocate ()
 469 is Linux-specific.
 470 .SH SEE ALSO
 471 .BR fallocate (1),
 472 .BR ftruncate (2),
 473 .BR posix_fadvise (3),
 474 .BR posix_fallocate (3)