original/man2/fallocate.2

   1 .\" Copyright (c) 2007 Silicon Graphics, Inc. All Rights Reserved
   2 .\" Written by Dave Chinner <dgc@sgi.com>
   3 .\" May be distributed as per GNU General Public License version 2.
   4 .\"
   5 .\" 2011-09-19: Added FALLOC_FL_PUNCH_HOLE
   6 .\" 2011-09-19: Substantial restructuring of the page
   7 .\"
   8 .TH FALLOCATE 2 2012-04-23 "Linux" "Linux Programmer's Manual"
   9 .SH NAME
  10 fallocate \- manipulate file space
  11 .SH SYNOPSIS
  12 .nf
  13 .BR "#define _GNU_SOURCE" "             /* See feature_test_macros(7) */"
  14 .B #include <fcntl.h>
  15
  16 .BI "int fallocate(int " fd ", int " mode ", off_t " offset \
  17 ", off_t " len ");
  18 .fi
  19 .SH DESCRIPTION
  20 This is a nonportable, Linux-specific system call.
  21 For the portable, POSIX.1-specified method of ensuring that space
  22 is allocated for a file, see
  23 .BR posix_fallocate (3).
  24
  25 .BR fallocate ()
  26 allows the caller to directly manipulate the allocated disk space
  27 for the file referred to by
  28 .I fd
  29 for the byte range starting at
  30 .I offset
  31 and continuing for
  32 .I len
  33 bytes.
  34
  35 The
  36 .I mode
  37 argument determines the operation to be performed on the given range.
  38 Details of the supported operations are given in the subsections below.
  39 .SS Allocating disk space
  40 The default operation (i.e.,
  41 .I mode
  42 is zero) of
  43 .BR fallocate ()
  44 allocates and initializes to zero the disk space
  45 within the range specified by
  46 .I offset
  47 and
  48 .IR len .
  49 The file size (as reported by
  50 .BR stat (2))
  51 will be changed if
  52 .IR offset + len
  53 is greater than the file size.
  54 This default behavior closely resembles the behavior of the
  55 .BR posix_fallocate (3)
  56 library function,
  57 and is intended as a method of optimally implementing that function.
  58
  59 After a successful call, subsequent writes into the range specified by
  60 .IR offset
  61 and
  62 .IR len
  63 are guaranteed not to fail because of lack of disk space.
  64
  65 If the
  66 .B FALLOC_FL_KEEP_SIZE
  67 flag is specified in
  68 .IR mode ,
  69 the behavior of the call is similar,
  70 but the file size will not be changed even if
  71 .IR offset + len
  72 is greater than the file size.
  73 Preallocating zeroed blocks beyond the end of the file in this manner
  74 is useful for optimizing append workloads.
  75 .PP
  76 Because allocation is done in block size chunks,
  77 .BR fallocate ()
  78 may allocate a larger range of disk space than was specified.
  79 .SS Deallocating file space
  80 Specifying the
  81 .BR FALLOC_FL_PUNCH_HOLE
  82 flag (available since Linux 2.6.38) in
  83 .I mode
  84 deallocates space (i.e., creates a hole)
  85 in the byte range starting at
  86 .I offset
  87 and continuing for
  88 .I len
  89 bytes.
  90 Within the specified range, partial file system blocks are zeroed,
  91 and whole file system blocks are removed from the file.
  92 After a successful call,
  93 subsequent reads from this range will return zeroes.
  94
  95 The
  96 .BR FALLOC_FL_PUNCH_HOLE
  97 flag must be ORed with
  98 .BR FALLOC_FL_KEEP_SIZE
  99 in
 100 .IR mode ;
 101 in other words, even when punching off the end of the file, the file size
 102 (as reported by
 103 .BR stat (2))
 104 does not change.
 105
 106 Not all file systems support
 107 .BR FALLOC_FL_PUNCH_HOLE ;
 108 if a file system doesn't support the operation, an error is returned.
 109 .SH RETURN VALUE
 110 .BR fallocate ()
 111 returns zero on success, and \-1 on failure.
 112 .SH ERRORS
 113 .TP
 114 .B EBADF
 115 .I fd
 116 is not a valid file descriptor, or is not opened for writing.
 117 .TP
 118 .B EFBIG
 119 .IR offset + len
 120 exceeds the maximum file size.
 121 .TP
 122 .B EINTR
 123 A signal was caught during execution.
 124 .TP
 125 .B EINVAL
 126 .I offset
 127 was less than 0, or
 128 .I len
 129 .\" FIXME (raise a kernel bug) Probably the len==0 case should be
 130 .\" a no-op, rather than an error. That would be consistent with
 131 .\" similar APIs for the len==0 case.
 132 .\" See "Re: [PATCH] fallocate.2: add FALLOC_FL_PUNCH_HOLE flag definition"
 133 .\" 21 Sep 2012
 134 .\" http://thread.gmane.org/gmane.linux.file-systems/48331/focus=1193526
 135 was less than or equal to 0.
 136 .TP
 137 .B EIO
 138 An I/O error occurred while reading from or writing to a file system.
 139 .TP
 140 .B ENODEV
 141 .I fd
 142 does not refer to a regular file or a directory.
 143 (If
 144 .I fd
 145 is a pipe or FIFO, a different error results.)
 146 .TP
 147 .B ENOSPC
 148 There is not enough space left on the device containing the file
 149 referred to by
 150 .IR fd .
 151 .TP
 152 .B ENOSYS
 153 This kernel does not implement
 154 .BR fallocate ().
 155 .TP
 156 .B EOPNOTSUPP
 157 The file system containing the file referred to by
 158 .I fd
 159 does not support this operation;
 160 or the
 161 .I mode
 162 is not supported by the file system containing the file referred to by
 163 .IR fd .
 164 .TP
 165 .B EPERM
 166 The file referred to by
 167 .I fd
 168 is marked immutable (see
 169 .BR chattr (1)).
 170 Or:
 171 .I mode
 172 specifies
 173 .BR FALLOC_FL_PUNCH_HOLE
 174 and
 175 the file referred to by
 176 .I fd
 177 is marked append-only
 178 (see
 179 .BR chattr (1)).
 180 .TP
 181 .B ESPIPE
 182 .I fd
 183 refers to a pipe or FIFO.
 184 .SH VERSIONS
 185 .BR fallocate ()
 186 is available on Linux since kernel 2.6.23.
 187 Support is provided by glibc since version 2.10.
 188 .SH CONFORMING TO
 189 .BR fallocate ()
 190 is Linux-specific.
 191 .SH SEE ALSO
 192 .BR ftruncate (2),
 193 .BR posix_fadvise (3),
 194 .BR posix_fallocate (3)