From 38e876d964346d3e4b88c52732b7ce5966d796a5 Mon Sep 17 00:00:00 2001 From: Dimitri Sokolyuk Date: Thu, 1 Nov 2018 13:35:40 +0100 Subject: import original 1.85 implementation from openbsd libc --- _db1.85/man/dbopen.3 | 538 +++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 538 insertions(+) create mode 100644 _db1.85/man/dbopen.3 (limited to '_db1.85/man/dbopen.3') 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. -- cgit v1.2.3