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 2014-04-17 "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 .SH RETURN VALUE
 184 On success,
 185 .BR fallocate ()
 186 returns zero.
 187 On error, \-1 is returned and
 188 .I errno
 189 is set to indicate the error.
 190 .SH ERRORS
 191 .TP
 192 .B EBADF
 193 .I fd
 194 is not a valid file descriptor, or is not opened for writing.
 195 .TP
 196 .B EFBIG
 197 .IR offset + len
 198 exceeds the maximum file size.
 199 .TP
 200 .B EINTR
 201 A signal was caught during execution.
 202 .TP
 203 .B EINVAL
 204 .I offset
 205 was less than 0, or
 206 .I len
 207 .\" FIXME (raise a kernel bug) Probably the len==0 case should be
 208 .\" a no-op, rather than an error. That would be consistent with
 209 .\" similar APIs for the len==0 case.
 210 .\" See "Re: [PATCH] fallocate.2: add FALLOC_FL_PUNCH_HOLE flag definition"
 211 .\" 21 Sep 2012
 212 .\" http://thread.gmane.org/gmane.linux.file-systems/48331/focus=1193526
 213 was less than or equal to 0.
 214 .TP
 215 .B EINVAL
 216 .I mode
 217 is
 218 .BR FALLOC_FL_COLLAPSE_RANGE
 219 and the range specified by
 220 .I offset
 221 plus
 222 .I len
 223 reaches or passes the end of the file.
 224 .TP
 225 .B EINVAL
 226 .I mode
 227 is
 228 .BR FALLOC_FL_COLLAPSE_RANGE ,
 229 but either
 230 .I offset
 231 or
 232 .I len
 233 is not a multiple of the filesystem block size.
 234 .TP
 235 .B EINVAL
 236 mode contains both
 237 .B FALLOC_FL_COLLAPSE_RANGE
 238 and other flags;
 239 no other flags are permitted with
 240 .BR FALLOC_FL_COLLAPSE_RANGE .
 241 .TP EINVAL
 242 .I mode
 243 is
 244 .BR FALLOC_FL_COLLAPSE_RANGE ,
 245 but the file referred to by
 246 .I fd
 247 is not a regular file.
 248 .\" There was a inconsistency in 3.15-rc1, that should be resolved so that all
 249 .\" filesystems use this error for this case. (Tytso says ex4 will change.)
 250 .\" http://thread.gmane.org/gmane.comp.file-systems.xfs.general/60485/focus=5521
 251 .\" From: Michael Kerrisk (man-pages <mtk.manpages@...>
 252 .\" Subject: Re: [PATCH v5 10/10] manpage: update FALLOC_FL_COLLAPSE_RANGE flag in fallocate
 253 .\" Newsgroups: gmane.linux.man, gmane.linux.file-systems
 254 .\" Date: 2014-04-17 13:40:05 GMT
 255 .TP
 256 .B EIO
 257 An I/O error occurred while reading from or writing to a filesystem.
 258 .TP
 259 .B ENODEV
 260 .I fd
 261 does not refer to a regular file or a directory.
 262 (If
 263 .I fd
 264 is a pipe or FIFO, a different error results.)
 265 .TP
 266 .B ENOSPC
 267 There is not enough space left on the device containing the file
 268 referred to by
 269 .IR fd .
 270 .TP
 271 .B ENOSYS
 272 This kernel does not implement
 273 .BR fallocate ().
 274 .TP
 275 .B EOPNOTSUPP
 276 The filesystem containing the file referred to by
 277 .I fd
 278 does not support this operation;
 279 or the
 280 .I mode
 281 is not supported by the filesystem containing the file referred to by
 282 .IR fd .
 283 .TP
 284 .B EPERM
 285 The file referred to by
 286 .I fd
 287 is marked immutable (see
 288 .BR chattr (1)).
 289 Or:
 290 .I mode
 291 specifies
 292 .BR FALLOC_FL_PUNCH_HOLE
 293 or
 294 .BR FALLOC_FL_COLLAPSE_RANGE
 295 and
 296 the file referred to by
 297 .I fd
 298 is marked append-only
 299 (see
 300 .BR chattr (1)).
 301 .TP
 302 .B ESPIPE
 303 .I fd
 304 refers to a pipe or FIFO.
 305 .TP
 306 .B ETXTBSY
 307 .I mode
 308 specifies
 309 .BR FALLOC_FL_COLLAPSE_RANGE ,
 310 but the file referred to by
 311 .IR fd
 312 is currently being executed.
 313 .SH VERSIONS
 314 .BR fallocate ()
 315 is available on Linux since kernel 2.6.23.
 316 Support is provided by glibc since version 2.10.
 317 The
 318 .BR FALLOC_FL_*
 319 flags are defined in glibc headers only since version 2.18.
 320 .\" See http://sourceware.org/bugzilla/show_bug.cgi?id=14964
 321 .SH CONFORMING TO
 322 .BR fallocate ()
 323 is Linux-specific.
 324 .SH SEE ALSO
 325 .BR fallocate (1),
 326 .BR ftruncate (2),
 327 .BR posix_fadvise (3),
 328 .BR posix_fallocate (3)
 329 .SH COLOPHON
 330 This page is part of release 3.65 of the Linux
 331 .I man-pages
 332 project.
 333 A description of the project,
 334 and information about reporting bugs,
 335 can be found at
 336 \%http://www.kernel.org/doc/man\-pages/.