.\"	$NetBSD: fdiscard.2,v 1.5 2016/06/30 18:43:43 wiz Exp $
.\"
.\" Copyright (c) 2014 The NetBSD Foundation, Inc.
.\" All rights reserved.
.\"
.\" This code is derived from software contributed to The NetBSD Foundation
.\" by David A. Holland.
.\"
.\" Redistribution and use in source and binary forms, with or without
.\" modification, are permitted provided that the following conditions
.\" are met:
.\" 1. Redistributions of source code must retain the above copyright
.\"    notice, this list of conditions and the following disclaimer.
.\" 2. Redistributions in binary form must reproduce the above copyright
.\"    notice, this list of conditions and the following disclaimer in the
.\"    documentation and/or other materials provided with the distribution.
.\"
.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS
.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
.\" PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS
.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
.\" POSSIBILITY OF SUCH DAMAGE.
.\"
.Dd June 30, 2016
.Dt FDISCARD 2
.Os
.Sh NAME
.Nm posix_fallocate ,
.Nm fdiscard
.Nd allocate or discard backing store for files
.Sh LIBRARY
.Lb libc
.Sh SYNOPSIS
.In fcntl.h
.Ft int
.Fn posix_fallocate "int fd" "off_t pos" "off_t length"
.In unistd.h
.Ft int
.Fn fdiscard "int fd" "off_t pos" "off_t length"
.Sh DESCRIPTION
The
.Fn posix_fallocate
call allocates backing store for the file referenced by
.Fa fd
in the region starting at
.Fa pos
bytes from the start of the file and continuing for
.Fa length
bytes more.
If the region extends past the current end of file, the file size is
increased to cover the region.
.Pp
The
.Fn fdiscard
call discards backing store for the file referenced by
.Fa fd
in the region starting at
.Fa pos
bytes from the start of the file and continuing for
.Fa length
bytes more.
The file size is not affected.
.Pp
Both calls operate on the basis of file system blocks, so
.Fn posix_fallocate
may allocate more physical space than requested and
.Fn fdiscard
may discard less physical space than requested.
.Pp
When
.Fn posix_fallocate
is applied to an unallocated region in a regular file (a
.Dq hole ) ,
the hole is filled and the visible contents are unaffected; both holes
and newly allocated regions read as all zeros.
If
.Fn posix_fallocate
is applied to an already-allocated region in a regular file,
it has no effect.
.Pp
When
.Fn fdiscard
is applied to a regular file, a hole is created and any data in the
affected region is thrown away.
Subsequent reads of the region return zeros.
.Pp
If
.Fn fdiscard
is applied to a device, and the device supports an underlying discard
operation, that operation is invoked.
For example, ATA flash devices and solid-state disks support an
operation called TRIM that discards blocks at the device level.
The behavior of blocks discarded at this level is
implementation-defined; as devices vary, specific behavior should not
be relied upon.
Subsequent reads of the same block may return zeros; such reads may
also, however, continue to return the previously written data, or
return other data, or return indeterminate garbage; or may switch
between any of these behaviors at unpredictable points later on.
.Pp
For both calls, the file
.Fa fd
must be open for writing and may not be a directory or socket.
.Sh RESTRICTIONS
Because there is no way for
.Fn posix_fallocate
to report a partial failure, errors may require some or all of the
work it has already done to be unwound, which may be expensive.
It is recommended to set the file length first with
.Xr ftruncate 2
and only then allocate space within the file using
.Fn posix_fallocate .
.Pp
Depending on the implementation, even a failing call to
.Fn posix_fallocate
may allocate some space to the target file.
Such a call will not, however, change the file size.
.Pp
Furthermore, in some implementations, the space reservations created
by
.Fn posix_fallocate
may not be persistent after a crash or reboot if the space reserved
has not yet been written to.
.Sh RETURN VALUES
If successful, the
.Fn posix_fallocate
function will return zero.
Otherwise an error number will be returned, without setting
.Va errno .
.Pp
If successful, the
.Fn fdiscard
function will return zero.
Otherwise the value \-1 is returned and the global variable
.Va errno
is set to indicate the error.
.Sh ERRORS
.Bl -tag -width Er
.It Bq Er EBADF
The file handle
.Fa fd
is invalid or not open for writing.
.It Bq Er EDQUOT
Allocating the requested blocks would exceed the user's quota.
.It Bq Er EINVAL
The position and/or length values are negative.
.It Bq Er EIO
A hardware-level I/O error occurred.
.It Bq Er EISDIR
The selected file is a directory.
.It Bq Er ENOSPC
There was no space in the file system to complete the operation.
.El
.Sh SEE ALSO
.Xr ftruncate 2
.Sh HISTORY
The
.Fn posix_fallocate
and
.Fn fdiscard
function calls appeared in
.Nx 7.0 .
Similar functions appeared previously in Linux.
The
.Fn posix_fallocate
function is expected to conform to
.St -p1003.1-2004 .