--- Libc/Libc-262/db/man/dbopen.3
+++ /dev/null
@@ -1,539 +0,0 @@
-.\" 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. 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.
-.\"
-.\"	@(#)dbopen.3	8.5 (Berkeley) 1/2/94
-.\" $FreeBSD: src/lib/libc/db/man/dbopen.3,v 1.5 2001/10/01 16:08:50 ru Exp $
-.\"
-.Dd January 2, 1994
-.Dt DBOPEN 3
-.Os
-.Sh NAME
-.Nm dbopen
-.Nd "database access methods"
-.Sh SYNOPSIS
-.In sys/types.h
-.In limits.h
-.In db.h
-.Ft DB *
-.Fn dbopen "const char *file" "int flags" "int mode" "DBTYPE type" "const void *openinfo"
-.Sh DESCRIPTION
-.Fn Dbopen
-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
-.Fn Dbopen
-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 , O_EXCL , O_EXLOCK , O_NONBLOCK ,
-.Dv O_RDONLY , O_RDWR , 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
-.\".Em or Ns 'ing
-.\"them into the
-.\".Fa flags
-.\"argument.
-.\".Bl -tag -width indent
-.\".It 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.
-.\".It Dv DB_SHMEM
-.\"Place the underlying memory pool used by the database in shared
-.\"memory.
-.\"Necessary for concurrent access.
-.\".It Dv DB_TXN
-.\"Support transactions in the database.
-.\"The
-.\".Dv DB_LOCK
-.\"and
-.\".Dv DB_SHMEM
-.\"flags must be set as well.
-.\".El
-.Pp
-The
-.Fa type
-argument is of type
-.Ft DBTYPE
-(as defined in the
-.Aq Pa db.h
-include file) and
-may be set to
-.Dv DB_BTREE , 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.
-.Pp
-.Fn Dbopen
-returns a pointer to a
-.Ft DB
-structure on success and
-.Dv NULL
-on error.
-The
-.Ft DB
-structure is defined in the
-.Aq Pa db.h
-include file, and contains at
-least the following fields:
-.Bd -literal
-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
-.Fn dbopen ,
-and sometimes one or more pointers to key/data structures and a flag value.
-.Bl -tag -width indent
-.It Va type
-The type of the underlying access method (and file format).
-.It Va 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
-.Va close
-or
-.Va sync
-function may result in inconsistent or lost information.
-.Va Close
-routines return -1 on error (setting
-.Va errno )
-and 0 on success.
-.It Va del
-A pointer to a routine to remove key/data pairs from the database.
-.Pp
-The parameter
-.Fa flags
-may be set to the following value:
-.Bl -tag -width indent
-.It Dv R_CURSOR
-Delete the record referenced by the cursor.
-The cursor must have previously been initialized.
-.El
-.Pp
-.Va 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 Va 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
-.Fn dbopen
-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.
-.Va \&Fd
-routines return -1 on error (setting
-.Va errno ) ,
-and the file descriptor on success.
-.It Va 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 .
-.Va Get
-routines return -1 on error (setting
-.Va errno ) ,
-0 on success, and 1 if the
-.Fa key
-was not in the file.
-.It Va put
-A pointer to a routine to store key/data pairs in the database.
-.Pp
-The parameter
-.Fa flags
-may be set to one of the following values:
-.Bl -tag -width indent
-.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
-.Va put
-routines is to enter the new key/data pair, replacing any previously
-existing key.
-.Pp
-.Va Put
-routines return -1 on error (setting
-.Va errno ) ,
-0 on success, and 1 if the
-.Dv R_NOOVERWRITE
-flag
-was set and the key already exists in the file.
-.It Va 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
-.Va del ,
-.Va get ,
-.Va put ,
-or
-.Va 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
-.Fa flags
-value
-.Em must
-be set to one of the following values:
-.Bl -tag -width indent
-.It Dv R_CURSOR
-The data associated with the specified key is returned.
-This differs from the
-.Va 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
-.Va 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
-.Va seq
-routines return 2.
-.It Va sync
-A pointer to a routine to flush any cached information to disk.
-If the database is in memory only, the
-.Va sync
-routine has no effect and will always succeed.
-.Pp
-The
-.Fa flags
-value may be set to the following value:
-.Bl -tag -width indent
-.It Dv R_RECNOSYNC
-If the
-.Dv DB_RECNO
-access method is being used, this flag causes
-the
-.Va sync
-routine to apply to the btree file which underlies the
-recno file, not the recno file itself.
-(See the
-.Va bfname
-field of the
-.Xr recno 3
-manual page for more information.)
-.El
-.Pp
-.Va Sync
-routines return -1 on error (setting
-.Va errno )
-and 0 on success.
-.El
-.Sh "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
-typedef struct {
-	void *data;
-	size_t size;
-} DBT;
-.Ed
-.Pp
-The elements of the
-.Ft DBT
-structure are defined as follows:
-.Bl -tag -width "data"
-.It Va data
-A pointer to a byte string.
-.It Va 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
-.Fn dbopen
-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 Bq Er EFTYPE
-A file is incorrectly formatted.
-.It Bq 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.
-.El
-.Pp
-The
-.Va 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
-.Va del ,
-.Va get ,
-.Va put
-and
-.Va 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
-.Va fd
-routines will fail and set
-.Va errno
-to
-.Er ENOENT
-for in memory databases.
-.Pp
-The
-.Va 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
-.Rs
-.%T "LIBTP: Portable, Modular Transactions for UNIX"
-.%A Margo Seltzer
-.%A Michael Olson
-.%R "USENIX proceedings"
-.%D Winter 1992
-.Re
-.Sh BUGS
-The typedef
-.Ft DBT
-is a mnemonic for
-.Dq "data base thang" ,
-and was used
-because noone could think of a reasonable name that wasn't already used.
-.Pp
-The file descriptor interface is a kluge 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.