Debian Codegraph @

upstream/debian-unstable/man3/posix_fallocate.3

raw
1 '\" t
2 .\" Copyright 2006, Michael Kerrisk <[email protected]>
3 .\" Copyright, the authors of the Linux man-pages project
4 .\"
5 .\" SPDX-License-Identifier: Linux-man-pages-copyleft
6 .\"
7 .TH posix_fallocate 3 2026-02-08 "Linux man-pages 6.18"
8 .SH NAME
9 posix_fallocate \- allocate file space
10 .SH LIBRARY
11 Standard C library
12 .RI ( libc ,\~ \-lc )
13 .SH SYNOPSIS
14 .nf
15 .B #include <fcntl.h>
16 .P
17 .BI "int posix_fallocate(int " fd ", off_t " offset ", off_t " size );
18 .fi
19 .P
20 .ad l
21 .RS -4
22 Feature Test Macro Requirements for glibc (see
23 .BR feature_test_macros (7)):
24 .RE
25 .P
26 .BR posix_fallocate ():
27 .nf
28 _POSIX_C_SOURCE >= 200112L
29 .fi
30 .SH DESCRIPTION
31 The function
32 .BR posix_fallocate ()
33 ensures that disk space is allocated for the file referred to by the
34 file descriptor
35 .I fd
36 for the bytes in the range starting at
37 .I offset
38 and continuing for
39 .I size
40 bytes.
41 After a successful call to
42 .BR posix_fallocate (),
43 subsequent writes to bytes in the specified range are
44 guaranteed not to fail because of lack of disk space.
45 .P
46 If the size of the file is less than
47 .IR offset + size ,
48 then the file is increased to this size;
49 otherwise the file size is left unchanged.
50 .SH RETURN VALUE
51 .BR posix_fallocate ()
52 returns zero on success, or an error number on failure.
53 Note that
54 .I errno
55 is not set.
56 .SH ERRORS
57 .TP
58 .B EBADF
59 .I fd
60 is not a valid file descriptor, or is not opened for writing.
61 .TP
62 .B EFBIG
63 .I offset+size
64 exceeds the maximum file size.
65 .TP
66 .B EINTR
67 A signal was caught during execution.
68 .TP
69 .B EINVAL
70 .I offset
71 was less than 0, or
72 .I size
73 was less than or equal to 0, or the underlying filesystem does not
74 support the operation.
75 .TP
76 .B ENODEV
77 .I fd
78 does not refer to a regular file.
79 .TP
80 .B ENOSPC
81 There is not enough space left on the device containing the file
82 referred to by
83 .IR fd .
84 .TP
85 .B EOPNOTSUPP
86 The filesystem containing the file referred to by
87 .I fd
88 does not support this operation.
89 This error code can be returned by C libraries that don't perform the
90 emulation shown in CAVEATS, such as musl libc.
91 .TP
92 .B ESPIPE
93 .I fd
94 refers to a pipe.
95 .SH ATTRIBUTES
96 For an explanation of the terms used in this section, see
97 .BR attributes (7).
98 .TS
99 allbox;
100 lb lb lbx
101 l l l.
102 Interface Attribute Value
103 T{
104 .na
105 .nh
106 .BR posix_fallocate ()
107 T} Thread safety T{
108 .na
109 .nh
110 MT-Safe (but see CAVEATS)
111 T}
112 .TE
113 .SH STANDARDS
114 POSIX.1-2008.
115 .SH HISTORY
116 glibc 2.1.94.
117 POSIX.1-2001
118 .P
119 POSIX.1-2008 says that an implementation
120 .I shall
121 give the
122 .B EINVAL
123 error if
124 .I size
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 size
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 size
140 equals zero.
141 .SH CAVEATS
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 \[bu] 3
151 The emulation is inefficient.
152 .IP \[bu]
153 There is a race condition where concurrent writes from another thread or
154 process could be overwritten with null bytes.
155 .IP \[bu]
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 \[bu]
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 fails with the error
167 .BR EBADF .
168 .P
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)