]>
Commit | Line | Data |
---|---|---|
d9a0b2a5 MK |
1 | .\" Copyright (c) 2007 Silicon Graphics, Inc. All Rights Reserved |
2 | .\" Written by Dave Chinner <dgc@sgi.com> | |
3 | .\" May be distributed as per GNU General Public License version 2. | |
4 | .\" | |
17187579 MK |
5 | .\" FIXME: Linux 2.6.38 added FALLOC_FL_PUNCH_HOLE |
6 | .\" | |
45eb0d22 | 7 | .TH FALLOCATE 2 2011-09-19 "Linux" "Linux Programmer's Manual" |
d9a0b2a5 MK |
8 | .SH NAME |
9 | fallocate \- manipulate file space | |
10 | .SH SYNOPSIS | |
11 | .nf | |
86b91fdf | 12 | .BR "#define _GNU_SOURCE" " /* See feature_test_macros(7) */" |
ff6db399 | 13 | .B #include <fcntl.h> |
c8250206 | 14 | |
ff6db399 MK |
15 | .BI "int fallocate(int " fd ", int " mode ", off_t " offset \ |
16 | ", off_t " len "); | |
c8250206 | 17 | .fi |
d9a0b2a5 | 18 | .SH DESCRIPTION |
d603cc27 | 19 | This is a nonportable, Linux-specific system call. |
01b7704f MK |
20 | For the portable, POSIX.1-specified method of ensuring that space |
21 | is allocated for a file, see | |
8c56fcec | 22 | .BR posix_fallocate (3). |
01b7704f | 23 | |
d9a0b2a5 MK |
24 | .BR fallocate () |
25 | allows the caller to directly manipulate the allocated disk space | |
26 | for the file referred to by | |
27 | .I fd | |
28 | for the byte range starting at | |
29 | .I offset | |
30 | and continuing for | |
31 | .I len | |
32 | bytes. | |
33 | ||
34 | The | |
35 | .I mode | |
36 | argument determines the operation to be performed on the given range. | |
37 | Currently only one flag is supported for | |
38 | .IR mode : | |
39 | .TP | |
40 | .B FALLOC_FL_KEEP_SIZE | |
41 | This flag allocates and initializes to zero the disk space | |
42 | within the range specified by | |
43 | .I offset | |
44 | and | |
45 | .IR len . | |
46 | After a successful call, subsequent writes into this range | |
47 | are guaranteed not to fail because of lack of disk space. | |
48 | Preallocating zeroed blocks beyond the end of the file | |
49 | is useful for optimizing append workloads. | |
50 | Preallocating blocks does not change | |
51 | the file size (as reported by | |
52 | .BR stat (2)) | |
53 | even if it is less than | |
54 | .IR offset + len . | |
55 | .\" | |
56 | .\" Note from Amit Arora: | |
57 | .\" There were few more flags which were discussed, but none of | |
58 | .\" them have been finalized upon. Here are these flags: | |
59 | .\" FA_FL_DEALLOC, FA_FL_DEL_DATA, FA_FL_ERR_FREE, FA_FL_NO_MTIME, | |
60 | .\" FA_FL_NO_CTIME | |
61 | .\" All of the above flags were debated upon and we can not say | |
62 | .\" if any/which one of these flags will make it to the later kernels. | |
63 | .PP | |
64 | If | |
65 | .B FALLOC_FL_KEEP_SIZE | |
66 | flag is not specified in | |
67 | .IR mode , | |
68 | the default behavior is almost same as when this flag is specified. | |
69 | The only difference is that on success, | |
70 | the file size will be changed if | |
9ec0ea90 | 71 | .I "offset + len" |
d9a0b2a5 MK |
72 | is greater than the file size. |
73 | This default behavior closely resembles the behavior of the | |
74 | .BR posix_fallocate (3) | |
75 | library function, | |
76 | and is intended as a method of optimally implementing that function. | |
77 | .PP | |
78 | Because allocation is done in block size chunks, | |
79 | .BR fallocate () | |
80 | may allocate a larger range than that which was specified. | |
81 | .SH RETURN VALUE | |
82 | .BR fallocate () | |
c3074d70 | 83 | returns zero on success, and \-1 on failure. |
d9a0b2a5 MK |
84 | .SH ERRORS |
85 | .TP | |
86 | .B EBADF | |
87 | .I fd | |
88 | is not a valid file descriptor, or is not opened for writing. | |
89 | .TP | |
90 | .B EFBIG | |
91 | .IR offset + len | |
92 | exceeds the maximum file size. | |
93 | .TP | |
94 | .B EINTR | |
95 | A signal was caught during execution. | |
96 | .TP | |
97 | .B EINVAL | |
98 | .I offset | |
99 | was less than 0, or | |
100 | .I len | |
101 | was less than or equal to 0. | |
102 | .TP | |
103 | .B EIO | |
104 | An I/O error occurred while reading from or writing to a file system. | |
105 | .TP | |
106 | .B ENODEV | |
107 | .I fd | |
108 | does not refer to a regular file or a directory. | |
109 | (If | |
110 | .I fd | |
111 | is a pipe or FIFO, a different error results.) | |
112 | .TP | |
113 | .B ENOSPC | |
114 | There is not enough space left on the device containing the file | |
115 | referred to by | |
116 | .IR fd . | |
117 | .TP | |
118 | .B ENOSYS | |
119 | The file system containing the file referred to by | |
120 | .I fd | |
121 | does not support this operation. | |
122 | .TP | |
123 | .B EOPNOTSUPP | |
124 | The | |
125 | .I mode | |
126 | is not supported by the file system containing the file referred to by | |
127 | .IR fd . | |
45eb0d22 MK |
128 | .TP |
129 | .B EPERM | |
130 | The file referred to by | |
928b1970 | 131 | .I fd |
45eb0d22 | 132 | is marked immutable (see |
928b1970 | 133 | .BR chattr (1)). |
45eb0d22 MK |
134 | .TP |
135 | .B ESPIPE | |
136 | .I fd | |
928b1970 | 137 | refers to a pipe or FIFO. |
d9a0b2a5 MK |
138 | .SH VERSIONS |
139 | .BR fallocate () | |
d9a0b2a5 | 140 | is available on Linux since kernel 2.6.23. |
ff6db399 | 141 | Support is provided by glibc since version 2.10. |
90e261f2 | 142 | .SH CONFORMING TO |
d9a0b2a5 | 143 | .BR fallocate () |
8382f16d | 144 | is Linux-specific. |
d9a0b2a5 MK |
145 | .SH SEE ALSO |
146 | .BR ftruncate (2), | |
f0c34053 MK |
147 | .BR posix_fadvise (3), |
148 | .BR posix_fallocate (3) |