Adding upstream version 6.05.01.upstream/6.05.01

Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>

1 files changed, 481 insertions, 0 deletions

diff --git a/man2/fallocate.2 b/man2/fallocate.2
new file mode 100644
index 0000000..e462658
--- /dev/null
+++ b/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 2023-03-30 "Linux man-pages 6.05.01"
+.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>
+.PP
+.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).
+.PP
+.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.
+.PP
+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.
+.PP
+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.
+.PP
+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.
+.PP
+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.
+.PP
+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.
+.PP
+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.
+.PP
+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.
+.PP
+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.
+.PP
+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.
+.PP
+No other flags may be specified in
+.I mode
+in conjunction with
+.BR FALLOC_FL_COLLAPSE_RANGE .
+.PP
+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.
+.PP
+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.
+.PP
+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.
+.PP
+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.
+.PP
+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.
+.PP
+No other flags may be specified in
+.I mode
+in conjunction with
+.BR FALLOC_FL_INSERT_RANGE .
+.PP
+.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)