diff options
Diffstat (limited to 'man/man2/fallocate.2')
| -rw-r--r-- | man/man2/fallocate.2 | 481 |
1 files changed, 481 insertions, 0 deletions
diff --git a/man/man2/fallocate.2 b/man/man2/fallocate.2 new file mode 100644 index 0000000..1d50425 --- /dev/null +++ b/man/man2/fallocate.2 @@ -0,0 +1,481 @@ +.\" 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 2024-05-02 "Linux man-pages (unreleased)" +.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) |