diff options
Diffstat (limited to 'lib/libc/db/man')
| -rw-r--r-- | lib/libc/db/man/Makefile.inc | 18 | ||||
| -rw-r--r-- | lib/libc/db/man/btree.3 | 275 | ||||
| -rw-r--r-- | lib/libc/db/man/dbm.3 | 230 | ||||
| -rw-r--r-- | lib/libc/db/man/dbopen.3 | 550 | ||||
| -rw-r--r-- | lib/libc/db/man/hash.3 | 200 | ||||
| -rw-r--r-- | lib/libc/db/man/mpool.3 | 231 | ||||
| -rw-r--r-- | lib/libc/db/man/recno.3 | 232 |
7 files changed, 1736 insertions, 0 deletions
diff --git a/lib/libc/db/man/Makefile.inc b/lib/libc/db/man/Makefile.inc new file mode 100644 index 0000000..349b029 --- /dev/null +++ b/lib/libc/db/man/Makefile.inc @@ -0,0 +1,18 @@ +# from @(#)Makefile.inc 8.1 (Berkeley) 6/4/93 +# $FreeBSD$ + +.PATH: ${.CURDIR}/db/man + +MAN+= btree.3 dbm.3 dbopen.3 hash.3 mpool.3 recno.3 + +MLINKS+= dbm.3 dbm_clearerr.3 +MLINKS+= dbm.3 dbm_close.3 +MLINKS+= dbm.3 dbm_delete.3 +MLINKS+= dbm.3 dbm_dirnfo.3 +MLINKS+= dbm.3 dbm_error.3 +MLINKS+= dbm.3 dbm_fetch.3 +MLINKS+= dbm.3 dbm_firstkey.3 +MLINKS+= dbm.3 dbm_nextkey.3 +MLINKS+= dbm.3 dbm_open.3 +MLINKS+= dbm.3 dbm_store.3 +MLINKS+= dbopen.3 db.3 diff --git a/lib/libc/db/man/btree.3 b/lib/libc/db/man/btree.3 new file mode 100644 index 0000000..5712d18 --- /dev/null +++ b/lib/libc/db/man/btree.3 @@ -0,0 +1,275 @@ +.\" 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. +.\" +.\" @(#)btree.3 8.4 (Berkeley) 8/18/94 +.\" $FreeBSD$ +.\" +.Dd August 18, 1994 +.Dt BTREE 3 +.Os +.Sh NAME +.Nm btree +.Nd "btree database access method" +.Sh SYNOPSIS +.In sys/types.h +.In db.h +.Sh DESCRIPTION +The routine +.Fn dbopen +is the library interface to database files. +One of the supported file formats is +.Nm +files. +The general description of the database access methods is in +.Xr dbopen 3 , +this manual page describes only the +.Nm +specific information. +.Pp +The +.Nm +data structure is a sorted, balanced tree structure storing +associated key/data pairs. +.Pp +The +.Nm +access method specific data structure provided to +.Fn dbopen +is defined in the +.In db.h +include file as follows: +.Bd -literal +typedef struct { + u_long flags; + u_int cachesize; + int maxkeypage; + int minkeypage; + u_int psize; + int (*compare)(const DBT *key1, const DBT *key2); + size_t (*prefix)(const DBT *key1, const DBT *key2); + int lorder; +} BTREEINFO; +.Ed +.Pp +The elements of this structure are as follows: +.Bl -tag -width indent +.It Va flags +The flag value is specified by +.Em or Ns 'ing +any of the following values: +.Bl -tag -width indent +.It Dv R_DUP +Permit duplicate keys in the tree, i.e., permit insertion if the key to be +inserted already exists in the tree. +The default behavior, as described in +.Xr dbopen 3 , +is to overwrite a matching key when inserting a new key or to fail if +the +.Dv R_NOOVERWRITE +flag is specified. +The +.Dv R_DUP +flag is overridden by the +.Dv R_NOOVERWRITE +flag, and if the +.Dv R_NOOVERWRITE +flag is specified, attempts to insert duplicate keys into +the tree will fail. +.Pp +If the database contains duplicate keys, the order of retrieval of +key/data pairs is undefined if the +.Va get +routine is used, however, +.Va seq +routine calls with the +.Dv R_CURSOR +flag set will always return the logical +.Dq first +of any group of duplicate keys. +.El +.It Va cachesize +A suggested maximum size (in bytes) of the memory cache. +This value is +.Em only +advisory, and the access method will allocate more memory rather than fail. +Since every search examines the root page of the tree, caching the most +recently used pages substantially improves access time. +In addition, physical writes are delayed as long as possible, so a moderate +cache can reduce the number of I/O operations significantly. +Obviously, using a cache increases (but only increases) the likelihood of +corruption or lost data if the system crashes while a tree is being modified. +If +.Va cachesize +is 0 (no size is specified) a default cache is used. +.It Va maxkeypage +The maximum number of keys which will be stored on any single page. +Not currently implemented. +.\" The maximum number of keys which will be stored on any single page. +.\" Because of the way the +.\" .Nm +.\" data structure works, +.\" .Va maxkeypage +.\" must always be greater than or equal to 2. +.\" If +.\" .Va maxkeypage +.\" is 0 (no maximum number of keys is specified) the page fill factor is +.\" made as large as possible (which is almost invariably what is wanted). +.It Va minkeypage +The minimum number of keys which will be stored on any single page. +This value is used to determine which keys will be stored on overflow +pages, i.e., if a key or data item is longer than the pagesize divided +by the minkeypage value, it will be stored on overflow pages instead +of in the page itself. +If +.Va minkeypage +is 0 (no minimum number of keys is specified) a value of 2 is used. +.It Va psize +Page size is the size (in bytes) of the pages used for nodes in the tree. +The minimum page size is 512 bytes and the maximum page size is 64K. +If +.Va psize +is 0 (no page size is specified) a page size is chosen based on the +underlying file system I/O block size. +.It Va compare +Compare is the key comparison function. +It must return an integer less than, equal to, or greater than zero if the +first key argument is considered to be respectively less than, equal to, +or greater than the second key argument. +The same comparison function must be used on a given tree every time it +is opened. +If +.Va compare +is +.Dv NULL +(no comparison function is specified), the keys are compared +lexically, with shorter keys considered less than longer keys. +.It Va prefix +The +.Va prefix +element +is the prefix comparison function. +If specified, this routine must return the number of bytes of the second key +argument which are necessary to determine that it is greater than the first +key argument. +If the keys are equal, the key length should be returned. +Note, the usefulness of this routine is very data dependent, but, in some +data sets can produce significantly reduced tree sizes and search times. +If +.Va prefix +is +.Dv NULL +(no prefix function is specified), +.Em and +no comparison function is specified, a default lexical comparison routine +is used. +If +.Va prefix +is +.Dv NULL +and a comparison routine is specified, no prefix comparison is +done. +.It Va lorder +The byte order for integers in the stored database metadata. +The number should represent the order as an integer; for example, +big endian order would be the number 4,321. +If +.Va lorder +is 0 (no order is specified) the current host order is used. +.El +.Pp +If the file already exists (and the +.Dv O_TRUNC +flag is not specified), the +values specified for the +.Va flags , lorder +and +.Va psize +arguments +are ignored +in favor of the values used when the tree was created. +.Pp +Forward sequential scans of a tree are from the least key to the greatest. +.Pp +Space freed up by deleting key/data pairs from the tree is never reclaimed, +although it is normally made available for reuse. +This means that the +.Nm +storage structure is grow-only. +The only solutions are to avoid excessive deletions, or to create a fresh +tree periodically from a scan of an existing one. +.Pp +Searches, insertions, and deletions in a +.Nm +will all complete in +O lg base N where base is the average fill factor. +Often, inserting ordered data into +.Nm Ns s +results in a low fill factor. +This implementation has been modified to make ordered insertion the best +case, resulting in a much better than normal page fill factor. +.Sh ERRORS +The +.Nm +access method routines may fail and set +.Va errno +for any of the errors specified for the library routine +.Xr dbopen 3 . +.Sh SEE ALSO +.Xr dbopen 3 , +.Xr hash 3 , +.Xr mpool 3 , +.Xr recno 3 +.Rs +.%T "The Ubiquitous B-tree" +.%A Douglas Comer +.%J "ACM Comput. Surv. 11" +.%N 2 +.%D June 1979 +.%P 121-138 +.Re +.Rs +.%A Bayer +.%A Unterauer +.%T "Prefix B-trees" +.%J "ACM Transactions on Database Systems" +.%N 1 +.%V Vol. 2 +.%D March 1977 +.%P 11-26 +.Re +.Rs +.%B "The Art of Computer Programming Vol. 3: Sorting and Searching" +.%A D. E. Knuth +.%D 1968 +.%P 471-480 +.Re +.Sh BUGS +Only big and little endian byte order is supported. diff --git a/lib/libc/db/man/dbm.3 b/lib/libc/db/man/dbm.3 new file mode 100644 index 0000000..16becc6 --- /dev/null +++ b/lib/libc/db/man/dbm.3 @@ -0,0 +1,230 @@ +.\" Copyright (c) 1999 Tim Singletary +.\" No copyright is claimed. +.\" +.\" 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. +.\" +.\" $FreeBSD$ +.\" +.\" Note: The date here should be updated whenever a non-trivial +.\" change is made to the manual page. +.Dd April 16, 2006 +.Dt DBM 3 +.Os +.Sh NAME +.Nm dbm_clearerr , +.Nm dbm_close , +.Nm dbm_delete , +.Nm dbm_dirfno , +.Nm dbm_error , +.Nm dbm_fetch , +.Nm dbm_firstkey , +.Nm dbm_nextkey , +.Nm dbm_open , +.Nm dbm_store +.Nd database access functions +.Sh SYNOPSIS +.In fcntl.h +.In ndbm.h +.Ft DBM * +.Fn dbm_open "const char *base" "int flags" "int mode" +.Ft void +.Fn dbm_close "DBM *db" +.Ft int +.Fn dbm_store "DBM *db" "datum key" "datum data" "int flags" +.Ft datum +.Fn dbm_fetch "DBM *db" "datum key" +.Ft int +.Fn dbm_delete "DBM *db" "datum key" +.Ft datum +.Fn dbm_firstkey "DBM *db" +.Ft datum +.Fn dbm_nextkey "DBM *db" +.Ft int +.Fn dbm_error "DBM *db" +.Ft int +.Fn dbm_clearerr "DBM *db" +.Ft int +.Fn dbm_dirfno "DBM *db" +.Sh DESCRIPTION +Database access functions. +These functions are implemented using +.Xr dbopen 3 +with a +.Xr hash 3 +database. +.Pp +.Vt datum +is declared in +.In ndbm.h : +.Bd -literal +typedef struct { + char *dptr; + int dsize; +} datum; +.Ed +.Pp +The +.Fn dbm_open base flags mode +function +opens or creates a database. +The +.Fa base +argument +is the basename of the file containing +the database; the actual database has a +.Pa .db +suffix. +I.e., if +.Fa base +is +.Qq Li /home/me/mystuff +then the actual database is in the file +.Pa /home/me/mystuff.db . +The +.Fa flags +and +.Fa mode +arguments +are passed to +.Xr open 2 . +.Pq Dv O_RDWR | O_CREAT +is a typical value for +.Fa flags ; +.Li 0660 +is a typical value for +.Fa mode . +.Dv O_WRONLY +is not allowed in +.Fa flags . +The pointer returned by +.Fn dbm_open +identifies the database and is the +.Fa db +argument to the other functions. +The +.Fn dbm_open +function +returns +.Dv NULL +and sets +.Va errno +if there were any errors. +.Pp +The +.Fn dbm_close db +function +closes the database. +.Pp +The +.Fn dbm_store db key data flags +function +inserts or replaces an entry in the database. +The +.Fa flags +argument +is either +.Dv DBM_INSERT +or +.Dv DBM_REPLACE . +If +.Fa flags +is +.Dv DBM_INSERT +and the database already contains an entry for +.Fa key , +that entry is not replaced. +Otherwise the entry is replaced or inserted. +The +.Fn dbm_store +function +normally returns zero but returns 1 if the entry could not be +inserted (because +.Fa flags +is +.Dv DBM_INSERT , +and an entry with +.Fa key +already exists) or returns -1 and sets +.Va errno +if there were any errors. +.Pp +The +.Fn dbm_fetch db key +function +returns +.Dv NULL +or the +.Fa data +corresponding to +.Fa key . +.Pp +The +.Fn dbm_delete db key +function +deletes the entry for +.Fa key . +The +.Fn dbm_delete +function +normally returns zero but returns 1 if there was no entry with +.Fa key +in the database or returns -1 and sets +.Va errno +if there were any errors. +.Pp +The +.Fn dbm_firstkey db +function +returns the first key in the database. +The +.Fn dbm_nextkey db +function +returns subsequent keys. +The +.Fn db_firstkey +function +must be called before +.Fn dbm_nextkey . +The order in which keys are returned is unspecified and may appear +random. +The +.Fn dbm_nextkey +function +returns +.Dv NULL +after all keys have been returned. +.Pp +The +.Fn dbm_error db +function +returns the +.Va errno +value of the most recent error. +The +.Fn dbm_clearerr db +function +resets this value to 0 and returns 0. +.Pp +The +.Fn dbm_dirfno db +function +returns the file descriptor to the database. +.Sh SEE ALSO +.Xr open 2 , +.Xr dbopen 3 , +.Xr hash 3 +.Sh STANDARDS +These functions (except +.Fn dbm_dirfno ) +are included in the +.St -susv2 . diff --git a/lib/libc/db/man/dbopen.3 b/lib/libc/db/man/dbopen.3 new file mode 100644 index 0000000..f35194b --- /dev/null +++ b/lib/libc/db/man/dbopen.3 @@ -0,0 +1,550 @@ +.\" 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$ +.\" +.Dd January 2, 1994 +.Dt DBOPEN 3 +.Os +.Sh NAME +.Nm dbopen +.Nd "database access methods" +.Sh SYNOPSIS +.In sys/types.h +.In db.h +.In fcntl.h +.In limits.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 +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 +.Fa file +argument 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 is not 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 +.In 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 +The +.Fn dbopen +function +returns a pointer to a +.Ft DB +structure on success and +.Dv NULL +on error. +The +.Ft DB +structure is defined in the +.In db.h +include file, and contains at +least the following fields: +.Bd -literal +typedef struct { + DBTYPE type; + int (*close)(DB *db); + int (*del)(const DB *db, const DBT *key, u_int flags); + int (*fd)(const DB *db); + int (*get)(const DB *db, const 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 +.Fa flags +argument +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 +.Fa flags +argument +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 +argument +.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 +argument 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 +An argument 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 was not 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. diff --git a/lib/libc/db/man/hash.3 b/lib/libc/db/man/hash.3 new file mode 100644 index 0000000..6c2e930 --- /dev/null +++ b/lib/libc/db/man/hash.3 @@ -0,0 +1,200 @@ +.\" 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. +.\" +.\" @(#)hash.3 8.6 (Berkeley) 8/18/94 +.\" $FreeBSD$ +.\" +.Dd August 18, 1994 +.Dt HASH 3 +.Os +.Sh NAME +.Nm hash +.Nd "hash database access method" +.Sh SYNOPSIS +.In sys/types.h +.In db.h +.Sh DESCRIPTION +The routine +.Fn dbopen +is the library interface to database files. +One of the supported file formats is +.Nm +files. +The general description of the database access methods is in +.Xr dbopen 3 , +this manual page describes only the +.Nm +specific information. +.Pp +The +.Nm +data structure is an extensible, dynamic hashing scheme. +.Pp +The access method specific data structure provided to +.Fn dbopen +is defined in the +.In db.h +include file as follows: +.Bd -literal +typedef struct { + u_int bsize; + u_int ffactor; + u_int nelem; + u_int cachesize; + u_int32_t (*hash)(const void *, size_t); + int lorder; +} HASHINFO; +.Ed +.Pp +The elements of this structure are as follows: +.Bl -tag -width indent +.It Va bsize +The +.Va bsize +element +defines the +.Nm +table bucket size, and is, by default, 256 bytes. +It may be preferable to increase the page size for disk-resident tables +and tables with large data items. +.It Va ffactor +The +.Va ffactor +element +indicates a desired density within the +.Nm +table. +It is an approximation of the number of keys allowed to accumulate in any +one bucket, determining when the +.Nm +table grows or shrinks. +The default value is 8. +.It Va nelem +The +.Va nelem +element +is an estimate of the final size of the +.Nm +table. +If not set or set too low, +.Nm +tables will expand gracefully as keys +are entered, although a slight performance degradation may be noticed. +The default value is 1. +.It Va cachesize +A suggested maximum size, in bytes, of the memory cache. +This value is +.Em only +advisory, and the access method will allocate more memory rather +than fail. +.It Va hash +The +.Va hash +element +is a user defined +.Nm +function. +Since no +.Nm +function performs equally well on all possible data, the +user may find that the built-in +.Nm +function does poorly on a particular +data set. +User specified +.Nm +functions must take two arguments (a pointer to a byte +string and a length) and return a 32-bit quantity to be used as the +.Nm +value. +.It Va lorder +The byte order for integers in the stored database metadata. +The number should represent the order as an integer; for example, +big endian order would be the number 4,321. +If +.Va lorder +is 0 (no order is specified) the current host order is used. +If the file already exists, the specified value is ignored and the +value specified when the tree was created is used. +.El +.Pp +If the file already exists (and the +.Dv O_TRUNC +flag is not specified), the +values specified for the +.Va bsize , ffactor , lorder +and +.Va nelem +arguments +are +ignored and the values specified when the tree was created are used. +.Pp +If a +.Nm +function is specified, +.Fn hash_open +will attempt to determine if the +.Nm +function specified is the same as +the one with which the database was created, and will fail if it is not. +.Pp +Backward compatible interfaces to the older +.Em dbm +and +.Em ndbm +routines are provided, however these interfaces are not compatible with +previous file formats. +.Sh ERRORS +The +.Nm +access method routines may fail and set +.Va errno +for any of the errors specified for the library routine +.Xr dbopen 3 . +.Sh SEE ALSO +.Xr btree 3 , +.Xr dbopen 3 , +.Xr mpool 3 , +.Xr recno 3 +.Rs +.%T "Dynamic Hash Tables" +.%A Per-Ake Larson +.%R "Communications of the ACM" +.%D April 1988 +.Re +.Rs +.%T "A New Hash Package for UNIX" +.%A Margo Seltzer +.%R "USENIX Proceedings" +.%D Winter 1991 +.Re +.Sh BUGS +Only big and little endian byte order is supported. diff --git a/lib/libc/db/man/mpool.3 b/lib/libc/db/man/mpool.3 new file mode 100644 index 0000000..0c8a12a --- /dev/null +++ b/lib/libc/db/man/mpool.3 @@ -0,0 +1,231 @@ +.\" 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. +.\" +.\" @(#)mpool.3 8.1 (Berkeley) 6/4/93 +.\" $FreeBSD$ +.\" +.Dd June 4, 1993 +.Dt MPOOL 3 +.Os +.Sh NAME +.Nm mpool +.Nd "shared memory buffer pool" +.Sh SYNOPSIS +.In db.h +.In mpool.h +.Ft MPOOL * +.Fn mpool_open "void *key" "int fd" "pgno_t pagesize" "pgno_t maxcache" +.Ft void +.Fo mpool_filter +.Fa "MPOOL *mp" +.Fa "void (*pgin)(void *, pgno_t, void *)" +.Fa "void (*pgout)(void *, pgno_t, void *)" +.Fa "void *pgcookie" +.Fc +.Ft void * +.Fn mpool_new "MPOOL *mp" "pgno_t *pgnoaddr" +.Ft void * +.Fn mpool_get "MPOOL *mp" "pgno_t pgno" "u_int flags" +.Ft int +.Fn mpool_put "MPOOL *mp" "void *pgaddr" "u_int flags" +.Ft int +.Fn mpool_sync "MPOOL *mp" +.Ft int +.Fn mpool_close "MPOOL *mp" +.Sh DESCRIPTION +The +.Nm mpool +library interface is intended to provide page oriented buffer management +of files. +.Pp +The +.Fn mpool_open +function initializes a memory pool. +The +.Fa key +argument is currently ignored. +The +.Fa fd +argument is a file descriptor for the underlying file, which must be seekable. +.Pp +The +.Fa pagesize +argument is the size, in bytes, of the pages into which the file is broken up. +The +.Fa maxcache +argument is the maximum number of pages from the underlying file to cache +at any one time. +This value is not relative to the number of processes which share a file's +buffers, but will be the largest value specified by any of the processes +sharing the file. +.Pp +The +.Fn mpool_filter +function is intended to make transparent input and output processing of the +pages possible. +If the +.Fa pgin +function is specified, it is called each time a buffer is read into the memory +pool from the backing file. +If the +.Fa pgout +function is specified, it is called each time a buffer is written into the +backing file. +Both functions are called with the +.Fa pgcookie +pointer, the page number and a pointer to the page to being read or written. +.Pp +The +.Fn mpool_new +function takes an +.Ft MPOOL +pointer and an address as arguments. +If a new page can be allocated, a pointer to the page is returned and +the page number is stored into the +.Fa pgnoaddr +address. +Otherwise, +.Dv NULL +is returned and +.Va errno +is set. +.Pp +The +.Fn mpool_get +function takes a +.Ft MPOOL +pointer and a page number as arguments. +If the page exists, a pointer to the page is returned. +Otherwise, +.Dv NULL +is returned and +.Va errno +is set. +The +.Fa flags +argument is not currently used. +.Pp +The +.Fn mpool_put +function unpins the page referenced by +.Fa pgaddr . +The +.Fa pgaddr +argument +must be an address previously returned by +.Fn mpool_get +or +.Fn mpool_new . +The +.Fa flags +argument is specified by +.Em or Ns 'ing +any of the following values: +.Bl -tag -width indent +.It Dv MPOOL_DIRTY +The page has been modified and needs to be written to the backing file. +.El +.Pp +The +.Fn mpool_put +function +returns 0 on success and -1 if an error occurs. +.Pp +The +.Fn mpool_sync +function writes all modified pages associated with the +.Ft MPOOL +pointer to the +backing file. +The +.Fn mpool_sync +function +returns 0 on success and -1 if an error occurs. +.Pp +The +.Fn mpool_close +function free's up any allocated memory associated with the memory pool +cookie. +Modified pages are +.Em not +written to the backing file. +The +.Fn mpool_close +function +returns 0 on success and -1 if an error occurs. +.Sh ERRORS +The +.Fn mpool_open +function may fail and set +.Va errno +for any of the errors specified for the library routine +.Xr malloc 3 . +.Pp +The +.Fn mpool_get +function may fail and set +.Va errno +for the following: +.Bl -tag -width Er +.It Bq Er EINVAL +The requested record does not exist. +.El +.Pp +The +.Fn mpool_new +and +.Fn mpool_get +functions may fail and set +.Va errno +for any of the errors specified for the library routines +.Xr read 2 , +.Xr write 2 , +and +.Xr malloc 3 . +.Pp +The +.Fn mpool_sync +function may fail and set +.Va errno +for any of the errors specified for the library routine +.Xr write 2 . +.Pp +The +.Fn mpool_close +function may fail and set +.Va errno +for any of the errors specified for the library routine +.Xr free 3 . +.Sh SEE ALSO +.Xr btree 3 , +.Xr dbopen 3 , +.Xr hash 3 , +.Xr recno 3 diff --git a/lib/libc/db/man/recno.3 b/lib/libc/db/man/recno.3 new file mode 100644 index 0000000..726f74f --- /dev/null +++ b/lib/libc/db/man/recno.3 @@ -0,0 +1,232 @@ +.\" 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. +.\" +.\" @(#)recno.3 8.5 (Berkeley) 8/18/94 +.\" $FreeBSD$ +.\" +.Dd August 18, 1994 +.Dt RECNO 3 +.Os +.Sh NAME +.Nm recno +.Nd "record number database access method" +.Sh SYNOPSIS +.In sys/types.h +.In db.h +.Sh DESCRIPTION +The routine +.Fn dbopen +is the library interface to database files. +One of the supported file formats is record number files. +The general description of the database access methods is in +.Xr dbopen 3 , +this manual page describes only the +.Nm +specific information. +.Pp +The record number data structure is either variable or fixed-length +records stored in a flat-file format, accessed by the logical record +number. +The existence of record number five implies the existence of records +one through four, and the deletion of record number one causes +record number five to be renumbered to record number four, as well +as the cursor, if positioned after record number one, to shift down +one record. +.Pp +The +.Nm +access method specific data structure provided to +.Fn dbopen +is defined in the +.In db.h +include file as follows: +.Bd -literal +typedef struct { + u_long flags; + u_int cachesize; + u_int psize; + int lorder; + size_t reclen; + u_char bval; + char *bfname; +} RECNOINFO; +.Ed +.Pp +The elements of this structure are defined as follows: +.Bl -tag -width indent +.It Va flags +The flag value is specified by +.Em or Ns 'ing +any of the following values: +.Bl -tag -width indent +.It Dv R_FIXEDLEN +The records are fixed-length, not byte delimited. +The structure element +.Va reclen +specifies the length of the record, and the structure element +.Va bval +is used as the pad character. +Any records, inserted into the database, that are less than +.Va reclen +bytes long are automatically padded. +.It Dv R_NOKEY +In the interface specified by +.Fn dbopen , +the sequential record retrieval fills in both the caller's key and +data structures. +If the +.Dv R_NOKEY +flag is specified, the +.Em cursor +routines are not required to fill in the key structure. +This permits applications to retrieve records at the end of files without +reading all of the intervening records. +.It Dv R_SNAPSHOT +This flag requires that a snapshot of the file be taken when +.Fn dbopen +is called, instead of permitting any unmodified records to be read from +the original file. +.El +.It Va cachesize +A suggested maximum size, in bytes, of the memory cache. +This value is +.Em only +advisory, and the access method will allocate more memory rather than fail. +If +.Va cachesize +is 0 (no size is specified) a default cache is used. +.It Va psize +The +.Nm +access method stores the in-memory copies of its records +in a btree. +This value is the size (in bytes) of the pages used for nodes in that tree. +If +.Va psize +is 0 (no page size is specified) a page size is chosen based on the +underlying file system I/O block size. +See +.Xr btree 3 +for more information. +.It Va lorder +The byte order for integers in the stored database metadata. +The number should represent the order as an integer; for example, +big endian order would be the number 4,321. +If +.Va lorder +is 0 (no order is specified) the current host order is used. +.It Va reclen +The length of a fixed-length record. +.It Va bval +The delimiting byte to be used to mark the end of a record for +variable-length records, and the pad character for fixed-length +records. +If no value is specified, newlines +.Pq Dq \en +are used to mark the end +of variable-length records and fixed-length records are padded with +spaces. +.It Va bfname +The +.Nm +access method stores the in-memory copies of its records +in a btree. +If +.Va bfname +is +.No non\- Ns Dv NULL , +it specifies the name of the btree file, +as if specified as the file name for a +.Fn dbopen +of a btree file. +.El +.Pp +The data part of the key/data pair used by the +.Nm +access method +is the same as other access methods. +The key is different. +The +.Va data +field of the key should be a pointer to a memory location of type +.Ft recno_t , +as defined in the +.In db.h +include file. +This type is normally the largest unsigned integral type available to +the implementation. +The +.Va size +field of the key should be the size of that type. +.Pp +Because there can be no meta-data associated with the underlying +.Nm +access method files, any changes made to the default values +(e.g.\& fixed record length or byte separator value) must be explicitly +specified each time the file is opened. +.Pp +In the interface specified by +.Fn dbopen , +using the +.Va put +interface to create a new record will cause the creation of multiple, +empty records if the record number is more than one greater than the +largest record currently in the database. +.Sh ERRORS +The +.Nm +access method routines may fail and set +.Va errno +for any of the errors specified for the library routine +.Xr dbopen 3 +or the following: +.Bl -tag -width Er +.It Bq Er EINVAL +An attempt was made to add a record to a fixed-length database that +was too large to fit. +.El +.Sh SEE ALSO +.Xr btree 3 , +.Xr dbopen 3 , +.Xr hash 3 , +.Xr mpool 3 +.Rs +.%T "Document Processing in a Relational Database System" +.%A Michael Stonebraker +.%A Heidi Stettner +.%A Joseph Kalash +.%A Antonin Guttman +.%A Nadene Lynn +.%R "Memorandum No. UCB/ERL M82/32" +.%D May 1982 +.Re +.Sh BUGS +Only big and little endian byte order is supported. |
