docs: OpenBSD Man Pages Added

1 files changed, 395 insertions, 0 deletions

diff --git a/static/openbsd/man9/buffercache.9 b/static/openbsd/man9/buffercache.9
new file mode 100644
index 00000000..1d31154b
--- /dev/null
+++ b/static/openbsd/man9/buffercache.9
@@ -0,0 +1,395 @@
+.\"	$OpenBSD: buffercache.9,v 1.13 2019/07/19 00:24:31 cheloha Exp $
+.\"     $NetBSD: buffercache.9,v 1.13 2004/06/25 15:31:37 wiz Exp $
+.\"
+.\" Copyright (c)2003 YAMAMOTO Takashi,
+.\" All rights reserved.
+.\"
+.\" 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 AUTHOR 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 AUTHOR 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.
+.\"
+.\"
+.\" following copyright notices are from sys/kern/vfs_bio.c.
+.\" they are here because i took some comments from it.  yamt@NetBSD.org
+.\"
+.\"
+.\"/*-
+.\" * Copyright (c) 1982, 1986, 1989, 1993
+.\" *	The Regents of the University of California.  All rights reserved.
+.\" * (c) UNIX System Laboratories, Inc.
+.\" * All or some portions of this file are derived from material licensed
+.\" * to the University of California by American Telephone and Telegraph
+.\" * Co. or Unix System Laboratories, Inc. and are reproduced herein with
+.\" * the permission of UNIX System Laboratories, Inc.
+.\" *
+.\" * 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.
+.\" * 3. Neither the name of the University nor the names of its contributors
+.\" *    may be used to endorse or promote products derived from this software
+.\" *    without specific prior written permission.
+.\" *
+.\" * THIS SOFTWARE IS PROVIDED BY THE REGENTS 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 REGENTS 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.
+.\" *
+.\" *	@(#)vfs_bio.c	8.6 (Berkeley) 1/11/94
+.\" */
+.\"
+.\"/*-
+.\" * Copyright (c) 1994 Christopher G. Demetriou
+.\" *
+.\" * 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.
+.\" * 3. All advertising materials mentioning features or use of this software
+.\" *    must display the following acknowledgement:
+.\" *	This product includes software developed by the University of
+.\" *	California, Berkeley and its contributors.
+.\" * 4. Neither the name of the University nor the names of its contributors
+.\" *    may be used to endorse or promote products derived from this software
+.\" *    without specific prior written permission.
+.\" *
+.\" * THIS SOFTWARE IS PROVIDED BY THE REGENTS 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 REGENTS 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.
+.\" *
+.\" *	@(#)vfs_bio.c	8.6 (Berkeley) 1/11/94
+.\" */
+.\"
+.\"
+.\" ------------------------------------------------------------
+.Dd $Mdocdate: July 19 2019 $
+.Dt BUFFERCACHE 9
+.Os
+.Sh NAME
+.Nm buffercache ,
+.Nm bread ,
+.Nm bread_cluster ,
+.Nm breadn ,
+.Nm bwrite ,
+.Nm bawrite ,
+.Nm bdwrite ,
+.Nm getblk ,
+.Nm geteblk ,
+.Nm incore ,
+.Nm brelse ,
+.Nm biodone ,
+.Nm biowait
+.Nd buffer cache interfaces
+.\" ------------------------------------------------------------
+.Sh SYNOPSIS
+.In sys/buf.h
+.Ft int
+.Fn bread "struct vnode *vp" "daddr_t blkno" "int size" \
+"struct buf **bpp"
+.Ft int
+.Fn bread_cluster "struct vnode *vp" "daddr_t blkno" "int size" \
+"struct buf **bpp"
+.Ft int
+.Fn breadn "struct vnode *vp" "daddr_t blkno" "int size" \
+"daddr_t rablks[]" "int rasizes[]" "int nrablks" \
+"struct buf **bpp"
+.Ft int
+.Fn bwrite "struct buf *bp"
+.Ft void
+.Fn bawrite "struct buf *bp"
+.Ft void
+.Fn bdwrite "struct buf *bp"
+.Ft struct buf *
+.Fn getblk "struct vnode *vp" "daddr_t blkno" "int size" \
+"int slpflag" "uint64_t slptimeo"
+.Ft struct buf *
+.Fn geteblk "size_t size"
+.Ft struct buf *
+.Fn incore "struct vnode *vp" "daddr_t blkno"
+.Ft void
+.Fn brelse "struct buf *bp"
+.Ft void
+.Fn biodone "struct buf *bp"
+.Ft int
+.Fn biowait "struct buf *bp"
+.\" ------------------------------------------------------------
+.Sh DESCRIPTION
+The
+.Nm
+interface is used by each filesystem to improve I/O performance using
+in-core caches of filesystem blocks.
+.Pp
+The kernel memory used to cache a block is called a buffer and
+described by a
+.Em buf
+structure.
+In addition to describing a cached block, a
+.Em buf
+structure is also used to describe an I/O request as a part of
+the disk driver interface.
+.Pp
+The block size used for logical block numbers depends on the type of the
+given vnode.
+For file vnodes, this is f_iosize of the underlying filesystem.
+For block device vnodes, this will usually be DEV_BSIZE.
+.\" XXX struct buf, B_ flags, MP locks, etc.
+.\" XXX free list, hash queue, etc.
+.\" ------------------------------------------------------------
+.Sh FUNCTIONS
+.Bl -tag -width compact
+.It Fn bread "vp" "blkno" "size" "bpp"
+Read a block corresponding to
+.Fa vp
+and
+.Fa blkno .
+The buffer is returned via
+.Fa bpp .
+.Pp
+If the buffer is not found (i.e. the block is not cached in memory),
+.Fn bread
+calls
+.Fn getblk
+to allocate a buffer with enough pages for
+.Fa size
+and reads the specified disk block into it.
+.Pp
+.Fn bread
+always returns a buffer, even if it returns an error due to an I/O
+error.
+.Pp
+The buffer returned by
+.Fn bread
+is marked as busy.
+(The
+.Dv B_BUSY
+flag is set.)
+After manipulation of the buffer returned from
+.Fn bread ,
+the caller should unbusy it so that another thread can get it.
+If the buffer contents are modified and should be written back to disk,
+it should be unbusied using one of the variants of
+.Fn bwrite .
+Otherwise, it should be unbusied using
+.Fn brelse .
+.\" - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
+.It Xo
+.Fo breadn
+.Fa "vp"
+.Fa "blkno"
+.Fa "size"
+.Fa "rablks"
+.Fa "rasizes"
+.Fa "nrablks"
+.Fa "bpp"
+.Fc
+.Xc
+Get a buffer as
+.Fn bread .
+In addition,
+.Fn breadn
+will start read-ahead of blocks specified by
+.Fa rablks ,
+.Fa rasizes ,
+and
+.Fa nrablks .
+The read-ahead blocks aren't returned, but are available in cache for
+future accesses.
+.\" - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
+.It Xo
+.Fo bread_cluster
+.Fa "vp"
+.Fa "blkno"
+.Fa "size"
+.Fa "bpp"
+.Fc
+.Xc
+Read a block of size
+.Fa "size"
+corresponding to
+.Fa vp
+and
+.Fa blkno ,
+with readahead.
+If neither the first block nor a part of the next MAXBSIZE bytes is already
+in the buffer cache,
+.Fn bread_cluster
+will perform a read-ahead of MAXBSIZE bytes in a single I/O operation.
+This is currently more efficient than
+.Fn breadn .
+The read-ahead data isn't returned, but is available in cache for
+future access.
+.\" - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
+.It Fn bwrite "bp"
+Write a block.
+Start I/O for write using
+.Fn VOP_STRATEGY .
+Then, unless the
+.Dv B_ASYNC
+flag is set in
+.Fa bp ,
+.Fn bwrite
+waits for the I/O to complete.
+.\" - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
+.It Fn bawrite "bp"
+Write a block asynchronously.
+Set the
+.Dv B_ASYNC
+flag in
+.Fa bp
+and simply call
+.Fn VOP_BWRITE ,
+which results in
+.Fn bwrite
+for most filesystems.
+.\" - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
+.It Fn bdwrite "bp"
+Delayed write.
+Unlike
+.Fn bawrite ,
+.Fn bdwrite
+won't start any I/O.
+It only marks the buffer as dirty
+.Pq Dv B_DELWRI
+and unbusies it.
+This routine should be used when the buffer is expected
+to be modified again soon, typically a small write that
+partially fills a buffer.
+.\" - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
+.It Fn getblk "vp" "blkno" "size" "slpflag" "slptimeo"
+Get a block of requested size
+.Fa size
+that is associated with a given vnode and block
+offset, specified by
+.Fa vp
+and
+.Fa blkno .
+If it is found in the block cache, mark it as having been found,
+make it busy and return it.
+Otherwise, return an empty block of the correct size.
+It is up to the caller to ensure that the cached blocks
+are of the correct size.
+.Pp
+If
+.Fn getblk
+needs to sleep,
+.Fa slpflag
+and
+.Fa slptimeo
+are used as arguments for
+.Xr tsleep_nsec 9 .
+.\" - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
+.It Fn geteblk "size"
+Allocate an empty, disassociated block of a given size
+.Fa size .
+.\" - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
+.It Fn incore "vp" "blkno"
+Determine if a block associated with a given vnode and block offset
+is in the cache.
+If it is there, return a pointer to it.
+Note that
+.Fn incore
+doesn't mark the buffer as busy unlike
+.Fn getblk .
+.\" - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
+.It Fn brelse "bp"
+Unlock a buffer by clearing the
+.Dv B_AGE ,
+.Dv B_ASYNC ,
+.Dv B_BUSY ,
+.Dv B_NOCACHE ,
+and
+.Dv B_DEFERRED
+flags and release it to the free lists.
+.\" - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
+.It Fn biodone "bp"
+Mark I/O complete on a buffer.
+If a callback has been requested by
+.Dv B_CALL ,
+do so.
+Otherwise, wake up the waiting processes.
+.\" - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
+.It Fn biowait "bp"
+Wait for operations on the buffer to complete.
+When they do, extract and return the I/O's error value.
+If the operation on the buffer is being done via a direct call to a
+.Fn strategy
+type function, then the buffer must be previously initialized with the
+.Dv B_RAW
+flag.
+.El
+.\" ------------------------------------------------------------
+.Sh CODE REFERENCES
+This section describes places within the
+.Ox
+source tree where actual code implementing the buffer cache subsystem
+can be found.
+All pathnames are relative to
+.Pa /usr/src .
+.Pp
+The buffer cache subsystem is implemented within the file
+.Pa sys/kern/vfs_bio.c .
+.Sh SEE ALSO
+.Xr intro 9 ,
+.Xr vnode 9 ,
+.Xr VOP_STRATEGY 9
+.Rs
+.%A Maurice J. Bach
+.%B "The Design of the UNIX Operating System"
+.%I "Prentice Hall"
+.%D 1986
+.Re
+.Rs
+.%A Marshall Kirk McKusick
+.%A Keith Bostic
+.%A Michael J. Karels
+.%A John S. Quarterman
+.%B "The Design and Implementation of the 4.4BSD Operating System"
+.%I "Addison Wesley"
+.%D 1996
+.Re
+.Rs
+.%A Leffler, et. al.
+.%B "The Design and Implementation of the 4.3 BSD Unix Operating System"
+.%I Addison Wesley
+.%D 1989
+.Re