summaryrefslogtreecommitdiffstats
path: root/man2/fallocate.2
diff options
context:
space:
mode:
Diffstat (limited to 'man2/fallocate.2')
-rw-r--r--man2/fallocate.2481
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)