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  2015-03-02 "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 .sp
  32 .BI "int posix_fallocate(int " fd ", off_t " offset ", off_t " len );
  33 .fi
  34 .sp
  35 .ad l
  36 .in -4n
  37 Feature Test Macro Requirements for glibc (see
  38 .BR feature_test_macros (7)):
  39 .in
  40 .sp
  41 .BR posix_fallocate ():
  42 .RS 4
  43 _XOPEN_SOURCE\ >=\ 600 || _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 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
  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 EINVAL
  83 .I offset
  84 was less than 0, or
  85 .I len
  86 was less than or equal to 0, or the underlying filesystem does not
  87 support the operation.
  88 .TP
  89 .B ENODEV
  90 .I fd
  91 does not refer to a regular file.
  92 .TP
  93 .B ENOSPC
  94 There is not enough space left on the device containing the file
  95 referred to by
  96 .IR fd .
  97 .TP
  98 .B ESPIPE
  99 .I fd
 100 refers to a pipe.
 101 .SH VERSIONS
 102 .BR posix_fallocate ()
 103 is available since glibc 2.1.94.
 104 .SH ATTRIBUTES
 105 For an explanation of the terms used in this section, see
 106 .BR attributes (7).
 107 .TS
 108 allbox;
 109 lb lb lb
 110 l l l.
 111 Interface       Attribute       Value
 112 T{
 113 .BR posix_fallocate ()
 114 T}      Thread safety   MT-Safe (but see NOTES)
 115 .TE
 116 .SH CONFORMING TO
 117 POSIX.1-2001.
 118
 119 POSIX.1-2008 says that an implementation
 120 .I shall
 121 give the
 122 .B EINVAL
 123 error if
 124 .I len
 125 was 0, or
 126 .I offset
 127 was less than 0.
 128 POSIX.1-2001 says that an implementation
 129 .I shall
 130 give the
 131 .B EINVAL
 132 error if
 133 .I len
 134 is less than 0, or
 135 .I offset
 136 was less than 0, and
 137 .I may
 138 give the error if
 139 .I len
 140 equals zero.
 141 .SH NOTES
 142 In the glibc implementation,
 143 .BR posix_fallocate ()
 144 is implemented using the
 145 .BR fallocate (2)
 146 system call, which is MT-safe.
 147 If the underlying filesystem does not support
 148 .BR fallocate (2),
 149 then the operation is emulated with the following caveats:
 150 .IP * 2
 151 The emulation is inefficient.
 152 .IP *
 153 There is a race condition where concurrent writes from another thread or
 154 process could be overwritten with null bytes.
 155 .IP *
 156 There is a race condition where concurrent file size increases by
 157 another thread or process could result in a file whose size is smaller
 158 than expected.
 159 .IP *
 160 If
 161 .I fd
 162 has been opened with the
 163 .B O_APPEND
 164 or
 165 .B O_WRONLY
 166 flags, the function will fail with the error
 167 .B EBADF.
 168 .PP
 169 In general, the emulation is not MT-safe.
 170 On Linux, applications may use
 171 .BR fallocate (2)
 172 if they cannot tolerate the emulation caveats.
 173 In general, this is
 174 only recommended if the application plans to terminate the operation if
 175 .B EOPNOTSUPP
 176 is returned, otherwise the application itself will need to implement a
 177 fallback with all the same problems as the emulation provided by glibc.
 178 .SH SEE ALSO
 179 .BR fallocate (1),
 180 .BR fallocate (2),
 181 .BR lseek (2),
 182 .BR posix_fadvise (2)