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
|
|
|
|
|
.\"
|
2013-04-19 06:26:03 +00:00
|
|
|
.TH FALLOCATE 2 2013-04-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
|
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.
|
|
|
|
|
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.
|
|
|
|
|
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
|
2013-04-19 06:26:03 +00:00
|
|
|
On error,
|
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
|
|
|
|
|
.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
|
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
|
2012-04-22 22:07:47 +00:00
|
|
|
The file system containing the file referred to by
|
|
|
|
|
.I fd
|
|
|
|
|
does not support this operation;
|
|
|
|
|
or the
|
2007-09-10 04:30:43 +00:00
|
|
|
.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:20:56 +00:00
|
|
|
.BR chattr (1)).
|
2011-09-19 04:17:53 +00:00
|
|
|
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.
|
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)
|