2007-09-10 04:30:43 +00:00
|
|
|
.\" Copyright (c) 2007 Silicon Graphics, Inc. All Rights Reserved
|
|
|
|
|
.\" Written by Dave Chinner <dgc@sgi.com>
|
ldd.1, capget.2, clone.2, create_module.2, fallocate.2, futex.2, get_kernel_syms.2, get_thread_area.2, getcpu.2, getitimer.2, getpid.2, io_cancel.2, io_destroy.2, io_getevents.2, io_setup.2, io_submit.2, ioctl_list.2, mkdir.2, mknod.2, pciconfig_read.2, pivot_root.2, posix_fadvise.2, query_module.2, sendfile.2, set_thread_area.2, setns.2, unshare.2, __setfpucw.3, a64l.3, addseverity.3, argz_add.3, bindresvport.3, cabs.3, cacos.3, cacosh.3, canonicalize_file_name.3, carg.3, casin.3, casinh.3, catan.3, catanh.3, ccos.3, ccosh.3, cerf.3, cexp.3, cexp2.3, cimag.3, clog.3, clog10.3, clog2.3, cmsg.3, conj.3, cpow.3, cproj.3, creal.3, csin.3, csinh.3, csqrt.3, ctan.3, ctanh.3, des_crypt.3, envz_add.3, fdim.3, fma.3, fmax.3, fmemopen.3, fmin.3, fmtmsg.3, fpclassify.3, gamma.3, getpt.3, getrpcent.3, getrpcport.3, getttyent.3, isgreater.3, key_setsecret.3, lgamma.3, malloc_hook.3, mempcpy.3, nan.3, netlink.3, nextafter.3, putgrent.3, remove.3, remquo.3, rpc.3, rtime.3, rtnetlink.3, setaliasent.3, setnetgrent.3, signbit.3, significand.3, sincos.3, stdin.3, tgamma.3, xcrypt.3, xdr.3, cciss.4, hpsa.4, mouse.4, pts.4, sk98lin.4, tty_ioctl.4, wavelan.4, hosts.equiv.5, rpc.5, tzfile.5, boot.7, complex.7, ddp.7, fifo.7, futex.7, icmp.7, ip.7, ipv6.7, netdevice.7, netlink.7, packet.7, raw.7, rtnetlink.7, socket.7, tcp.7, udp.7, unix.7, x25.7, sync.8: Global fix: Put copyright info at top of page, followed by blank line and LICENSE
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
2013-03-10 09:29:51 +00:00
|
|
|
.\"
|
2013-03-10 09:29:10 +00:00
|
|
|
.\" %%%LICENSE_START(GPLv2_ONELINE)
|
2007-09-10 04:30:43 +00:00
|
|
|
.\" May be distributed as per GNU General Public License version 2.
|
epoll_create.2, epoll_ctl.2, epoll_wait.2, eventfd.2, fallocate.2, futex.2, getcpu.2, getitimer.2, ioctl_list.2, ioprio_set.2, migrate_pages.2, move_pages.2, pciconfig_read.2, sendfile.2, setns.2, signalfd.2, spu_create.2, spu_run.2, sysinfo.2, timerfd_create.2, backtrace.3, cmsg.3, error.3, getpt.3, getrpcent.3, getrpcport.3, getsubopt.3, offsetof.3, program_invocation_name.3, rpc.3, rpmatch.3, rtnetlink.3, xdr.3, cciss.4, hpsa.4, pts.4, charmap.5, dir_colors.5, elf.5, gai.conf.5, locale.5, nscd.conf.5, nss.5, resolv.conf.5, rpc.5, arp.7, cpuset.7, ddp.7, epoll.7, fifo.7, futex.7, icmp.7, ip.7, ipv6.7, mailaddr.7, netdevice.7, packet.7, raw.7, regex.7, rtnetlink.7, socket.7, spufs.7, tcp.7, udp.7, unix.7, x25.7, ldconfig.8, nscd.8: Global fix: s/END_LICENSE/LICENSE_END/
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
2013-03-12 09:26:07 +00:00
|
|
|
.\" %%%LICENSE_END
|
2007-09-10 04:30:43 +00:00
|
|
|
.\"
|
2011-09-19 04:14:01 +00:00
|
|
|
.\" 2011-09-19: Added FALLOC_FL_PUNCH_HOLE
|
|
|
|
|
.\" 2011-09-19: Substantial restructuring of the page
|
|
|
|
|
.\"
|
2014-04-17 12:12:16 +00:00
|
|
|
.TH FALLOCATE 2 2014-04-17 "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 ()
|
2013-11-06 13:52:31 +00:00
|
|
|
allocates the disk space within the range specified by
|
2007-09-10 04:30:43 +00:00
|
|
|
.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
|
2012-03-19 18:42:00 +00:00
|
|
|
.IR offset + len
|
2011-09-19 04:14:01 +00:00
|
|
|
is greater than the file size.
|
2013-11-07 17:02:49 +00:00
|
|
|
Any subregion within the range specified by
|
2013-11-06 13:52:31 +00:00
|
|
|
.I offset
|
|
|
|
|
and
|
2014-02-04 08:08:43 +00:00
|
|
|
.IR len
|
2013-11-06 13:52:31 +00:00
|
|
|
that did not contain data before the call will be initialized to zero.
|
2011-09-19 04:14:01 +00:00
|
|
|
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
|
2012-03-19 18:42:00 +00:00
|
|
|
.IR offset + len
|
2011-09-19 04:14:01 +00:00
|
|
|
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.
|
intro.1, time.1, access.2, acct.2, alloc_hugepages.2, bind.2, chdir.2, chmod.2, chown.2, chroot.2, clone.2, close.2, execve.2, fallocate.2, fcntl.2, getdents.2, getrusage.2, getxattr.2, init_module.2, inotify_add_watch.2, ioprio_set.2, kcmp.2, link.2, listxattr.2, lseek.2, madvise.2, mkdir.2, mknod.2, mmap.2, mount.2, move_pages.2, msgctl.2, nfsservctl.2, open.2, pivot_root.2, quotactl.2, read.2, readlink.2, removexattr.2, rename.2, rmdir.2, semctl.2, setfsgid.2, setfsuid.2, setresuid.2, setuid.2, setup.2, setxattr.2, shmctl.2, splice.2, spu_create.2, stat.2, statfs.2, swapon.2, symlink.2, sync.2, sync_file_range.2, sysfs.2, truncate.2, umount.2, unlink.2, unshare.2, ustat.2, utime.2, utimensat.2, write.2, btree.3, errno.3, fexecve.3, ftw.3, futimes.3, get_nprocs_conf.3, getcwd.3, getdirentries.3, getmntent.3, glob.3, mkfifo.3, mq_open.3, readdir.3, realpath.3, recno.3, remove.3, sem_open.3, shm_open.3, statvfs.3, sysconf.3, telldir.3, tmpfile.3, cciss.4, initrd.4, pts.4, sk98lin.4, vcs.4, core.5, filesystems.5, proc.5, boot.7, bootparam.7, capabilities.7, cpuset.7, credentials.7, feature_test_macros.7, fifo.7, hier.7, inotify.7, intro.7, mq_overview.7, path_resolution.7, pipe.7, sem_overview.7, shm_overview.7, spufs.7, symlink.7, unix.7, uri.7, sync.8: Global fix: s/file system/filesystem/
Notwithstanding 24d01c530c5a3f75217543d02bf6712395e5f90c,
"filesystem" is the form used by the great majority of man pages
outside the man-pages project and in a number of other sources,
so let's go with that.
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
2013-08-08 08:07:57 +00:00
|
|
|
Within the specified range, partial filesystem blocks are zeroed,
|
|
|
|
|
and whole filesystem blocks are removed from the file.
|
2011-09-19 03:33:54 +00:00
|
|
|
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
|
|
|
|
intro.1, time.1, access.2, acct.2, alloc_hugepages.2, bind.2, chdir.2, chmod.2, chown.2, chroot.2, clone.2, close.2, execve.2, fallocate.2, fcntl.2, getdents.2, getrusage.2, getxattr.2, init_module.2, inotify_add_watch.2, ioprio_set.2, kcmp.2, link.2, listxattr.2, lseek.2, madvise.2, mkdir.2, mknod.2, mmap.2, mount.2, move_pages.2, msgctl.2, nfsservctl.2, open.2, pivot_root.2, quotactl.2, read.2, readlink.2, removexattr.2, rename.2, rmdir.2, semctl.2, setfsgid.2, setfsuid.2, setresuid.2, setuid.2, setup.2, setxattr.2, shmctl.2, splice.2, spu_create.2, stat.2, statfs.2, swapon.2, symlink.2, sync.2, sync_file_range.2, sysfs.2, truncate.2, umount.2, unlink.2, unshare.2, ustat.2, utime.2, utimensat.2, write.2, btree.3, errno.3, fexecve.3, ftw.3, futimes.3, get_nprocs_conf.3, getcwd.3, getdirentries.3, getmntent.3, glob.3, mkfifo.3, mq_open.3, readdir.3, realpath.3, recno.3, remove.3, sem_open.3, shm_open.3, statvfs.3, sysconf.3, telldir.3, tmpfile.3, cciss.4, initrd.4, pts.4, sk98lin.4, vcs.4, core.5, filesystems.5, proc.5, boot.7, bootparam.7, capabilities.7, cpuset.7, credentials.7, feature_test_macros.7, fifo.7, hier.7, inotify.7, intro.7, mq_overview.7, path_resolution.7, pipe.7, sem_overview.7, shm_overview.7, spufs.7, symlink.7, unix.7, uri.7, sync.8: Global fix: s/file system/filesystem/
Notwithstanding 24d01c530c5a3f75217543d02bf6712395e5f90c,
"filesystem" is the form used by the great majority of man pages
outside the man-pages project and in a number of other sources,
so let's go with that.
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
2013-08-08 08:07:57 +00:00
|
|
|
Not all filesystems support
|
2011-09-19 04:14:01 +00:00
|
|
|
.BR FALLOC_FL_PUNCH_HOLE ;
|
intro.1, time.1, access.2, acct.2, alloc_hugepages.2, bind.2, chdir.2, chmod.2, chown.2, chroot.2, clone.2, close.2, execve.2, fallocate.2, fcntl.2, getdents.2, getrusage.2, getxattr.2, init_module.2, inotify_add_watch.2, ioprio_set.2, kcmp.2, link.2, listxattr.2, lseek.2, madvise.2, mkdir.2, mknod.2, mmap.2, mount.2, move_pages.2, msgctl.2, nfsservctl.2, open.2, pivot_root.2, quotactl.2, read.2, readlink.2, removexattr.2, rename.2, rmdir.2, semctl.2, setfsgid.2, setfsuid.2, setresuid.2, setuid.2, setup.2, setxattr.2, shmctl.2, splice.2, spu_create.2, stat.2, statfs.2, swapon.2, symlink.2, sync.2, sync_file_range.2, sysfs.2, truncate.2, umount.2, unlink.2, unshare.2, ustat.2, utime.2, utimensat.2, write.2, btree.3, errno.3, fexecve.3, ftw.3, futimes.3, get_nprocs_conf.3, getcwd.3, getdirentries.3, getmntent.3, glob.3, mkfifo.3, mq_open.3, readdir.3, realpath.3, recno.3, remove.3, sem_open.3, shm_open.3, statvfs.3, sysconf.3, telldir.3, tmpfile.3, cciss.4, initrd.4, pts.4, sk98lin.4, vcs.4, core.5, filesystems.5, proc.5, boot.7, bootparam.7, capabilities.7, cpuset.7, credentials.7, feature_test_macros.7, fifo.7, hier.7, inotify.7, intro.7, mq_overview.7, path_resolution.7, pipe.7, sem_overview.7, shm_overview.7, spufs.7, symlink.7, unix.7, uri.7, sync.8: Global fix: s/file system/filesystem/
Notwithstanding 24d01c530c5a3f75217543d02bf6712395e5f90c,
"filesystem" is the form used by the great majority of man pages
outside the man-pages project and in a number of other sources,
so let's go with that.
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
2013-08-08 08:07:57 +00:00
|
|
|
if a filesystem doesn't support the operation, an error is returned.
|
2014-04-30 18:04:08 +00:00
|
|
|
The operation is supported on at least the following filesystems:
|
2014-01-22 11:38:17 +00:00
|
|
|
.IP * 3
|
|
|
|
|
XFS (since Linux 2.6.38)
|
|
|
|
|
.IP *
|
|
|
|
|
ext4 (since Linux 3.0)
|
|
|
|
|
.\" commit a4bb6b64e39abc0e41ca077725f2a72c868e7622
|
|
|
|
|
.IP *
|
|
|
|
|
Btrfs (since Linux 3.7)
|
|
|
|
|
.IP *
|
|
|
|
|
tmpfs (since Linux 3.5)
|
|
|
|
|
.\" commit 83e4fa9c16e4af7122e31be3eca5d57881d236fe
|
2014-02-18 16:39:53 +00:00
|
|
|
.SS Collapsing file space
|
2014-04-17 13:33:31 +00:00
|
|
|
.\" commit 00f5e61998dd17f5375d9dfc01331f104b83f841
|
2014-04-17 12:12:16 +00:00
|
|
|
Specifying the
|
2014-02-18 16:39:53 +00:00
|
|
|
.BR FALLOC_FL_COLLAPSE_RANGE
|
2014-04-17 13:33:31 +00:00
|
|
|
flag (available since Linux 3.15) in
|
2014-02-18 16:39:53 +00:00
|
|
|
.I mode
|
2014-04-17 13:33:31 +00:00
|
|
|
removes a byte range from a file, without leaving a hole.
|
|
|
|
|
The byte range to be collapsed starts at
|
2014-02-18 16:39:53 +00:00
|
|
|
.I offset
|
2014-04-17 13:33:31 +00:00
|
|
|
and continues for
|
2014-02-18 16:39:53 +00:00
|
|
|
.I len
|
2014-04-17 12:12:16 +00:00
|
|
|
bytes.
|
2014-04-17 13:33:31 +00:00
|
|
|
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.
|
2014-02-18 16:39:53 +00:00
|
|
|
|
2014-04-17 13:33:31 +00:00
|
|
|
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 ()
|
|
|
|
|
will fail with the error
|
|
|
|
|
.BR EINVAL
|
|
|
|
|
if this requirement is violated.
|
2014-02-18 16:39:53 +00:00
|
|
|
|
2014-04-17 13:33:31 +00:00
|
|
|
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.
|
|
|
|
|
|
|
|
|
|
No other flags may be specified in
|
|
|
|
|
.IR mode
|
|
|
|
|
in conjunction with
|
|
|
|
|
.BR FALLOC_FL_COLLAPSE_RANGE .
|
2014-02-18 16:39:53 +00:00
|
|
|
|
2014-04-17 13:33:31 +00:00
|
|
|
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
|
2014-04-30 14:09:27 +00:00
|
|
|
.SS Zeroing file space
|
2014-04-30 18:03:15 +00:00
|
|
|
Specifying the
|
2014-04-30 14:09:27 +00:00
|
|
|
.BR FALLOC_FL_ZERO_RANGE
|
2014-04-30 18:03:15 +00:00
|
|
|
flag (available since Linux 3.14)
|
|
|
|
|
.\" commit 409332b65d3ed8cfa7a8030f1e9d52f372219642
|
|
|
|
|
in
|
2014-04-30 14:09:27 +00:00
|
|
|
.I mode
|
|
|
|
|
zeroes 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
|
2014-04-30 18:03:15 +00:00
|
|
|
that span the holes in the file.
|
|
|
|
|
After a successful call, subsequent
|
2014-04-30 14:09:27 +00:00
|
|
|
reads from this range will return zeroes.
|
|
|
|
|
|
2014-04-30 18:03:15 +00:00
|
|
|
Zeroing is done within the filesystem preferably by converting range into
|
|
|
|
|
unwritten extents which requires very little I/O to be issued mostly for
|
|
|
|
|
metadata.
|
|
|
|
|
This means that the range will not be physically zeroed out
|
2014-04-30 14:09:27 +00:00
|
|
|
on the device.
|
|
|
|
|
|
|
|
|
|
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
|
2014-04-30 18:03:15 +00:00
|
|
|
is greater than the file size.
|
|
|
|
|
This behaviour is the same as when preallocating space with
|
2014-04-30 14:09:27 +00:00
|
|
|
.B FALLOC_FL_KEEP_SIZE
|
|
|
|
|
specified.
|
|
|
|
|
|
|
|
|
|
Not all filesystems support
|
|
|
|
|
.BR FALLOC_FL_ZERO_RANGE ;
|
|
|
|
|
if a filesystem doesn't support the operation, an error is returned.
|
2014-04-30 18:03:15 +00:00
|
|
|
The operation is supported on at least the following filesystems:
|
2014-04-30 14:09:27 +00:00
|
|
|
.IP * 3
|
|
|
|
|
XFS (since Linux 2.14)
|
|
|
|
|
.\" commit 376ba313147b4172f3e8cf620b9fb591f3e8cdfa
|
|
|
|
|
.IP *
|
|
|
|
|
ext4 (since Linux 3.14)
|
|
|
|
|
.\" commit b8a8684502a0fc852afa0056c6bb2a9273f6fcc0
|
|
|
|
|
|
2007-09-10 04:30:43 +00:00
|
|
|
.SH RETURN VALUE
|
2013-06-10 08:01:01 +00:00
|
|
|
On success,
|
2007-09-10 04:30:43 +00:00
|
|
|
.BR fallocate ()
|
2013-04-19 06:26:03 +00:00
|
|
|
returns zero.
|
|
|
|
|
On error, \-1 is returned and
|
|
|
|
|
.I errno
|
|
|
|
|
is set to indicate the error.
|
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
|
2012-02-26 22:17:23 +00:00
|
|
|
.\" 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
|
2007-09-10 04:30:43 +00:00
|
|
|
was less than or equal to 0.
|
|
|
|
|
.TP
|
2014-04-17 13:33:31 +00:00
|
|
|
.B EINVAL
|
|
|
|
|
.I mode
|
|
|
|
|
is
|
|
|
|
|
.BR 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
|
|
|
|
|
.BR FALLOC_FL_COLLAPSE_RANGE ,
|
|
|
|
|
but either
|
|
|
|
|
.I offset
|
|
|
|
|
or
|
|
|
|
|
.I len
|
|
|
|
|
is not a multiple of the filesystem block size.
|
|
|
|
|
.TP
|
|
|
|
|
.B EINVAL
|
2014-04-27 21:52:25 +00:00
|
|
|
.I mode
|
|
|
|
|
contains both
|
2014-04-17 13:33:31 +00:00
|
|
|
.B FALLOC_FL_COLLAPSE_RANGE
|
|
|
|
|
and other flags;
|
|
|
|
|
no other flags are permitted with
|
|
|
|
|
.BR FALLOC_FL_COLLAPSE_RANGE .
|
2014-04-27 21:52:25 +00:00
|
|
|
.TP
|
|
|
|
|
.B EINVAL
|
2014-04-19 06:13:29 +00:00
|
|
|
.I mode
|
|
|
|
|
is
|
2014-04-30 14:09:27 +00:00
|
|
|
.BR FALLOC_FL_COLLAPSE_RANGE
|
|
|
|
|
or
|
|
|
|
|
.BR FALLOC_FL_ZERO_RANGE,
|
2014-04-19 06:13:29 +00:00
|
|
|
but the file referred to by
|
|
|
|
|
.I fd
|
|
|
|
|
is not a regular file.
|
|
|
|
|
.\" There was a inconsistency in 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
|
2014-04-17 13:33:31 +00:00
|
|
|
.TP
|
2007-09-10 04:30:43 +00:00
|
|
|
.B EIO
|
intro.1, time.1, access.2, acct.2, alloc_hugepages.2, bind.2, chdir.2, chmod.2, chown.2, chroot.2, clone.2, close.2, execve.2, fallocate.2, fcntl.2, getdents.2, getrusage.2, getxattr.2, init_module.2, inotify_add_watch.2, ioprio_set.2, kcmp.2, link.2, listxattr.2, lseek.2, madvise.2, mkdir.2, mknod.2, mmap.2, mount.2, move_pages.2, msgctl.2, nfsservctl.2, open.2, pivot_root.2, quotactl.2, read.2, readlink.2, removexattr.2, rename.2, rmdir.2, semctl.2, setfsgid.2, setfsuid.2, setresuid.2, setuid.2, setup.2, setxattr.2, shmctl.2, splice.2, spu_create.2, stat.2, statfs.2, swapon.2, symlink.2, sync.2, sync_file_range.2, sysfs.2, truncate.2, umount.2, unlink.2, unshare.2, ustat.2, utime.2, utimensat.2, write.2, btree.3, errno.3, fexecve.3, ftw.3, futimes.3, get_nprocs_conf.3, getcwd.3, getdirentries.3, getmntent.3, glob.3, mkfifo.3, mq_open.3, readdir.3, realpath.3, recno.3, remove.3, sem_open.3, shm_open.3, statvfs.3, sysconf.3, telldir.3, tmpfile.3, cciss.4, initrd.4, pts.4, sk98lin.4, vcs.4, core.5, filesystems.5, proc.5, boot.7, bootparam.7, capabilities.7, cpuset.7, credentials.7, feature_test_macros.7, fifo.7, hier.7, inotify.7, intro.7, mq_overview.7, path_resolution.7, pipe.7, sem_overview.7, shm_overview.7, spufs.7, symlink.7, unix.7, uri.7, sync.8: Global fix: s/file system/filesystem/
Notwithstanding 24d01c530c5a3f75217543d02bf6712395e5f90c,
"filesystem" is the form used by the great majority of man pages
outside the man-pages project and in a number of other sources,
so let's go with that.
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
2013-08-08 08:07:57 +00:00
|
|
|
An I/O error occurred while reading from or writing to a filesystem.
|
2007-09-10 04:30:43 +00:00
|
|
|
.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
|
2012-04-22 22:07:47 +00:00
|
|
|
This kernel does not implement
|
|
|
|
|
.BR fallocate ().
|
2007-09-10 04:30:43 +00:00
|
|
|
.TP
|
|
|
|
|
.B EOPNOTSUPP
|
intro.1, time.1, access.2, acct.2, alloc_hugepages.2, bind.2, chdir.2, chmod.2, chown.2, chroot.2, clone.2, close.2, execve.2, fallocate.2, fcntl.2, getdents.2, getrusage.2, getxattr.2, init_module.2, inotify_add_watch.2, ioprio_set.2, kcmp.2, link.2, listxattr.2, lseek.2, madvise.2, mkdir.2, mknod.2, mmap.2, mount.2, move_pages.2, msgctl.2, nfsservctl.2, open.2, pivot_root.2, quotactl.2, read.2, readlink.2, removexattr.2, rename.2, rmdir.2, semctl.2, setfsgid.2, setfsuid.2, setresuid.2, setuid.2, setup.2, setxattr.2, shmctl.2, splice.2, spu_create.2, stat.2, statfs.2, swapon.2, symlink.2, sync.2, sync_file_range.2, sysfs.2, truncate.2, umount.2, unlink.2, unshare.2, ustat.2, utime.2, utimensat.2, write.2, btree.3, errno.3, fexecve.3, ftw.3, futimes.3, get_nprocs_conf.3, getcwd.3, getdirentries.3, getmntent.3, glob.3, mkfifo.3, mq_open.3, readdir.3, realpath.3, recno.3, remove.3, sem_open.3, shm_open.3, statvfs.3, sysconf.3, telldir.3, tmpfile.3, cciss.4, initrd.4, pts.4, sk98lin.4, vcs.4, core.5, filesystems.5, proc.5, boot.7, bootparam.7, capabilities.7, cpuset.7, credentials.7, feature_test_macros.7, fifo.7, hier.7, inotify.7, intro.7, mq_overview.7, path_resolution.7, pipe.7, sem_overview.7, shm_overview.7, spufs.7, symlink.7, unix.7, uri.7, sync.8: Global fix: s/file system/filesystem/
Notwithstanding 24d01c530c5a3f75217543d02bf6712395e5f90c,
"filesystem" is the form used by the great majority of man pages
outside the man-pages project and in a number of other sources,
so let's go with that.
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
2013-08-08 08:07:57 +00:00
|
|
|
The filesystem containing the file referred to by
|
2012-04-22 22:07:47 +00:00
|
|
|
.I fd
|
|
|
|
|
does not support this operation;
|
|
|
|
|
or the
|
2007-09-10 04:30:43 +00:00
|
|
|
.I mode
|
intro.1, time.1, access.2, acct.2, alloc_hugepages.2, bind.2, chdir.2, chmod.2, chown.2, chroot.2, clone.2, close.2, execve.2, fallocate.2, fcntl.2, getdents.2, getrusage.2, getxattr.2, init_module.2, inotify_add_watch.2, ioprio_set.2, kcmp.2, link.2, listxattr.2, lseek.2, madvise.2, mkdir.2, mknod.2, mmap.2, mount.2, move_pages.2, msgctl.2, nfsservctl.2, open.2, pivot_root.2, quotactl.2, read.2, readlink.2, removexattr.2, rename.2, rmdir.2, semctl.2, setfsgid.2, setfsuid.2, setresuid.2, setuid.2, setup.2, setxattr.2, shmctl.2, splice.2, spu_create.2, stat.2, statfs.2, swapon.2, symlink.2, sync.2, sync_file_range.2, sysfs.2, truncate.2, umount.2, unlink.2, unshare.2, ustat.2, utime.2, utimensat.2, write.2, btree.3, errno.3, fexecve.3, ftw.3, futimes.3, get_nprocs_conf.3, getcwd.3, getdirentries.3, getmntent.3, glob.3, mkfifo.3, mq_open.3, readdir.3, realpath.3, recno.3, remove.3, sem_open.3, shm_open.3, statvfs.3, sysconf.3, telldir.3, tmpfile.3, cciss.4, initrd.4, pts.4, sk98lin.4, vcs.4, core.5, filesystems.5, proc.5, boot.7, bootparam.7, capabilities.7, cpuset.7, credentials.7, feature_test_macros.7, fifo.7, hier.7, inotify.7, intro.7, mq_overview.7, path_resolution.7, pipe.7, sem_overview.7, shm_overview.7, spufs.7, symlink.7, unix.7, uri.7, sync.8: Global fix: s/file system/filesystem/
Notwithstanding 24d01c530c5a3f75217543d02bf6712395e5f90c,
"filesystem" is the form used by the great majority of man pages
outside the man-pages project and in a number of other sources,
so let's go with that.
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
2013-08-08 08:07:57 +00:00
|
|
|
is not supported by the filesystem containing the file referred to by
|
2007-09-10 04:30:43 +00:00
|
|
|
.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:20:56 +00:00
|
|
|
.BR chattr (1)).
|
2011-09-19 04:17:53 +00:00
|
|
|
Or:
|
|
|
|
|
.I mode
|
|
|
|
|
specifies
|
|
|
|
|
.BR FALLOC_FL_PUNCH_HOLE
|
2014-04-17 13:33:31 +00:00
|
|
|
or
|
|
|
|
|
.BR FALLOC_FL_COLLAPSE_RANGE
|
2011-09-19 04:17:53 +00:00
|
|
|
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.
|
2014-04-17 13:33:31 +00:00
|
|
|
.TP
|
|
|
|
|
.B ETXTBSY
|
|
|
|
|
.I mode
|
|
|
|
|
specifies
|
|
|
|
|
.BR FALLOC_FL_COLLAPSE_RANGE ,
|
|
|
|
|
but the file referred to by
|
|
|
|
|
.IR fd
|
|
|
|
|
is currently being executed.
|
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.
|
2013-01-10 22:39:00 +00:00
|
|
|
The
|
|
|
|
|
.BR FALLOC_FL_*
|
|
|
|
|
flags are defined in glibc headers only since version 2.18.
|
|
|
|
|
.\" See http://sourceware.org/bugzilla/show_bug.cgi?id=14964
|
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
|
2013-02-11 23:46:49 +00:00
|
|
|
.BR fallocate (1),
|
2007-09-10 04:30:43 +00:00
|
|
|
.BR ftruncate (2),
|
2008-07-14 15:52:21 +00:00
|
|
|
.BR posix_fadvise (3),
|
|
|
|
|
.BR posix_fallocate (3)
|