174 lines
5.4 KiB
Groff
174 lines
5.4 KiB
Groff
.\" $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 .
|