docs: Added All NetBSD Manuals

1 files changed, 538 insertions, 0 deletions

diff --git a/static/netbsd/man3/dbopen.3 b/static/netbsd/man3/dbopen.3
new file mode 100644
index 00000000..1db9a25f
--- /dev/null
+++ b/static/netbsd/man3/dbopen.3
@@ -0,0 +1,538 @@
+.\"	$NetBSD: dbopen.3,v 1.19 2010/12/16 12:08:16 jruoho Exp $
+.\"
+.\" Copyright (c) 1990, 1993
+.\"	The Regents of the University of California.  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.
+.\" 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.
+.\"
+.\"	@(#)dbopen.3	8.5 (Berkeley) 1/2/94
+.\"
+.Dd December 16, 2010
+.Dt DBOPEN 3
+.Os
+.Sh NAME
+.Nm dbopen ,
+.Nm db
+.Nd database access methods
+.Sh SYNOPSIS
+.In sys/types.h
+.In limits.h
+.In db.h
+.In fcntl.h
+.Ft DB *
+.Fn dbopen "const char *file" "int flags" "mode_t mode" \
+"DBTYPE type" "const void *openinfo"
+.Sh DESCRIPTION
+.Nm
+is the library interface to database files.
+The supported file formats are btree, hashed, and UNIX file oriented.
+The btree format is a representation of a sorted, balanced tree
+structure.
+The hashed format is an extensible, dynamic hashing scheme.
+The flat-file format is a byte stream file with fixed or variable
+length records.
+The formats and file format specific information are described in
+detail in their respective manual pages
+.Xr btree 3 ,
+.Xr hash 3 ,
+and
+.Xr recno 3 .
+.Pp
+The
+.Fn dbopen
+function opens
+.Fa file
+for reading and/or writing.
+Files never intended to be preserved on disk may be created by setting
+the file parameter to
+.Dv NULL .
+.Pp
+The
+.Fa flags
+and
+.Fa mode
+arguments are as specified to the
+.Xr open 2
+routine, however, only the
+.Dv O_CREAT ,
+.Dv O_EXCL ,
+.Dv O_EXLOCK ,
+.Dv O_NONBLOCK ,
+.Dv O_RDONLY ,
+.Dv O_RDWR ,
+.Dv O_SHLOCK ,
+and
+.Dv O_TRUNC
+flags are meaningful.
+(Note, opening a database file
+.Dv O_WRONLY
+is not possible.)
+.\"Three additional options may be specified by or'ing
+.\"them into the
+.\".Fa flags
+.\"argument.
+.\".Pp
+.\".Dv DB_LOCK
+.\"Do the necessary locking in the database to support concurrent access.
+.\"If concurrent access isn't needed or the database is read-only this
+.\"flag should not be set, as it tends to have an associated performance
+.\"penalty.
+.\".Pp
+.\".Dv DB_SHMEM
+.\"Place the underlying memory pool used by the database in shared
+.\"memory.
+.\"Necessary for concurrent access.
+.\".Pp
+.\".Dv DB_TXN
+.\"Support transactions in the database.
+.\"The
+.\".Dv DB_LOCK
+.\"and
+.\".Dv DB_SHMEM
+.\"flags must be set as well.
+.Pp
+The
+.Fa type
+argument is of type
+.Vt DBTYPE
+(as defined in the
+.In db.h
+include file) and may be set to
+.Dv DB_BTREE ,
+.Dv DB_HASH ,
+or
+.Dv DB_RECNO .
+.Pp
+The
+.Fa openinfo
+argument is a pointer to an access method specific structure described
+in the access method's manual page.
+If
+.Fa openinfo
+is
+.Dv NULL ,
+each access method will use defaults appropriate for the system and
+the access method.
+.Ss The DB Structure
+The
+.Fn dbopen
+function returns a pointer to a DB structure on success and
+.Dv NULL
+on error.
+The DB structure is defined in the
+.In db.h
+include file, and contains at least the following fields:
+.Bd -literal -offset indent
+typedef struct {
+	DBTYPE type;
+	int (*close)(const DB *db);
+	int (*del)(const DB *db, const DBT *key, u_int flags);
+	int (*fd)(const DB *db);
+	int (*get)(const DB *db, DBT *key, DBT *data, u_int flags);
+	int (*put)(const DB *db, DBT *key, const DBT *data,
+	    u_int flags);
+	int (*sync)(const DB *db, u_int flags);
+	int (*seq)(const DB *db, DBT *key, DBT *data, u_int flags);
+} DB;
+.Ed
+.Pp
+These elements describe a database type and a set of functions
+performing various actions.
+These functions take a pointer to a structure as returned by
+.Nm ,
+and sometimes one or more pointers to key/data structures and a flag
+value.
+.Bl -tag -width closex -offset indent
+.It Fa type
+The type of the underlying access method (and file format).
+.It Fa close
+A pointer to a routine to flush any cached information to disk, free
+any allocated resources, and close the underlying file(s).
+Since key/data pairs may be cached in memory, failing to sync the file
+with a
+.Fa close
+or
+.Fa sync
+function may result in inconsistent or lost information.
+.Fa close
+routines return \-1 on error (setting
+.Va errno )
+and 0 on success.
+.It Fa del
+A pointer to a routine to remove key/data pairs from the database.
+.Pp
+The parameter
+.Fa flag
+may be set to the following value:
+.Bl -tag -width R_CURSORX
+.It Dv R_CURSOR
+Delete the record referenced by the cursor.
+The cursor must have previously been initialized.
+.El
+.Pp
+.Fa delete
+routines return \-1 on error (setting
+.Va errno ) ,
+0 on success, and 1 if the specified
+.Fa key
+was not in the file.
+.It Fa fd
+A pointer to a routine which returns a file descriptor representative
+of the underlying database.
+A file descriptor referencing the same file will be returned to all
+processes which call
+.Nm
+with the same
+.Fa file
+name.
+This file descriptor may be safely used as an argument to the
+.Xr fcntl 2
+and
+.Xr flock 2
+locking functions.
+The file descriptor is not necessarily associated with any of the
+underlying files used by the access method.
+No file descriptor is available for in memory databases.
+.Fa fd
+routines return \-1 on error (setting
+.Va errno ) ,
+and the file descriptor on success.
+.It Fa get
+A pointer to a routine which is the interface for keyed retrieval from
+the database.
+The address and length of the data associated with the specified
+.Fa key
+are returned in the structure referenced by
+.Fa data .
+.Fa get
+routines return \-1 on error (setting
+.Va errno ) ,
+0 on success, and 1 if the
+.Fa key
+was not in the file.
+.It Fa put
+A pointer to a routine to store key/data pairs in the database.
+.Pp
+The parameter
+.Fa flag
+may be set to one of the following values:
+.Bl -tag -width R_NOOVERWRITEX
+.It Dv R_CURSOR
+Replace the key/data pair referenced by the cursor.
+The cursor must have previously been initialized.
+.It Dv R_IAFTER
+Append the data immediately after the data referenced by
+.Fa key ,
+creating a new key/data pair.
+The record number of the appended key/data pair is returned in the
+.Fa key
+structure.
+(Applicable only to the
+.Dv DB_RECNO
+access method.)
+.It Dv R_IBEFORE
+Insert the data immediately before the data referenced by
+.Fa key ,
+creating a new key/data pair.
+The record number of the inserted key/data pair is returned in the
+.Fa key
+structure.
+(Applicable only to the
+.Dv DB_RECNO
+access method.)
+.It Dv R_NOOVERWRITE
+Enter the new key/data pair only if the key does not previously
+exist.
+.It Dv R_SETCURSOR
+Store the key/data pair, setting or initializing the position of the
+cursor to reference it.
+(Applicable only to the
+.Dv DB_BTREE
+and
+.Dv DB_RECNO
+access methods.)
+.El
+.Pp
+.Dv R_SETCURSOR
+is available only for the
+.Dv DB_BTREE
+and
+.Dv DB_RECNO
+access methods because it implies that the keys have an inherent order
+which does not change.
+.Pp
+.Dv R_IAFTER
+and
+.Dv R_IBEFORE
+are available only for the
+.Dv DB_RECNO
+access method because they each imply that the access method is able
+to create new keys.
+This is only true if the keys are ordered and independent, record
+numbers for example.
+.Pp
+The default behavior of the
+.Fa put
+routines is to enter the new key/data pair, replacing any previously
+existing key.
+.Pp
+.Fa put
+routines return \-1 on error (setting
+.Va errno ) ,
+0 on success, and 1 if the
+.Dv R_NOOVERWRITE
+.Fa flag
+was set and the key already exists in the file.
+.It Fa seq
+A pointer to a routine which is the interface for sequential
+retrieval from the database.
+The address and length of the key are returned in the structure
+referenced by
+.Fa key ,
+and the address and length of the data are returned in the
+structure referenced by
+.Fa data .
+.Pp
+Sequential key/data pair retrieval may begin at any time, and the
+position of the
+.Dq cursor
+is not affected by calls to the
+.Fa del ,
+.Fa get ,
+.Fa put ,
+or
+.Fa sync
+routines.
+Modifications to the database during a sequential scan will be
+reflected in the scan, i.e., records inserted behind the cursor will
+not be returned while records inserted in front of the cursor will be
+returned.
+.Pp
+The flag value
+.Em must
+be set to one of the following values:
+.Bl -tag -width R_CURSORX
+.It Dv R_CURSOR
+The data associated with the specified key is returned.
+This differs from the
+.Fa get
+routines in that it sets or initializes the cursor to the location of
+the key as well.
+(Note, for the
+.Dv DB_BTREE
+access method, the returned key is not necessarily an exact match for
+the specified key.
+The returned key is the smallest key greater than or equal to the
+specified key, permitting partial key matches and range searches.)
+.It Dv R_FIRST
+The first key/data pair of the database is returned, and the cursor
+is set or initialized to reference it.
+.It Dv R_LAST
+The last key/data pair of the database is returned, and the cursor
+is set or initialized to reference it.
+(Applicable only to the
+.Dv DB_BTREE
+and
+.Dv DB_RECNO
+access methods.)
+.It Dv R_NEXT
+Retrieve the key/data pair immediately after the cursor.
+If the cursor is not yet set, this is the same as the
+.Dv R_FIRST
+flag.
+.It Dv R_PREV
+Retrieve the key/data pair immediately before the cursor.
+If the cursor is not yet set, this is the same as the
+.Dv R_LAST
+flag.
+(Applicable only to the
+.Dv DB_BTREE
+and
+.Dv DB_RECNO
+access methods.)
+.El
+.Pp
+.Dv R_LAST
+and
+.Dv R_PREV
+are available only for the
+.Dv DB_BTREE
+and
+.Dv DB_RECNO
+access methods because they each imply that the keys have an inherent
+order which does not change.
+.Pp
+.Fa seq
+routines return \-1 on error (setting
+.Va errno ) ,
+0 on success and 1 if there are no key/data pairs less than or greater
+than the specified or current key.
+If the
+.Dv DB_RECNO
+access method is being used, and if the database file is a character
+special file and no complete key/data pairs are currently available,
+the
+.Fa seq
+routines return 2.
+.It Fa sync
+A pointer to a routine to flush any cached information to disk.
+If the database is in memory only, the
+.Fa sync
+routine has no effect and will always succeed.
+.Pp
+The flag value may be set to the following value:
+.Bl -tag -width ".Dv R_RECNOSYNC"
+.It Dv R_RECNOSYNC
+If the
+.Dv DB_RECNO
+access method is being used, this flag causes the sync routine to
+apply to the btree file which underlies the recno file, not the recno
+file itself.
+(See the
+.Fa bfname
+field of the
+.Xr recno 3
+manual page for more information.)
+.El
+.Pp
+.Fa sync
+routines return \-1 on error (setting
+.Va errno )
+and 0 on success.
+.El
+.Ss Key/data Pairs
+Access to all file types is based on key/data pairs.
+Both keys and data are represented by the following data structure:
+.Bd -literal -offset indent
+typedef struct {
+	void *data;
+	size_t size;
+} DBT;
+.Ed
+.Pp
+The elements of the DBT structure are defined as follows:
+.Bl -tag -width datax -offset indent
+.It Fa data
+A pointer to a byte string.
+.It Fa size
+The length of the byte string.
+.El
+.Pp
+Key and data byte strings may reference strings of essentially
+unlimited length although any two of them must fit into available
+memory at the same time.
+It should be noted that the access methods provide no guarantees about
+byte string alignment.
+.Sh ERRORS
+The
+.Nm
+routine may fail and set
+.Va errno
+for any of the errors specified for the library routines
+.Xr open 2
+and
+.Xr malloc 3
+or the following:
+.Bl -tag -width Er
+.It Er EFTYPE
+A file is incorrectly formatted.
+.It Er EINVAL
+A parameter has been specified (hash function, pad byte, etc.) that is
+incompatible with the current file specification or which is not
+meaningful for the function (for example, use of the cursor without
+prior initialization) or there is a mismatch between the version
+number of file and the software.
+.It Er EFBIG
+The key could not be inserted due to limitations in the DB file format
+(e.g., a hash database was out of overflow pages).
+.El
+.Pp
+The
+.Fa close
+routines may fail and set
+.Va errno
+for any of the errors specified for the library routines
+.Xr close 2 ,
+.Xr read 2 ,
+.Xr write 2 ,
+.Xr free 3 ,
+or
+.Xr fsync 2 .
+.Pp
+The
+.Fa del ,
+.Fa get ,
+.Fa put ,
+and
+.Fa seq
+routines may fail and set
+.Va errno
+for any of the errors specified for the library routines
+.Xr read 2 ,
+.Xr write 2 ,
+.Xr free 3 ,
+or
+.Xr malloc 3 .
+.Pp
+The
+.Fa fd
+routines will fail and set
+.Va errno
+to
+.Er ENOENT
+for in memory databases.
+.Pp
+The
+.Fa sync
+routines may fail and set
+.Va errno
+for any of the errors specified for the library routine
+.Xr fsync 2 .
+.Sh SEE ALSO
+.Xr btree 3 ,
+.Xr hash 3 ,
+.Xr mpool 3 ,
+.Xr recno 3
+.Pp
+.Rs
+.%T LIBTP: Portable, Modular Transactions for UNIX
+.%A Margo Seltzer
+.%A Michael Olson
+.%I USENIX Association
+.%B Proceedings of the 1992 Winter USENIX Technical Conference
+.%D 1992
+.%P 9-25
+.Re
+.Sh BUGS
+The typedef DBT is a mnemonic for
+.Dq data base thang ,
+and was used because no one could think of a reasonable name that
+wasn't already used.
+.Pp
+The file descriptor interface is a kludge and will be deleted in a
+future version of the interface.
+.Pp
+None of the access methods provide any form of concurrent access,
+locking, or transactions.