diff options
Diffstat (limited to 'man2/fallocate.2')
| -rw-r--r-- | man2/fallocate.2 | 481 |
1 files changed, 0 insertions, 481 deletions
diff --git a/man2/fallocate.2 b/man2/fallocate.2 deleted file mode 100644 index bedc533..0000000 --- a/man2/fallocate.2 +++ /dev/null @@ -1,481 +0,0 @@ -.\" Copyright (c) 2007 Silicon Graphics, Inc. All Rights Reserved -.\" Written by Dave Chinner <dgc@sgi.com> -.\" -.\" SPDX-License-Identifier: GPL-2.0-only -.\" -.\" 2011-09-19: Added FALLOC_FL_PUNCH_HOLE -.\" 2011-09-19: Substantial restructuring of the page -.\" -.TH fallocate 2 2023-10-31 "Linux man-pages 6.7" -.SH NAME -fallocate \- manipulate file space -.SH LIBRARY -Standard C library -.RI ( libc ", " \-lc ) -.SH SYNOPSIS -.nf -.BR "#define _GNU_SOURCE" " /* See feature_test_macros(7) */" -.B #include <fcntl.h> -.P -.BI "int fallocate(int " fd ", int " mode ", off_t " offset \ -", off_t " len ");" -.fi -.SH DESCRIPTION -This is a nonportable, Linux-specific system call. -For the portable, POSIX.1-specified method of ensuring that space -is allocated for a file, see -.BR posix_fallocate (3). -.P -.BR fallocate () -allows the caller to directly manipulate the allocated disk space -for the file referred to by -.I fd -for the byte range starting at -.I offset -and continuing for -.I len -bytes. -.P -The -.I mode -argument determines the operation to be performed on the given range. -Details of the supported operations are given in the subsections below. -.SS Allocating disk space -The default operation (i.e., -.I mode -is zero) of -.BR fallocate () -allocates the disk space within the range specified by -.I offset -and -.IR len . -The file size (as reported by -.BR stat (2)) -will be changed if -.IR offset + len -is greater than the file size. -Any subregion within the range specified by -.I offset -and -.I len -that did not contain data before the call will be initialized to zero. -This default behavior closely resembles the behavior of the -.BR posix_fallocate (3) -library function, -and is intended as a method of optimally implementing that function. -.P -After a successful call, subsequent writes into the range specified by -.I offset -and -.I len -are guaranteed not to fail because of lack of disk space. -.P -If the -.B FALLOC_FL_KEEP_SIZE -flag is specified in -.IR mode , -the behavior of the call is similar, -but the file size will not be changed even if -.IR offset + len -is greater than the file size. -Preallocating zeroed blocks beyond the end of the file in this manner -is useful for optimizing append workloads. -.P -If the -.B FALLOC_FL_UNSHARE_RANGE -flag is specified in -.IR mode , -shared file data extents will be made private to the file to guarantee -that a subsequent write will not fail due to lack of space. -Typically, this will be done by performing a copy-on-write operation on -all shared data in the file. -This flag may not be supported by all filesystems. -.P -Because allocation is done in block size chunks, -.BR fallocate () -may allocate a larger range of disk space than was specified. -.SS Deallocating file space -Specifying the -.B FALLOC_FL_PUNCH_HOLE -flag (available since Linux 2.6.38) in -.I mode -deallocates space (i.e., creates a hole) -in the byte range starting at -.I offset -and continuing for -.I len -bytes. -Within the specified range, partial filesystem blocks are zeroed, -and whole filesystem blocks are removed from the file. -After a successful call, -subsequent reads from this range will return zeros. -.P -The -.B FALLOC_FL_PUNCH_HOLE -flag must be ORed with -.B FALLOC_FL_KEEP_SIZE -in -.IR mode ; -in other words, even when punching off the end of the file, the file size -(as reported by -.BR stat (2)) -does not change. -.P -Not all filesystems support -.BR FALLOC_FL_PUNCH_HOLE ; -if a filesystem doesn't support the operation, an error is returned. -The operation is supported on at least the following filesystems: -.IP \[bu] 3 -XFS (since Linux 2.6.38) -.IP \[bu] -ext4 (since Linux 3.0) -.\" commit a4bb6b64e39abc0e41ca077725f2a72c868e7622 -.IP \[bu] -Btrfs (since Linux 3.7) -.IP \[bu] -.BR tmpfs (5) -(since Linux 3.5) -.\" commit 83e4fa9c16e4af7122e31be3eca5d57881d236fe -.IP \[bu] -.BR gfs2 (5) -(since Linux 4.16) -.\" commit 4e56a6411fbce6f859566e17298114c2434391a4 -.SS Collapsing file space -.\" commit 00f5e61998dd17f5375d9dfc01331f104b83f841 -Specifying the -.B FALLOC_FL_COLLAPSE_RANGE -flag (available since Linux 3.15) in -.I mode -removes a byte range from a file, without leaving a hole. -The byte range to be collapsed starts at -.I offset -and continues for -.I len -bytes. -At the completion of the operation, -the contents of the file starting at the location -.I offset+len -will be appended at the location -.IR offset , -and the file will be -.I len -bytes smaller. -.P -A filesystem may place limitations on the granularity of the operation, -in order to ensure efficient implementation. -Typically, -.I offset -and -.I len -must be a multiple of the filesystem logical block size, -which varies according to the filesystem type and configuration. -If a filesystem has such a requirement, -.BR fallocate () -fails with the error -.B EINVAL -if this requirement is violated. -.P -If the region specified by -.I offset -plus -.I len -reaches or passes the end of file, an error is returned; -instead, use -.BR ftruncate (2) -to truncate a file. -.P -No other flags may be specified in -.I mode -in conjunction with -.BR FALLOC_FL_COLLAPSE_RANGE . -.P -As at Linux 3.15, -.B FALLOC_FL_COLLAPSE_RANGE -is supported by -ext4 (only for extent-based files) -.\" commit 9eb79482a97152930b113b51dff530aba9e28c8e -and XFS. -.\" commit e1d8fb88a64c1f8094b9f6c3b6d2d9e6719c970d -.SS Zeroing file space -Specifying the -.B FALLOC_FL_ZERO_RANGE -flag (available since Linux 3.15) -.\" commit 409332b65d3ed8cfa7a8030f1e9d52f372219642 -in -.I mode -zeros space in the byte range starting at -.I offset -and continuing for -.I len -bytes. -Within the specified range, blocks are preallocated for the regions -that span the holes in the file. -After a successful call, subsequent -reads from this range will return zeros. -.P -Zeroing is done within the filesystem preferably by converting the range into -unwritten extents. -This approach means that the specified range will not be physically zeroed -out on the device (except for partial blocks at the either end of the range), -and I/O is (otherwise) required only to update metadata. -.P -If the -.B FALLOC_FL_KEEP_SIZE -flag is additionally specified in -.IR mode , -the behavior of the call is similar, -but the file size will not be changed even if -.IR offset + len -is greater than the file size. -This behavior is the same as when preallocating space with -.B FALLOC_FL_KEEP_SIZE -specified. -.P -Not all filesystems support -.BR FALLOC_FL_ZERO_RANGE ; -if a filesystem doesn't support the operation, an error is returned. -The operation is supported on at least the following filesystems: -.IP \[bu] 3 -XFS (since Linux 3.15) -.\" commit 376ba313147b4172f3e8cf620b9fb591f3e8cdfa -.IP \[bu] -ext4, for extent-based files (since Linux 3.15) -.\" commit b8a8684502a0fc852afa0056c6bb2a9273f6fcc0 -.IP \[bu] -SMB3 (since Linux 3.17) -.\" commit 30175628bf7f521e9ee31ac98fa6d6fe7441a556 -.IP \[bu] -Btrfs (since Linux 4.16) -.\" commit f27451f229966874a8793995b8e6b74326d125df -.SS Increasing file space -Specifying the -.B FALLOC_FL_INSERT_RANGE -flag -(available since Linux 4.1) -.\" commit dd46c787788d5bf5b974729d43e4c405814a4c7d -in -.I mode -increases the file space by inserting a hole within the file size without -overwriting any existing data. -The hole will start at -.I offset -and continue for -.I len -bytes. -When inserting the hole inside file, the contents of the file starting at -.I offset -will be shifted upward (i.e., to a higher file offset) by -.I len -bytes. -Inserting a hole inside a file increases the file size by -.I len -bytes. -.P -This mode has the same limitations as -.B FALLOC_FL_COLLAPSE_RANGE -regarding the granularity of the operation. -If the granularity requirements are not met, -.BR fallocate () -fails with the error -.BR EINVAL . -If the -.I offset -is equal to or greater than the end of file, an error is returned. -For such operations (i.e., inserting a hole at the end of file), -.BR ftruncate (2) -should be used. -.P -No other flags may be specified in -.I mode -in conjunction with -.BR FALLOC_FL_INSERT_RANGE . -.P -.B FALLOC_FL_INSERT_RANGE -requires filesystem support. -Filesystems that support this operation include -XFS (since Linux 4.1) -.\" commit a904b1ca5751faf5ece8600e18cd3b674afcca1b -and ext4 (since Linux 4.2). -.\" commit 331573febb6a224bc50322e3670da326cb7f4cfc -.\" f2fs also has support since Linux 4.2 -.\" commit f62185d0e283e9d311e3ac1020f159d95f0aab39 -.SH RETURN VALUE -On success, -.BR fallocate () -returns zero. -On error, \-1 is returned and -.I errno -is set to indicate the error. -.SH ERRORS -.TP -.B EBADF -.I fd -is not a valid file descriptor, or is not opened for writing. -.TP -.B EFBIG -.IR offset + len -exceeds the maximum file size. -.TP -.B EFBIG -.I mode -is -.BR FALLOC_FL_INSERT_RANGE , -and the current file size+\fIlen\fP exceeds the maximum file size. -.TP -.B EINTR -A signal was caught during execution; see -.BR signal (7). -.TP -.B EINVAL -.I offset -was less than 0, or -.I len -.\" FIXME . (raise a kernel bug) Probably the len==0 case should be -.\" a no-op, rather than an error. That would be consistent with -.\" similar APIs for the len==0 case. -.\" See "Re: [PATCH] fallocate.2: add FALLOC_FL_PUNCH_HOLE flag definition" -.\" 21 Sep 2012 -.\" http://thread.gmane.org/gmane.linux.file-systems/48331/focus=1193526 -was less than or equal to 0. -.TP -.B EINVAL -.I mode -is -.B FALLOC_FL_COLLAPSE_RANGE -and the range specified by -.I offset -plus -.I len -reaches or passes the end of the file. -.TP -.B EINVAL -.I mode -is -.B FALLOC_FL_INSERT_RANGE -and the range specified by -.I offset -reaches or passes the end of the file. -.TP -.B EINVAL -.I mode -is -.B FALLOC_FL_COLLAPSE_RANGE -or -.BR FALLOC_FL_INSERT_RANGE , -but either -.I offset -or -.I len -is not a multiple of the filesystem block size. -.TP -.B EINVAL -.I mode -contains one of -.B FALLOC_FL_COLLAPSE_RANGE -or -.B FALLOC_FL_INSERT_RANGE -and also other flags; -no other flags are permitted with -.B FALLOC_FL_COLLAPSE_RANGE -or -.BR FALLOC_FL_INSERT_RANGE . -.TP -.B EINVAL -.I mode -is -.BR FALLOC_FL_COLLAPSE_RANGE , -.BR FALLOC_FL_ZERO_RANGE , -or -.BR FALLOC_FL_INSERT_RANGE , -but the file referred to by -.I fd -is not a regular file. -.\" There was an inconsistency in Linux 3.15-rc1, that should be resolved so that all -.\" filesystems use this error for this case. (Tytso says ex4 will change.) -.\" http://thread.gmane.org/gmane.comp.file-systems.xfs.general/60485/focus=5521 -.\" From: Michael Kerrisk (man-pages <mtk.manpages@...> -.\" Subject: Re: [PATCH v5 10/10] manpage: update FALLOC_FL_COLLAPSE_RANGE flag in fallocate -.\" Newsgroups: gmane.linux.man, gmane.linux.file-systems -.\" Date: 2014-04-17 13:40:05 GMT -.TP -.B EIO -An I/O error occurred while reading from or writing to a filesystem. -.TP -.B ENODEV -.I fd -does not refer to a regular file or a directory. -(If -.I fd -is a pipe or FIFO, a different error results.) -.TP -.B ENOSPC -There is not enough space left on the device containing the file -referred to by -.IR fd . -.TP -.B ENOSYS -This kernel does not implement -.BR fallocate (). -.TP -.B EOPNOTSUPP -The filesystem containing the file referred to by -.I fd -does not support this operation; -or the -.I mode -is not supported by the filesystem containing the file referred to by -.IR fd . -.TP -.B EPERM -The file referred to by -.I fd -is marked immutable (see -.BR chattr (1)). -.TP -.B EPERM -.I mode -specifies -.BR FALLOC_FL_PUNCH_HOLE , -.BR FALLOC_FL_COLLAPSE_RANGE , -or -.B FALLOC_FL_INSERT_RANGE -and -the file referred to by -.I fd -is marked append-only -(see -.BR chattr (1)). -.TP -.B EPERM -The operation was prevented by a file seal; see -.BR fcntl (2). -.TP -.B ESPIPE -.I fd -refers to a pipe or FIFO. -.TP -.B ETXTBSY -.I mode -specifies -.B FALLOC_FL_COLLAPSE_RANGE -or -.BR FALLOC_FL_INSERT_RANGE , -but the file referred to by -.I fd -is currently being executed. -.SH STANDARDS -Linux. -.SH HISTORY -.TP -.BR fallocate () -Linux 2.6.23, -glibc 2.10. -.TP -.B FALLOC_FL_* -glibc 2.18. -.\" See http://sourceware.org/bugzilla/show_bug.cgi?id=14964 -.SH SEE ALSO -.BR fallocate (1), -.BR ftruncate (2), -.BR posix_fadvise (3), -.BR posix_fallocate (3) |