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 2013-02-12 "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 and initializes to zero the disk space
  48 within the range specified by
  49 .I offset
  50 and
  51 .IR len .
  52 The file size (as reported by
  53 .BR stat (2))
  54 will be changed if
  55 .IR offset + len
  56 is greater than the file size.
  57 This default behavior closely resembles the behavior of the
  58 .BR posix_fallocate (3)
  59 library function,
  60 and is intended as a method of optimally implementing that function.
  61
  62 After a successful call, subsequent writes into the range specified by
  63 .IR offset
  64 and
  65 .IR len
  66 are guaranteed not to fail because of lack of disk space.
  67
  68 If the
  69 .B FALLOC_FL_KEEP_SIZE
  70 flag is specified in
  71 .IR mode ,
  72 the behavior of the call is similar,
  73 but the file size will not be changed even if
  74 .IR offset + len
  75 is greater than the file size.
  76 Preallocating zeroed blocks beyond the end of the file in this manner
  77 is useful for optimizing append workloads.
  78 .PP
  79 Because allocation is done in block size chunks,
  80 .BR fallocate ()
  81 may allocate a larger range of disk space than was specified.
  82 .SS Deallocating file space
  83 Specifying the
  84 .BR FALLOC_FL_PUNCH_HOLE
  85 flag (available since Linux 2.6.38) in
  86 .I mode
  87 deallocates space (i.e., creates a hole)
  88 in the byte range starting at
  89 .I offset
  90 and continuing for
  91 .I len
  92 bytes.
  93 Within the specified range, partial file system blocks are zeroed,
  94 and whole file system blocks are removed from the file.
  95 After a successful call,
  96 subsequent reads from this range will return zeroes.
  97
  98 The
  99 .BR FALLOC_FL_PUNCH_HOLE
 100 flag must be ORed with
 101 .BR FALLOC_FL_KEEP_SIZE
 102 in
 103 .IR mode ;
 104 in other words, even when punching off the end of the file, the file size
 105 (as reported by
 106 .BR stat (2))
 107 does not change.
 108
 109 Not all file systems support
 110 .BR FALLOC_FL_PUNCH_HOLE ;
 111 if a file system doesn't support the operation, an error is returned.
 112 .SH RETURN VALUE
 113 .BR fallocate ()
 114 returns zero on success, and \-1 on failure.
 115 .SH ERRORS
 116 .TP
 117 .B EBADF
 118 .I fd
 119 is not a valid file descriptor, or is not opened for writing.
 120 .TP
 121 .B EFBIG
 122 .IR offset + len
 123 exceeds the maximum file size.
 124 .TP
 125 .B EINTR
 126 A signal was caught during execution.
 127 .TP
 128 .B EINVAL
 129 .I offset
 130 was less than 0, or
 131 .I len
 132 .\" FIXME (raise a kernel bug) Probably the len==0 case should be
 133 .\" a no-op, rather than an error. That would be consistent with
 134 .\" similar APIs for the len==0 case.
 135 .\" See "Re: [PATCH] fallocate.2: add FALLOC_FL_PUNCH_HOLE flag definition"
 136 .\" 21 Sep 2012
 137 .\" http://thread.gmane.org/gmane.linux.file-systems/48331/focus=1193526
 138 was less than or equal to 0.
 139 .TP
 140 .B EIO
 141 An I/O error occurred while reading from or writing to a file system.
 142 .TP
 143 .B ENODEV
 144 .I fd
 145 does not refer to a regular file or a directory.
 146 (If
 147 .I fd
 148 is a pipe or FIFO, a different error results.)
 149 .TP
 150 .B ENOSPC
 151 There is not enough space left on the device containing the file
 152 referred to by
 153 .IR fd .
 154 .TP
 155 .B ENOSYS
 156 This kernel does not implement
 157 .BR fallocate ().
 158 .TP
 159 .B EOPNOTSUPP
 160 The file system containing the file referred to by
 161 .I fd
 162 does not support this operation;
 163 or the
 164 .I mode
 165 is not supported by the file system containing the file referred to by
 166 .IR fd .
 167 .TP
 168 .B EPERM
 169 The file referred to by
 170 .I fd
 171 is marked immutable (see
 172 .BR chattr (1)).
 173 Or:
 174 .I mode
 175 specifies
 176 .BR FALLOC_FL_PUNCH_HOLE
 177 and
 178 the file referred to by
 179 .I fd
 180 is marked append-only
 181 (see
 182 .BR chattr (1)).
 183 .TP
 184 .B ESPIPE
 185 .I fd
 186 refers to a pipe or FIFO.
 187 .SH VERSIONS
 188 .BR fallocate ()
 189 is available on Linux since kernel 2.6.23.
 190 Support is provided by glibc since version 2.10.
 191 The
 192 .BR FALLOC_FL_*
 193 flags are defined in glibc headers only since version 2.18.
 194 .\" See http://sourceware.org/bugzilla/show_bug.cgi?id=14964
 195 .SH CONFORMING TO
 196 .BR fallocate ()
 197 is Linux-specific.
 198 .SH SEE ALSO
 199 .BR fallocate (1),
 200 .BR ftruncate (2),
 201 .BR posix_fadvise (3),
 202 .BR posix_fallocate (3)