man3/posix_fallocate.3

   1 .\" Copyright (c) 2006, Michael Kerrisk <mtk.manpages@gmail.com>
   2 .\"
   3 .\" %%%LICENSE_START(VERBATIM)
   4 .\" Permission is granted to make and distribute verbatim copies of this
   5 .\" manual provided the copyright notice and this permission notice are
   6 .\" preserved on all copies.
   7 .\"
   8 .\" Permission is granted to copy and distribute modified versions of this
   9 .\" manual under the conditions for verbatim copying, provided that the
  10 .\" entire resulting derived work is distributed under the terms of a
  11 .\" permission notice identical to this one.
  12 .\"
  13 .\" Since the Linux kernel and libraries are constantly changing, this
  14 .\" manual page may be incorrect or out-of-date.  The author(s) assume no
  15 .\" responsibility for errors or omissions, or for damages resulting from
  16 .\" the use of the information contained herein.  The author(s) may not
  17 .\" have taken the same level of care in the production of this manual,
  18 .\" which is licensed free of charge, as they might when working
  19 .\" professionally.
  20 .\"
  21 .\" Formatted or processed versions of this manual, if unaccompanied by
  22 .\" the source, must acknowledge the copyright and authors of this work.
  23 .\" %%%LICENSE_END
  24 .\"
  25 .TH POSIX_FALLOCATE 3  2017-09-15 "GNU" "Linux Programmer's Manual"
  26 .SH NAME
  27 posix_fallocate \- allocate file space
  28 .SH SYNOPSIS
  29 .nf
  30 .B #include <fcntl.h>
  31 .PP
  32 .BI "int posix_fallocate(int " fd ", off_t " offset ", off_t " len );
  33 .fi
  34 .PP
  35 .ad l
  36 .in -4n
  37 Feature Test Macro Requirements for glibc (see
  38 .BR feature_test_macros (7)):
  39 .in
  40 .PP
  41 .BR posix_fallocate ():
  42 .RS 4
  43 _POSIX_C_SOURCE\ >=\ 200112L
  44 .RE
  45 .ad
  46 .SH DESCRIPTION
  47 The function
  48 .BR posix_fallocate ()
  49 ensures that disk space is allocated for the file referred to by the
  50 file descriptor
  51 .I fd
  52 for the bytes in the range starting at
  53 .I offset
  54 and continuing for
  55 .I len
  56 bytes.
  57 After a successful call to
  58 .BR posix_fallocate (),
  59 subsequent writes to bytes in the specified range are
  60 guaranteed not to fail because of lack of disk space.
  61 .PP
  62 If the size of the file is less than
  63 .IR offset + len ,
  64 then the file is increased to this size;
  65 otherwise the file size is left unchanged.
  66 .SH RETURN VALUE
  67 .BR posix_fallocate ()
  68 returns zero on success, or an error number on failure.
  69 Note that
  70 .I errno
  71 is not set.
  72 .SH ERRORS
  73 .TP
  74 .B EBADF
  75 .I fd
  76 is not a valid file descriptor, or is not opened for writing.
  77 .TP
  78 .B EFBIG
  79 .I offset+len
  80 exceeds the maximum file size.
  81 .TP
  82 .B EINTR
  83 A signal was caught during execution.
  84 .TP
  85 .B EINVAL
  86 .I offset
  87 was less than 0, or
  88 .I len
  89 was less than or equal to 0, or the underlying filesystem does not
  90 support the operation.
  91 .TP
  92 .B ENODEV
  93 .I fd
  94 does not refer to a regular file.
  95 .TP
  96 .B ENOSPC
  97 There is not enough space left on the device containing the file
  98 referred to by
  99 .IR fd .
 100 .TP
 101 .B ESPIPE
 102 .I fd
 103 refers to a pipe.
 104 .SH VERSIONS
 105 .BR posix_fallocate ()
 106 is available since glibc 2.1.94.
 107 .SH ATTRIBUTES
 108 For an explanation of the terms used in this section, see
 109 .BR attributes (7).
 110 .TS
 111 allbox;
 112 lb lb lb
 113 l l l.
 114 Interface       Attribute       Value
 115 T{
 116 .BR posix_fallocate ()
 117 T}      Thread safety   MT-Safe (but see NOTES)
 118 .TE
 119 .SH CONFORMING TO
 120 POSIX.1-2001.
 121 .PP
 122 POSIX.1-2008 says that an implementation
 123 .I shall
 124 give the
 125 .B EINVAL
 126 error if
 127 .I len
 128 was 0, or
 129 .I offset
 130 was less than 0.
 131 POSIX.1-2001 says that an implementation
 132 .I shall
 133 give the
 134 .B EINVAL
 135 error if
 136 .I len
 137 is less than 0, or
 138 .I offset
 139 was less than 0, and
 140 .I may
 141 give the error if
 142 .I len
 143 equals zero.
 144 .SH NOTES
 145 In the glibc implementation,
 146 .BR posix_fallocate ()
 147 is implemented using the
 148 .BR fallocate (2)
 149 system call, which is MT-safe.
 150 If the underlying filesystem does not support
 151 .BR fallocate (2),
 152 then the operation is emulated with the following caveats:
 153 .IP * 2
 154 The emulation is inefficient.
 155 .IP *
 156 There is a race condition where concurrent writes from another thread or
 157 process could be overwritten with null bytes.
 158 .IP *
 159 There is a race condition where concurrent file size increases by
 160 another thread or process could result in a file whose size is smaller
 161 than expected.
 162 .IP *
 163 If
 164 .I fd
 165 has been opened with the
 166 .B O_APPEND
 167 or
 168 .B O_WRONLY
 169 flags, the function fails with the error
 170 .BR EBADF .
 171 .PP
 172 In general, the emulation is not MT-safe.
 173 On Linux, applications may use
 174 .BR fallocate (2)
 175 if they cannot tolerate the emulation caveats.
 176 In general, this is
 177 only recommended if the application plans to terminate the operation if
 178 .B EOPNOTSUPP
 179 is returned, otherwise the application itself will need to implement a
 180 fallback with all the same problems as the emulation provided by glibc.
 181 .SH SEE ALSO
 182 .BR fallocate (1),
 183 .BR fallocate (2),
 184 .BR lseek (2),
 185 .BR posix_fadvise (2)