2007-09-10 04:30:43 +00:00
|
|
|
.\" 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 04:14:01 +00:00
|
|
|
.\" 2011-09-19: Added FALLOC_FL_PUNCH_HOLE
|
|
|
|
.\" 2011-09-19: Substantial restructuring of the page
|
|
|
|
.\"
|
2011-09-19 02:49:42 +00:00
|
|
|
.TH FALLOCATE 2 2011-09-19 "Linux" "Linux Programmer's Manual"
|
2007-09-10 04:30:43 +00:00
|
|
|
.SH NAME
|
|
|
|
fallocate \- manipulate file space
|
|
|
|
.SH SYNOPSIS
|
|
|
|
.nf
|
accept.2, clone.2, dup.2, fallocate.2, pipe.2, readahead.2, sched_setaffinity.2, unshare.2, CPU_SET.3, endian.3, euidaccess.3, fexecve.3, getpt.3, getpw.3, getumask.3, getutmp.3, gnu_get_libc_version.3, makedev.3, matherr.3, mbsnrtowcs.3, memfrob.3, pthread_attr_setaffinity_np.3, pthread_getattr_np.3, pthread_setaffinity_np.3, pthread_tryjoin_np.3, tcgetsid.3, wcscasecmp.3, wcsncasecmp.3, wcsnlen.3, wcsnrtombs.3, wcswidth.3, rtld-audit.7: SYNOPSIS: Add reference to feature_test_macros(7)
These pages specify feature test macros in the function
prototypes. Add a reference to feature_test_macros(7),
so that readers are pointed to the information that
feature test macros must be defined before including
*any* header file.
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
2010-09-10 05:06:22 +00:00
|
|
|
.BR "#define _GNU_SOURCE" " /* See feature_test_macros(7) */"
|
2009-03-12 05:17:54 +00:00
|
|
|
.B #include <fcntl.h>
|
2007-12-23 21:05:57 +00:00
|
|
|
|
2009-03-12 05:17:54 +00:00
|
|
|
.BI "int fallocate(int " fd ", int " mode ", off_t " offset \
|
|
|
|
", off_t " len ");
|
2007-12-23 21:05:57 +00:00
|
|
|
.fi
|
2007-09-10 04:30:43 +00:00
|
|
|
.SH DESCRIPTION
|
execve.2, fallocate.2, futex.2, sched_rr_get_interval.2, select_tut.2, shmget.2, timer_getoverrun.2, times.2, pthread_attr_init.3, pthread_attr_setaffinity_np.3, pthread_cleanup_push_defer_np.3, pthread_getattr_np.3, pthread_self.3, pthread_setaffinity_np.3, pthread_tryjoin_np.3, sem_open.3, stdin.3, rtc.4, tty_ioctl.4, unix.7: Global fix: s/non-portable/nonportable/
The tendency in English, as prescribed in style guides like
Chicago MoS, is towards removing hyphens after prefixes
like "non-" etc.
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
2010-01-16 16:46:09 +00:00
|
|
|
This is a nonportable, Linux-specific system call.
|
2008-10-06 13:08:21 +00:00
|
|
|
For the portable, POSIX.1-specified method of ensuring that space
|
|
|
|
is allocated for a file, see
|
2011-09-08 15:31:30 +00:00
|
|
|
.BR posix_fallocate (3).
|
2008-10-06 13:08:21 +00:00
|
|
|
|
2007-09-10 04:30:43 +00:00
|
|
|
.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.
|
2011-09-19 04:14:01 +00:00
|
|
|
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
|
2007-09-10 04:30:43 +00:00
|
|
|
within the range specified by
|
|
|
|
.I offset
|
|
|
|
and
|
|
|
|
.IR len .
|
2011-09-19 04:14:01 +00:00
|
|
|
The file size (as reported by
|
|
|
|
.BR stat (2))
|
|
|
|
will be changed if
|
|
|
|
.I "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
|
2007-09-10 04:30:43 +00:00
|
|
|
are guaranteed not to fail because of lack of disk space.
|
2011-09-19 04:14:01 +00:00
|
|
|
|
|
|
|
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
|
|
|
|
.I "offset + len"
|
|
|
|
is greater than the file size.
|
|
|
|
Preallocating zeroed blocks beyond the end of the file in this manner
|
2007-09-10 04:30:43 +00:00
|
|
|
is useful for optimizing append workloads.
|
|
|
|
.PP
|
2011-09-19 04:14:01 +00:00
|
|
|
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)
|
2011-09-19 03:33:54 +00:00
|
|
|
in the byte range starting at
|
2011-09-19 03:09:31 +00:00
|
|
|
.I offset
|
|
|
|
and continuing for
|
|
|
|
.I len
|
2011-09-19 04:14:01 +00:00
|
|
|
bytes.
|
|
|
|
Within the specified range, partial file system blocks are zeroed,
|
2011-09-19 03:33:54 +00:00
|
|
|
and whole file system blocks are removed from the file.
|
|
|
|
After a successful call,
|
|
|
|
subsequent reads from this range will return zeroes.
|
2011-09-19 04:14:01 +00:00
|
|
|
|
2011-09-19 03:33:54 +00:00
|
|
|
The
|
2011-09-19 03:09:31 +00:00
|
|
|
.BR FALLOC_FL_PUNCH_HOLE
|
2011-09-19 03:33:54 +00:00
|
|
|
flag must be ORed with
|
2011-09-19 03:09:31 +00:00
|
|
|
.BR FALLOC_FL_KEEP_SIZE
|
2011-09-19 04:14:01 +00:00
|
|
|
in
|
|
|
|
.IR mode ;
|
2011-09-19 03:33:54 +00:00
|
|
|
in other words, even when punching off the end of the file, the file size
|
|
|
|
(as reported by
|
2011-09-19 03:09:31 +00:00
|
|
|
.BR stat (2))
|
2011-09-19 03:33:54 +00:00
|
|
|
does not change.
|
2011-09-19 04:14:01 +00:00
|
|
|
|
|
|
|
Not all file systems support
|
|
|
|
.BR FALLOC_FL_PUNCH_HOLE ;
|
|
|
|
if a file system doesn't support the operation, an error is returned.
|
2007-09-10 04:30:43 +00:00
|
|
|
.SH RETURN VALUE
|
|
|
|
.BR fallocate ()
|
fallocate.2, kexec_load.2, poll.2, spu_run.2, atan2.3, cbrt.3, clock_getcpuclockid.3, end.3, frexp.3, getgrouplist.3, getifaddrs.3, matherr.3, modf.3, pow.3, pthread_getattr_np.3, pthread_getcpuclockid.3, sched_getcpu.3, tgamma.3, mouse.4, proc.5, feature_test_macros.7, spufs.7: Global fix: properly escape minus sign
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
2011-09-10 01:57:53 +00:00
|
|
|
returns zero on success, and \-1 on failure.
|
2007-09-10 04:30:43 +00:00
|
|
|
.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
|
|
|
|
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
|
|
|
|
The file system containing the file referred to by
|
|
|
|
.I fd
|
|
|
|
does not support this operation.
|
|
|
|
.TP
|
|
|
|
.B EOPNOTSUPP
|
|
|
|
The
|
|
|
|
.I mode
|
|
|
|
is not supported by the file system containing the file referred to by
|
|
|
|
.IR fd .
|
2011-09-19 02:49:42 +00:00
|
|
|
.TP
|
|
|
|
.B EPERM
|
|
|
|
The file referred to by
|
2011-09-22 02:54:53 +00:00
|
|
|
.I fd
|
2011-09-19 02:49:42 +00:00
|
|
|
is marked immutable (see
|
2011-09-19 04:17:53 +00:00
|
|
|
.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
|
2011-09-22 02:54:53 +00:00
|
|
|
.BR chattr (1)).
|
2011-09-19 02:49:42 +00:00
|
|
|
.TP
|
|
|
|
.B ESPIPE
|
|
|
|
.I fd
|
2011-09-22 02:54:53 +00:00
|
|
|
refers to a pipe or FIFO.
|
2007-09-10 04:30:43 +00:00
|
|
|
.SH VERSIONS
|
|
|
|
.BR fallocate ()
|
|
|
|
is available on Linux since kernel 2.6.23.
|
2009-03-12 05:17:54 +00:00
|
|
|
Support is provided by glibc since version 2.10.
|
2007-11-17 06:13:05 +00:00
|
|
|
.SH CONFORMING TO
|
2007-09-10 04:30:43 +00:00
|
|
|
.BR fallocate ()
|
2007-12-25 21:28:09 +00:00
|
|
|
is Linux-specific.
|
2007-09-10 04:30:43 +00:00
|
|
|
.SH SEE ALSO
|
|
|
|
.BR ftruncate (2),
|
2008-07-14 15:52:21 +00:00
|
|
|
.BR posix_fadvise (3),
|
|
|
|
.BR posix_fallocate (3)
|