mirror of https://github.com/mkerrisk/man-pages
195 lines
4.6 KiB
Groff
195 lines
4.6 KiB
Groff
.\" Copyright (c) 2007 Silicon Graphics, Inc. All Rights Reserved
|
|
.\" Written by Dave Chinner <dgc@sgi.com>
|
|
.\" May be distributed as per GNU General Public License version 2.
|
|
.\"
|
|
.\" 2011-09-19: Added FALLOC_FL_PUNCH_HOLE
|
|
.\" 2011-09-19: Substantial restructuring of the page
|
|
.\"
|
|
.TH FALLOCATE 2 2012-04-23 "Linux" "Linux Programmer's Manual"
|
|
.SH NAME
|
|
fallocate \- manipulate file space
|
|
.SH SYNOPSIS
|
|
.nf
|
|
.BR "#define _GNU_SOURCE" " /* See feature_test_macros(7) */"
|
|
.B #include <fcntl.h>
|
|
|
|
.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).
|
|
|
|
.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.
|
|
|
|
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 and initializes to zero 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.
|
|
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.
|
|
|
|
After a successful call, subsequent writes into the range specified by
|
|
.IR offset
|
|
and
|
|
.IR len
|
|
are guaranteed not to fail because of lack of disk space.
|
|
|
|
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
|
|
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
|
|
.BR 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 file system blocks are zeroed,
|
|
and whole file system blocks are removed from the file.
|
|
After a successful call,
|
|
subsequent reads from this range will return zeroes.
|
|
|
|
The
|
|
.BR FALLOC_FL_PUNCH_HOLE
|
|
flag must be ORed with
|
|
.BR 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.
|
|
|
|
Not all file systems support
|
|
.BR FALLOC_FL_PUNCH_HOLE ;
|
|
if a file system doesn't support the operation, an error is returned.
|
|
.SH RETURN VALUE
|
|
.BR fallocate ()
|
|
returns zero on success, and \-1 on failure.
|
|
.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 EINTR
|
|
A signal was caught during execution.
|
|
.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 EIO
|
|
An I/O error occurred while reading from or writing to a file system.
|
|
.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 file system containing the file referred to by
|
|
.I fd
|
|
does not support this operation;
|
|
or the
|
|
.I mode
|
|
is not supported by the file system 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)).
|
|
Or:
|
|
.I mode
|
|
specifies
|
|
.BR FALLOC_FL_PUNCH_HOLE
|
|
and
|
|
the file referred to by
|
|
.I fd
|
|
is marked append-only
|
|
(see
|
|
.BR chattr (1)).
|
|
.TP
|
|
.B ESPIPE
|
|
.I fd
|
|
refers to a pipe or FIFO.
|
|
.SH VERSIONS
|
|
.BR fallocate ()
|
|
is available on Linux since kernel 2.6.23.
|
|
Support is provided by glibc since version 2.10.
|
|
.SH CONFORMING TO
|
|
.BR fallocate ()
|
|
is Linux-specific.
|
|
.SH SEE ALSO
|
|
.BR ftruncate (2),
|
|
.BR posix_fadvise (3),
|
|
.BR posix_fallocate (3)
|