aboutsummaryrefslogtreecommitdiff
path: root/_db1.85/man/dbopen.3
diff options
context:
space:
mode:
Diffstat (limited to '_db1.85/man/dbopen.3')
-rw-r--r--_db1.85/man/dbopen.3538
1 files changed, 538 insertions, 0 deletions
diff --git a/_db1.85/man/dbopen.3 b/_db1.85/man/dbopen.3
new file mode 100644
index 0000000..87ed04c
--- /dev/null
+++ b/_db1.85/man/dbopen.3
@@ -0,0 +1,538 @@
+.\" $OpenBSD: dbopen.3,v 1.28 2015/09/10 10:20:55 jmc Exp $
+.\" $NetBSD: dbopen.3,v 1.6 1995/02/27 13:23:25 cgd Exp $
+.\"
+.\" Copyright (c) 1997, Phillip F Knaack. All rights reserved.
+.\"
+.\" 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 $Mdocdate: September 10 2015 $
+.Dt DBOPEN 3
+.Os
+.Sh NAME
+.Nm dbopen
+.Nd database access methods
+.Sh SYNOPSIS
+.In sys/types.h
+.In fcntl.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
+The
+.Fn dbopen
+function 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 ,
+.Dv O_EXCL ,
+.Dv O_EXLOCK ,
+.Dv O_NOFOLLOW ,
+.Dv O_NONBLOCK ,
+.Dv O_RDONLY ,
+.Dv O_RDWR ,
+.Dv O_SHLOCK ,
+.Dv O_SYNC ,
+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
+.\".IR or 'ing
+.\"them into the
+.\".I flags
+.\"argument.
+.\".Bl -tag -width XXXXX
+.\".It 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 DB_SHMEM
+.\"Place the underlying memory pool used by the database in shared
+.\"memory.
+.\"Necessary for concurrent access.
+.\".It DB_TXN
+.\"Support transactions in the database.
+.\"The DB_LOCK and DB_SHMEM flags must be set as well.
+.\".El
+.Pp
+The
+.Fa type
+argument is of type
+.Fa 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.
+.Pp
+.Fn dbopen
+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,
+ unsigned int flags);
+ int (*fd)(const DB *db);
+ int (*get)(const DB *db, DBT *key, DBT *data,
+ unsigned int flags);
+ int (*put)(const DB *db, DBT *key, const DBT *data,
+ unsigned int flags);
+ int (*sync)(const DB *db, u_int flags);
+ int (*seq)(const DB *db, DBT *key, DBT *data,
+ unsigned 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 XXXXX -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 flags
+may be set to the following value:
+.Bl -tag -width R_NOOVERWRITE
+.It Dv R_CURSOR
+Delete the record referenced by the cursor.
+The cursor must have previously been initialized.
+.El
+.Pp
+.Fa del
+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
+.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.
+.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.
+.Pp
+.Fa flags
+is currently unused.
+Specifying anything but 0 will result in an error.
+.It Fa 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 R_NOOVERWRITE
+.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
+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
+.Fa flags
+value
+.Sy must
+be set to one of the following values:
+.Bl -tag -width R_NOOVERWRITE
+.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
+.Fa flags
+value may be set to the following value:
+.Bl -tag -width R_NOOVERWRITE
+.It Dv R_RECNOSYNC
+If the
+.Dv DB_RECNO
+access method is being used, this flag causes the
+.Fa 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
+.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 -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 Ds -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
+.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 XEINVALX
+.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 the file and the software.
+.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 recno 3
+.Rs
+.%T "LIBTP: Portable, Modular Transactions for UNIX"
+.%A Margo Seltzer
+.%A Michael Olson
+.%J USENIX proceedings
+.%D Winter 1992
+.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.