docs: Added All NetBSD Manuals

1 files changed, 173 insertions, 0 deletions

diff --git a/static/netbsd/man2/fdiscard.2 b/static/netbsd/man2/fdiscard.2
new file mode 100644
index 00000000..8e2c558c
--- /dev/null
+++ b/static/netbsd/man2/fdiscard.2
@@ -0,0 +1,173 @@
+.\"	$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 .