Debian Codegraph @

upstream/debian-trixie/man3/posix_fallocate.3

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