man3/posix_fallocate.3

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