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-01-24 "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 .SH RETURN VALUE
 128 On success,
 129 .BR fallocate ()
 130 returns zero.
 131 On error, \-1 is returned and
 132 .I errno
 133 is set to indicate the error.
 134 .SH ERRORS
 135 .TP
 136 .B EBADF
 137 .I fd
 138 is not a valid file descriptor, or is not opened for writing.
 139 .TP
 140 .B EFBIG
 141 .IR offset + len
 142 exceeds the maximum file size.
 143 .TP
 144 .B EINTR
 145 A signal was caught during execution.
 146 .TP
 147 .B EINVAL
 148 .I offset
 149 was less than 0, or
 150 .I len
 151 .\" FIXME (raise a kernel bug) Probably the len==0 case should be
 152 .\" a no-op, rather than an error. That would be consistent with
 153 .\" similar APIs for the len==0 case.
 154 .\" See "Re: [PATCH] fallocate.2: add FALLOC_FL_PUNCH_HOLE flag definition"
 155 .\" 21 Sep 2012
 156 .\" http://thread.gmane.org/gmane.linux.file-systems/48331/focus=1193526
 157 was less than or equal to 0.
 158 .TP
 159 .B EIO
 160 An I/O error occurred while reading from or writing to a filesystem.
 161 .TP
 162 .B ENODEV
 163 .I fd
 164 does not refer to a regular file or a directory.
 165 (If
 166 .I fd
 167 is a pipe or FIFO, a different error results.)
 168 .TP
 169 .B ENOSPC
 170 There is not enough space left on the device containing the file
 171 referred to by
 172 .IR fd .
 173 .TP
 174 .B ENOSYS
 175 This kernel does not implement
 176 .BR fallocate ().
 177 .TP
 178 .B EOPNOTSUPP
 179 The filesystem containing the file referred to by
 180 .I fd
 181 does not support this operation;
 182 or the
 183 .I mode
 184 is not supported by the filesystem containing the file referred to by
 185 .IR fd .
 186 .TP
 187 .B EPERM
 188 The file referred to by
 189 .I fd
 190 is marked immutable (see
 191 .BR chattr (1)).
 192 Or:
 193 .I mode
 194 specifies
 195 .BR FALLOC_FL_PUNCH_HOLE
 196 and
 197 the file referred to by
 198 .I fd
 199 is marked append-only
 200 (see
 201 .BR chattr (1)).
 202 .TP
 203 .B ESPIPE
 204 .I fd
 205 refers to a pipe or FIFO.
 206 .SH VERSIONS
 207 .BR fallocate ()
 208 is available on Linux since kernel 2.6.23.
 209 Support is provided by glibc since version 2.10.
 210 The
 211 .BR FALLOC_FL_*
 212 flags are defined in glibc headers only since version 2.18.
 213 .\" See http://sourceware.org/bugzilla/show_bug.cgi?id=14964
 214 .SH CONFORMING TO
 215 .BR fallocate ()
 216 is Linux-specific.
 217 .SH SEE ALSO
 218 .BR fallocate (1),
 219 .BR ftruncate (2),
 220 .BR posix_fadvise (3),
 221 .BR posix_fallocate (3)
 222 .SH COLOPHON
 223 This page is part of release 3.64 of the Linux
 224 .I man-pages
 225 project.
 226 A description of the project,
 227 and information about reporting bugs,
 228 can be found at
 229 \%http://www.kernel.org/doc/man\-pages/.