diff options
Diffstat (limited to 'lib/libc/db/man')
| -rw-r--r-- | lib/libc/db/man/Makefile.inc | 10 | ||||
| -rw-r--r-- | lib/libc/db/man/btree.3 | 233 | ||||
| -rw-r--r-- | lib/libc/db/man/dbopen.3 | 476 | ||||
| -rw-r--r-- | lib/libc/db/man/hash.3 | 159 | ||||
| -rw-r--r-- | lib/libc/db/man/mpool.3 | 220 | ||||
| -rw-r--r-- | lib/libc/db/man/recno.3 | 216 |
6 files changed, 0 insertions, 1314 deletions
diff --git a/lib/libc/db/man/Makefile.inc b/lib/libc/db/man/Makefile.inc deleted file mode 100644 index 2c70dd07..0000000 --- a/lib/libc/db/man/Makefile.inc +++ /dev/null @@ -1,10 +0,0 @@ -# from @(#)Makefile.inc 8.1 (Berkeley) 6/4/93 -# $Id: Makefile.inc,v 1.6 1997/10/16 14:26:09 bde Exp $ - -.PATH: ${.CURDIR}/../libc/db/man - -.if ${LIB} == "c" -MAN3+= btree.3 dbopen.3 hash.3 mpool.3 recno.3 - -MLINKS+= dbopen.3 db.3 -.endif diff --git a/lib/libc/db/man/btree.3 b/lib/libc/db/man/btree.3 deleted file mode 100644 index 8284b21..0000000 --- a/lib/libc/db/man/btree.3 +++ /dev/null @@ -1,233 +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. -.\" -.\" @(#)btree.3 8.4 (Berkeley) 8/18/94 -.\" -.TH BTREE 3 "August 18, 1994" -.\".UC 7 -.SH NAME -btree \- btree database access method -.SH SYNOPSIS -.nf -.ft B -#include <sys/types.h> -#include <db.h> -.ft R -.fi -.SH DESCRIPTION -The routine -.IR dbopen -is the library interface to database files. -One of the supported file formats is btree files. -The general description of the database access methods is in -.IR dbopen (3), -this manual page describes only the btree specific information. -.PP -The btree data structure is a sorted, balanced tree structure storing -associated key/data pairs. -.PP -The btree access method specific data structure provided to -.I dbopen -is defined in the <db.h> include file as follows: -.PP -typedef struct { -.RS -u_long flags; -.br -u_int cachesize; -.br -int maxkeypage; -.br -int minkeypage; -.br -u_int psize; -.br -int (*compare)(const DBT *key1, const DBT *key2); -.br -size_t (*prefix)(const DBT *key1, const DBT *key2); -.br -int lorder; -.RE -} BTREEINFO; -.PP -The elements of this structure are as follows: -.TP -flags -The flag value is specified by -.IR or 'ing -any of the following values: -.RS -.TP -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 -.IR dbopen (3), -is to overwrite a matching key when inserting a new key or to fail if -the R_NOOVERWRITE flag is specified. -The R_DUP flag is overridden by the R_NOOVERWRITE flag, and if the -R_NOOVERWRITE flag is specified, attempts to insert duplicate keys into -the tree will fail. -.IP -If the database contains duplicate keys, the order of retrieval of -key/data pairs is undefined if the -.I get -routine is used, however, -.I seq -routine calls with the R_CURSOR flag set will always return the logical -``first'' of any group of duplicate keys. -.RE -.TP -cachesize -A suggested maximum size (in bytes) of the memory cache. -This value is -.B 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 -.I cachesize -is 0 (no size is specified) a default cache is used. -.TP -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 btree data structure works, -.\" .I maxkeypage -.\" must always be greater than or equal to 2. -.\" If -.\" .I 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). -.TP -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 -.I minkeypage -is 0 (no minimum number of keys is specified) a value of 2 is used. -.TP -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 -.I psize -is 0 (no page size is specified) a page size is chosen based on the -underlying file system I/O block size. -.TP -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 -.I compare -is NULL (no comparison function is specified), the keys are compared -lexically, with shorter keys considered less than longer keys. -.TP -prefix -Prefix 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 -.I prefix -is NULL (no prefix function is specified), -.B and -no comparison function is specified, a default lexical comparison routine -is used. -If -.I prefix -is NULL and a comparison routine is specified, no prefix comparison is -done. -.TP -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 -.I lorder -is 0 (no order is specified) the current host order is used. -.PP -If the file already exists (and the O_TRUNC flag is not specified), the -values specified for the parameters flags, lorder and psize 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 btree 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 btree will all complete in -O lg base N where base is the average fill factor. -Often, inserting ordered data into btrees 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 -.I btree -access method routines may fail and set -.I errno -for any of the errors specified for the library routine -.IR dbopen (3). -.SH "SEE ALSO" -.IR dbopen (3), -.IR hash (3), -.IR mpool (3), -.IR recno (3) -.sp -.IR "The Ubiquitous B-tree" , -Douglas Comer, ACM Comput. Surv. 11, 2 (June 1979), 121-138. -.sp -.IR "Prefix B-trees" , -Bayer and Unterauer, ACM Transactions on Database Systems, Vol. 2, 1 -(March 1977), 11-26. -.sp -.IR "The Art of Computer Programming Vol. 3: Sorting and Searching" , -D.E. Knuth, 1968, pp 471-480. -.SH BUGS -Only big and little endian byte order is supported. diff --git a/lib/libc/db/man/dbopen.3 b/lib/libc/db/man/dbopen.3 deleted file mode 100644 index f06a4ef..0000000 --- a/lib/libc/db/man/dbopen.3 +++ /dev/null @@ -1,476 +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 -.\" -.TH DBOPEN 3 "January 2, 1994" -.UC 7 -.SH NAME -dbopen \- database access methods -.SH SYNOPSIS -.nf -.ft B -#include <sys/types.h> -#include <limits.h> -#include <db.h> - -DB * -dbopen(const char *file, int flags, int mode, DBTYPE type, -.ti +5 -const void *openinfo); -.ft R -.fi -.SH DESCRIPTION -.IR 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 -.IR btree (3), -.IR hash (3) -and -.IR recno (3). -.PP -Dbopen opens -.I file -for reading and/or writing. -Files never intended to be preserved on disk may be created by setting -the file parameter to NULL. -.PP -The -.I flags -and -.I mode arguments -are as specified to the -.IR open (2) -routine, however, only the O_CREAT, O_EXCL, O_EXLOCK, O_NONBLOCK, -O_RDONLY, O_RDWR, O_SHLOCK and O_TRUNC flags are meaningful. -(Note, opening a database file O_WRONLY is not possible.) -.\"Three additional options may be specified by -.\".IR or 'ing -.\"them into the -.\".I flags -.\"argument. -.\".TP -.\"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. -.\".TP -.\"DB_SHMEM -.\"Place the underlying memory pool used by the database in shared -.\"memory. -.\"Necessary for concurrent access. -.\".TP -.\"DB_TXN -.\"Support transactions in the database. -.\"The DB_LOCK and DB_SHMEM flags must be set as well. -.PP -The -.I type -argument is of type DBTYPE (as defined in the <db.h> include file) and -may be set to DB_BTREE, DB_HASH or DB_RECNO. -.PP -The -.I openinfo -argument is a pointer to an access method specific structure described -in the access method's manual page. -If -.I openinfo -is NULL, each access method will use defaults appropriate for the system -and the access method. -.PP -.I Dbopen -returns a pointer to a DB structure on success and NULL on error. -The DB structure is defined in the <db.h> include file, and contains at -least the following fields: -.sp -.nf -typedef struct { -.RS -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, -.ti +5 -u_int flags); -int (*sync)(const DB *db, u_int flags); -int (*seq)(const DB *db, DBT *key, DBT *data, u_int flags); -.RE -} DB; -.fi -.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 -.IR dbopen , -and sometimes one or more pointers to key/data structures and a flag value. -.TP -type -The type of the underlying access method (and file format). -.TP -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 -.I close -or -.I sync -function may result in inconsistent or lost information. -.I Close -routines return -1 on error (setting -.IR errno ) -and 0 on success. -.TP -del -A pointer to a routine to remove key/data pairs from the database. -.IP -The parameter -.I flag -may be set to the following value: -.RS -.TP -R_CURSOR -Delete the record referenced by the cursor. -The cursor must have previously been initialized. -.RE -.IP -.I Delete -routines return -1 on error (setting -.IR errno ), -0 on success, and 1 if the specified -.I key -was not in the file. -.TP -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 -.I dbopen -with the same -.I file -name. -This file descriptor may be safely used as an argument to the -.IR fcntl (2) -and -.IR 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. -.I Fd -routines return -1 on error (setting -.IR errno ), -and the file descriptor on success. -.TP -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 -.I key -are returned in the structure referenced by -.IR data . -.I Get -routines return -1 on error (setting -.IR errno ), -0 on success, and 1 if the -.I key -was not in the file. -.TP -put -A pointer to a routine to store key/data pairs in the database. -.IP -The parameter -.I flag -may be set to one of the following values: -.RS -.TP -R_CURSOR -Replace the key/data pair referenced by the cursor. -The cursor must have previously been initialized. -.TP -R_IAFTER -Append the data immediately after the data referenced by -.IR key , -creating a new key/data pair. -The record number of the appended key/data pair is returned in the -.I key -structure. -(Applicable only to the DB_RECNO access method.) -.TP -R_IBEFORE -Insert the data immediately before the data referenced by -.IR key , -creating a new key/data pair. -The record number of the inserted key/data pair is returned in the -.I key -structure. -(Applicable only to the DB_RECNO access method.) -.TP -R_NOOVERWRITE -Enter the new key/data pair only if the key does not previously exist. -.TP -R_SETCURSOR -Store the key/data pair, setting or initializing the position of the -cursor to reference it. -(Applicable only to the DB_BTREE and DB_RECNO access methods.) -.RE -.IP -R_SETCURSOR is available only for the DB_BTREE and DB_RECNO access -methods because it implies that the keys have an inherent order -which does not change. -.IP -R_IAFTER and R_IBEFORE are available only for the 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. -.IP -The default behavior of the -.I put -routines is to enter the new key/data pair, replacing any previously -existing key. -.IP -.I Put -routines return -1 on error (setting -.IR errno ), -0 on success, and 1 if the R_NOOVERWRITE -.I flag -was set and the key already exists in the file. -.TP -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 -.IR key , -and the address and length of the data are returned in the -structure referenced -by -.IR data . -.IP -Sequential key/data pair retrieval may begin at any time, and the -position of the ``cursor'' is not affected by calls to the -.IR del , -.IR get , -.IR put , -or -.I 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. -.IP -The flag value -.B must -be set to one of the following values: -.RS -.TP -R_CURSOR -The data associated with the specified key is returned. -This differs from the -.I get -routines in that it sets or initializes the cursor to the location of -the key as well. -(Note, for the 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.) -.TP -R_FIRST -The first key/data pair of the database is returned, and the cursor -is set or initialized to reference it. -.TP -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 DB_BTREE and DB_RECNO access methods.) -.TP -R_NEXT -Retrieve the key/data pair immediately after the cursor. -If the cursor is not yet set, this is the same as the R_FIRST flag. -.TP -R_PREV -Retrieve the key/data pair immediately before the cursor. -If the cursor is not yet set, this is the same as the R_LAST flag. -(Applicable only to the DB_BTREE and DB_RECNO access methods.) -.RE -.IP -R_LAST and R_PREV are available only for the DB_BTREE and DB_RECNO -access methods because they each imply that the keys have an inherent -order which does not change. -.IP -.I Seq -routines return -1 on error (setting -.IR 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 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 -.I seq -routines return 2. -.TP -sync -A pointer to a routine to flush any cached information to disk. -If the database is in memory only, the -.I sync -routine has no effect and will always succeed. -.IP -The flag value may be set to the following value: -.RS -.TP -R_RECNOSYNC -If the DB_RECNO access method is being used, this flag causes -the sync routine to apply to the btree file which underlies the -recno file, not the recno file itself. -(See the -.I bfname -field of the -.IR recno (3) -manual page for more information.) -.RE -.IP -.I Sync -routines return -1 on error (setting -.IR errno ) -and 0 on success. -.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: -.PP -typedef struct { -.RS -void *data; -.br -size_t size; -.RE -} DBT; -.PP -The elements of the DBT structure are defined as follows: -.TP -data -A pointer to a byte string. -.TP -size -The length of the byte string. -.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 -.I dbopen -routine may fail and set -.I errno -for any of the errors specified for the library routines -.IR open (2) -and -.IR malloc (3) -or the following: -.TP -[EFTYPE] -A file is incorrectly formatted. -.TP -[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. -.PP -The -.I close -routines may fail and set -.I errno -for any of the errors specified for the library routines -.IR close (2), -.IR read (2), -.IR write (2), -.IR free (3), -or -.IR fsync (2). -.PP -The -.IR del , -.IR get , -.I put -and -.I seq -routines may fail and set -.I errno -for any of the errors specified for the library routines -.IR read (2), -.IR write (2), -.IR free (3) -or -.IR malloc (3). -.PP -The -.I fd -routines will fail and set -.I errno -to ENOENT for in memory databases. -.PP -The -.I sync -routines may fail and set -.I errno -for any of the errors specified for the library routine -.IR fsync (2). -.SH "SEE ALSO" -.IR btree (3), -.IR hash (3), -.IR mpool (3), -.IR recno (3) -.sp -.IR "LIBTP: Portable, Modular Transactions for UNIX" , -Margo Seltzer, Michael Olson, USENIX proceedings, Winter 1992. -.SH BUGS -The typedef DBT is a mnemonic for ``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. diff --git a/lib/libc/db/man/hash.3 b/lib/libc/db/man/hash.3 deleted file mode 100644 index d408b5d..0000000 --- a/lib/libc/db/man/hash.3 +++ /dev/null @@ -1,159 +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. -.\" -.\" @(#)hash.3 8.6 (Berkeley) 8/18/94 -.\" -.TH HASH 3 "August 18, 1994" -.UC 7 -.SH NAME -hash \- hash database access method -.SH SYNOPSIS -.nf -.ft B -#include <sys/types.h> -#include <db.h> -.ft R -.fi -.SH DESCRIPTION -The routine -.IR dbopen -is the library interface to database files. -One of the supported file formats is hash files. -The general description of the database access methods is in -.IR dbopen (3), -this manual page describes only the hash specific information. -.PP -The hash data structure is an extensible, dynamic hashing scheme. -.PP -The access method specific data structure provided to -.I dbopen -is defined in the <db.h> include file as follows: -.sp -typedef struct { -.RS -u_int bsize; -.br -u_int ffactor; -.br -u_int nelem; -.br -u_int cachesize; -.br -u_int32_t (*hash)(const void *, size_t); -.br -int lorder; -.RE -} HASHINFO; -.PP -The elements of this structure are as follows: -.TP -bsize -.I Bsize -defines the hash 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. -.TP -ffactor -.I Ffactor -indicates a desired density within the hash table. -It is an approximation of the number of keys allowed to accumulate in any -one bucket, determining when the hash table grows or shrinks. -The default value is 8. -.TP -nelem -.I Nelem -is an estimate of the final size of the hash table. -If not set or set too low, hash tables will expand gracefully as keys -are entered, although a slight performance degradation may be noticed. -The default value is 1. -.TP -cachesize -A suggested maximum size, in bytes, of the memory cache. -This value is -.B only -advisory, and the access method will allocate more memory rather -than fail. -.TP -hash -.I Hash -is a user defined hash function. -Since no hash function performs equally well on all possible data, the -user may find that the built-in hash function does poorly on a particular -data set. -User specified hash 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 hash -value. -.TP -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 -.I 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. -.PP -If the file already exists (and the O_TRUNC flag is not specified), the -values specified for the parameters bsize, ffactor, lorder and nelem are -ignored and the values specified when the tree was created are used. -.PP -If a hash function is specified, -.I hash_open -will attempt to determine if the hash 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 -.I dbm -and -.I ndbm -routines are provided, however these interfaces are not compatible with -previous file formats. -.SH ERRORS -The -.I hash -access method routines may fail and set -.I errno -for any of the errors specified for the library routine -.IR dbopen (3). -.SH "SEE ALSO" -.IR btree (3), -.IR dbopen (3), -.IR mpool (3), -.IR recno (3) -.sp -.IR "Dynamic Hash Tables" , -Per-Ake Larson, Communications of the ACM, April 1988. -.sp -.IR "A New Hash Package for UNIX" , -Margo Seltzer, USENIX Proceedings, Winter 1991. -.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 deleted file mode 100644 index e625dc4..0000000 --- a/lib/libc/db/man/mpool.3 +++ /dev/null @@ -1,220 +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. -.\" -.\" @(#)mpool.3 8.1 (Berkeley) 6/4/93 -.\" $Id$ -.\" -.TH MPOOL 3 "June 4, 1993" -.UC 7 -.SH NAME -mpool \- shared memory buffer pool -.SH SYNOPSIS -.nf -.ft B -#include <db.h> -#include <mpool.h> - -MPOOL * -mpool_open (DBT *key, int fd, pgno_t pagesize, pgno_t maxcache); - -void -mpool_filter (MPOOL *mp, void (*pgin)(void *, pgno_t, void *), -.ti +5 -void (*pgout)(void *, pgno_t, void *), void *pgcookie); - -void * -mpool_new (MPOOL *mp, pgno_t *pgnoaddr); - -void * -mpool_get (MPOOL *mp, pgno_t pgno, u_int flags); - -int -mpool_put (MPOOL *mp, void *pgaddr, u_int flags); - -int -mpool_sync (MPOOL *mp); - -int -mpool_close (MPOOL *mp); -.ft R -.fi -.SH DESCRIPTION -.IR Mpool -is the library interface intended to provide page oriented buffer management -of files. -The buffers may be shared between processes. -.PP -The function -.I mpool_open -initializes a memory pool. -The -.I key -argument is the byte string used to negotiate between multiple -processes wishing to share buffers. -If the file buffers are mapped in shared memory, all processes using -the same key will share the buffers. -If -.I key -is NULL, the buffers are mapped into private memory. -The -.I fd -argument is a file descriptor for the underlying file, which must be seekable. -If -.I key -is non-NULL and matches a file already being mapped, the -.I fd -argument is ignored. -.PP -The -.I pagesize -argument is the size, in bytes, of the pages into which the file is broken up. -The -.I 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 -.I mpool_filter -function is intended to make transparent input and output processing of the -pages possible. -If the -.I pgin -function is specified, it is called each time a buffer is read into the memory -pool from the backing file. -If the -.I pgout -function is specified, it is called each time a buffer is written into the -backing file. -Both functions are called with the -.I pgcookie -pointer, the page number and a pointer to the page to being read or written. -.PP -The function -.I mpool_new -takes an 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 -.I pgnoaddr -address. -Otherwise, NULL is returned and errno is set. -.PP -The function -.I mpool_get -takes a MPOOL pointer and a page number as arguments. -If the page exists, a pointer to the page is returned. -Otherwise, NULL is returned and errno is set. -The flags parameter is not currently used. -.PP -The function -.I mpool_put -unpins the page referenced by -.IR pgaddr . -.I Pgaddr -must be an address previously returned by -.I mpool_get -or -.IR mpool_new . -The flag value is specified by -.IR or 'ing -any of the following values: -.TP -MPOOL_DIRTY -The page has been modified and needs to be written to the backing file. -.PP -.I Mpool_put -returns 0 on success and -1 if an error occurs. -.PP -The function -.I mpool_sync -writes all modified pages associated with the MPOOL pointer to the -backing file. -.I Mpool_sync -returns 0 on success and -1 if an error occurs. -.PP -The -.I mpool_close -function free's up any allocated memory associated with the memory pool -cookie. -Modified pages are -.B not -written to the backing file. -.I Mpool_close -returns 0 on success and -1 if an error occurs. -.SH ERRORS -The -.I mpool_open -function may fail and set -.I errno -for any of the errors specified for the library routine -.IR malloc (3). -.PP -The -.I mpool_get -function may fail and set -.I errno -for the following: -.TP 15 -[EINVAL] -The requested record doesn't exist. -.PP -The -.I mpool_new -and -.I mpool_get -functions may fail and set -.I errno -for any of the errors specified for the library routines -.IR read (2) , -.IR write (2) , -and -.IR malloc (3). -.PP -The -.I mpool_sync -function may fail and set -.I errno -for any of the errors specified for the library routine -.IR write (2). -.PP -The -.I mpool_close -function may fail and set -.I errno -for any of the errors specified for the library routine -.IR free (3). -.SH "SEE ALSO" -.IR dbopen (3), -.IR btree (3), -.IR hash (3), -.IR recno (3) diff --git a/lib/libc/db/man/recno.3 b/lib/libc/db/man/recno.3 deleted file mode 100644 index bb5f353..0000000 --- a/lib/libc/db/man/recno.3 +++ /dev/null @@ -1,216 +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. -.\" -.\" @(#)recno.3 8.5 (Berkeley) 8/18/94 -.\" -.TH RECNO 3 "August 18, 1994" -.UC 7 -.SH NAME -recno \- record number database access method -.SH SYNOPSIS -.nf -.ft B -#include <sys/types.h> -#include <db.h> -.ft R -.fi -.SH DESCRIPTION -The routine -.IR 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 -.IR dbopen (3), -this manual page describes only the recno 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 recno access method specific data structure provided to -.I dbopen -is defined in the <db.h> include file as follows: -.PP -typedef struct { -.RS -u_long flags; -.br -u_int cachesize; -.br -u_int psize; -.br -int lorder; -.br -size_t reclen; -.br -u_char bval; -.br -char *bfname; -.RE -} RECNOINFO; -.PP -The elements of this structure are defined as follows: -.TP -flags -The flag value is specified by -.IR or 'ing -any of the following values: -.RS -.TP -R_FIXEDLEN -The records are fixed-length, not byte delimited. -The structure element -.I reclen -specifies the length of the record, and the structure element -.I bval -is used as the pad character. -Any records, inserted into the database, that are less than -.I reclen -bytes long are automatically padded. -.TP -R_NOKEY -In the interface specified by -.IR dbopen , -the sequential record retrieval fills in both the caller's key and -data structures. -If the R_NOKEY flag is specified, the -.I 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. -.TP -R_SNAPSHOT -This flag requires that a snapshot of the file be taken when -.I dbopen -is called, instead of permitting any unmodified records to be read from -the original file. -.RE -.TP -cachesize -A suggested maximum size, in bytes, of the memory cache. -This value is -.B only -advisory, and the access method will allocate more memory rather than fail. -If -.I cachesize -is 0 (no size is specified) a default cache is used. -.TP -psize -The recno 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 -.I psize -is 0 (no page size is specified) a page size is chosen based on the -underlying file system I/O block size. -See -.IR btree (3) -for more information. -.TP -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 -.I lorder -is 0 (no order is specified) the current host order is used. -.TP -reclen -The length of a fixed-length record. -.TP -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 (``\en'') are used to mark the end -of variable-length records and fixed-length records are padded with -spaces. -.TP -bfname -The recno access method stores the in-memory copies of its records -in a btree. -If bfname is non-NULL, it specifies the name of the btree file, -as if specified as the file name for a dbopen of a btree file. -.PP -The data part of the key/data pair used by the recno access method -is the same as other access methods. -The key is different. -The -.I data -field of the key should be a pointer to a memory location of type -.IR recno_t , -as defined in the <db.h> include file. -This type is normally the largest unsigned integral type available to -the implementation. -The -.I size -field of the key should be the size of that type. -.PP -Because there can be no meta-data associated with the underlying -recno 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 -.IR dbopen , -using the -.I 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 -.I recno -access method routines may fail and set -.I errno -for any of the errors specified for the library routine -.IR dbopen (3) -or the following: -.TP -[EINVAL] -An attempt was made to add a record to a fixed-length database that -was too large to fit. -.SH "SEE ALSO" -.IR btree (3), -.IR dbopen (3), -.IR hash (3), -.IR mpool (3) -.sp -.IR "Document Processing in a Relational Database System" , -Michael Stonebraker, Heidi Stettner, Joseph Kalash, Antonin Guttman, -Nadene Lynn, Memorandum No. UCB/ERL M82/32, May 1982. -.SH BUGS -Only big and little endian byte order is supported. |
