d/freebsd-nq
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

man(7) -> mdoc(7).

Browse Source
This commit is contained in:
Ruslan Ermilov 2001-01-11 20:07:30 +00:00
parent 954c4772dd
commit d74f3e32c6
5 changed files with 858 additions and 694 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

272
lib/libc/db/man/btree.3
View File

@ -32,85 +32,93 @@
.\" @(#)btree.3 8.4 (Berkeley) 8/18/94
.\" $FreeBSD$
.\"
.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
.Dd August 18, 1994
.Dt BTREE 3
.Os
.Sh NAME
.Nm btree
.Nd "btree database access method"
.Sh SYNOPSIS
.Fd "#include <sys/types.h>"
.Fd "#include <db.h>"
.Sh DESCRIPTION
The routine
.IR dbopen
.Fn dbopen
is the library interface to database files.
One of the supported file formats is btree files.
One of the supported file formats is
.Nm
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
.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 btree access method specific data structure provided to
.I dbopen
is defined in the <db.h> include file as follows:
.PP
.Pp
The
.Nm
access method specific data structure provided to
.Fn dbopen
is defined in the
.Aq Pa db.h
include file as follows:
.Bd -literal
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
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;
.PP
.Ed
.Pp
The elements of this structure are as follows:
.TP
flags
.Bl -tag -width indent
.It Va flags
The flag value is specified by
.IR or 'ing
.Em or Ns 'ing
any of the following values:
.RS
.TP
R_DUP
.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
.IR dbopen (3),
.Xr 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
.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.
.IP
.Pp
If the database contains duplicate keys, the order of retrieval of
key/data pairs is undefined if the
.I get
.Va 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
.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
.B only
.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.
@ -119,40 +127,38 @@ 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
.Va cachesize
is 0 (no size is specified) a default cache is used.
.TP
maxkeypage
.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 btree data structure works,
.\" .I maxkeypage
.\" Because of the way the
.\" .Nm
.\" data structure works,
.\" .Va maxkeypage
.\" must always be greater than or equal to 2.
.\" If
.\" .I maxkeypage
.\" .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).
.TP
minkeypage
.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
.I minkeypage
.Va minkeypage
is 0 (no minimum number of keys is specified) a value of 2 is used.
.TP
psize
.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
.I psize
.Va 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
.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,
@ -160,12 +166,14 @@ 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
.Va compare
is
.Dv 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.
.It Va prefix
.Va 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.
@ -173,62 +181,92 @@ 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
.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
.I prefix
is NULL and a comparison routine is specified, no prefix comparison is
.Va prefix
is
.Dv NULL
and a comparison routine is specified, no prefix comparison is
done.
.TP
lorder
.It Va lorder
The byte order for integers in the stored database metadata.
The number should represent the order as an integer; for example,
The number should represent the order as an integer; for example,
big endian order would be the number 4,321.
If
.I lorder
.Va 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
.El
.Pp
If the file already exists (and the
.Dv O_TRUNC
flag is not specified), the
values specified for the parameters
.Va flags , lorder
and
.Va psize
are ignored
in favor of the values used when the tree was created.
.PP
.Pp
Forward sequential scans of a tree are from the least key to the greatest.
.PP
.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.
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 btree will all complete in
.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 btrees results in a low 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
.Sh ERRORS
The
.I btree
.Nm
access method routines may fail and set
.I errno
.Va 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
.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.

572
lib/libc/db/man/dbopen.3
View File

@ -32,25 +32,20 @@
.\" @(#)dbopen.3 8.5 (Berkeley) 1/2/94
.\" $FreeBSD$
.\"
.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
.Dd January 2, 1994
.Dt DBOPEN 3
.Os
.Sh NAME
.Nm dbopen
.Nd "database access methods"
.Sh SYNOPSIS
.Fd "#include <sys/types.h>"
.Fd "#include <limits.h>"
.Fd "#include <db.h>"
.Ft DB *
.Fn dbopen "const char *file" "int flags" "int mode" "DBTYPE type" "const void *openinfo"
.Sh DESCRIPTION
.Fn Dbopen
is the library interface to database files.
The supported file formats are btree, hashed and UNIX file oriented.
The btree format is a representation of a sorted, balanced tree structure.
@ -59,419 +54,486 @@ 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)
.Xr btree 3 ,
.Xr hash 3
and
.IR recno (3).
.PP
Dbopen opens
.I file
.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 NULL.
.PP
the file parameter to
.Dv NULL .
.Pp
The
.I flags
.Fa flags
and
.I mode arguments
.Fa 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.)
.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
.\".IR or 'ing
.\".Em or Ns 'ing
.\"them into the
.\".I flags
.\".Fa flags
.\"argument.
.\".TP
.\"DB_LOCK
.\".Bl -tag -width indent
.\".It Dv DB_LOCK
.\"Do the necessary locking in the database to support concurrent access.
.\"If concurrent access isn't needed or the database is read-only this
.\"flag should not be set, as it tends to have an associated performance
.\"penalty.
.\".TP
.\"DB_SHMEM
.\".It Dv DB_SHMEM
.\"Place the underlying memory pool used by the database in shared
.\"memory.
.\"Necessary for concurrent access.
.\".TP
.\"DB_TXN
.\".It Dv DB_TXN
.\"Support transactions in the database.
.\"The DB_LOCK and DB_SHMEM flags must be set as well.
.PP
.\"The
.\".Dv DB_LOCK
.\"and
.\".Dv DB_SHMEM
.\"flags must be set as well.
.\".El
.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
.Fa type
argument is of type
.Ft DBTYPE
(as defined in the
.Aq Pa db.h
include file) and
may be set to
.Dv DB_BTREE , DB_HASH
or
.Dv DB_RECNO .
.Pp
The
.I openinfo
.Fa 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
.Fa openinfo
is
.Dv 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
.Pp
.Fn Dbopen
returns a pointer to a
.Ft DB
structure on success and
.Dv NULL
on error.
The
.Ft DB
structure is defined in the
.Aq Pa db.h
include file, and contains at
least the following fields:
.sp
.nf
.Bd -literal
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
DBTYPE type;
int (*close)(const DB *db);
int (*del)(const DB *db, const DBT *key, u_int flags);
int (*fd)(const DB *db);
int (*get)(const DB *db, DBT *key, DBT *data, u_int flags);
int (*put)(const DB *db, DBT *key, const DBT *data,
u_int flags);
int (*sync)(const DB *db, u_int flags);
int (*seq)(const DB *db, DBT *key, DBT *data, u_int flags);
} DB;
.fi
.PP
.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
.IR dbopen ,
.Fn dbopen ,
and sometimes one or more pointers to key/data structures and a flag value.
.TP
type
.Bl -tag -width indent
.It Va type
The type of the underlying access method (and file format).
.TP
close
.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
.I close
.Va close
or
.I sync
.Va sync
function may result in inconsistent or lost information.
.I Close
.Va Close
routines return -1 on error (setting
.IR errno )
.Va errno )
and 0 on success.
.TP
del
.It Va del
A pointer to a routine to remove key/data pairs from the database.
.IP
.Pp
The parameter
.I flag
.Fa flags
may be set to the following value:
.RS
.TP
R_CURSOR
.Bl -tag -width indent
.It Dv R_CURSOR
Delete the record referenced by the cursor.
The cursor must have previously been initialized.
.RE
.IP
.I Delete
.El
.Pp
.Va Delete
routines return -1 on error (setting
.IR errno ),
.Va errno ) ,
0 on success, and 1 if the specified
.I key
.Fa key
was not in the file.
.TP
fd
.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
.I dbopen
.Fn dbopen
with the same
.I file
.Fa file
name.
This file descriptor may be safely used as an argument to the
.IR fcntl (2)
.Xr fcntl 2
and
.IR flock (2)
.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.
.I Fd
.Va \&Fd
routines return -1 on error (setting
.IR errno ),
.Va errno ) ,
and the file descriptor on success.
.TP
get
.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
.I key
.Fa key
are returned in the structure referenced by
.IR data .
.I Get
.Fa data .
.Va Get
routines return -1 on error (setting
.IR errno ),
.Va errno ) ,
0 on success, and 1 if the
.I key
.Fa key
was not in the file.
.TP
put
.It Va put
A pointer to a routine to store key/data pairs in the database.
.IP
.Pp
The parameter
.I flag
.Fa flags
may be set to one of the following values:
.RS
.TP
R_CURSOR
.Bl -tag -width indent
.It Dv R_CURSOR
Replace the key/data pair referenced by the cursor.
The cursor must have previously been initialized.
.TP
R_IAFTER
.It Dv R_IAFTER
Append the data immediately after the data referenced by
.IR key ,
.Fa key ,
creating a new key/data pair.
The record number of the appended key/data pair is returned in the
.I key
.Fa key
structure.
(Applicable only to the DB_RECNO access method.)
.TP
R_IBEFORE
(Applicable only to the
.Dv DB_RECNO
access method.)
.It Dv R_IBEFORE
Insert the data immediately before the data referenced by
.IR key ,
.Fa key ,
creating a new key/data pair.
The record number of the inserted key/data pair is returned in the
.I key
.Fa key
structure.
(Applicable only to the DB_RECNO access method.)
.TP
R_NOOVERWRITE
(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.
.TP
R_SETCURSOR
.It Dv 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
(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.
.IP
R_IAFTER and R_IBEFORE are available only for the DB_RECNO
.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.
.IP
.Pp
The default behavior of the
.I put
.Va put
routines is to enter the new key/data pair, replacing any previously
existing key.
.IP
.I Put
.Pp
.Va Put
routines return -1 on error (setting
.IR errno ),
0 on success, and 1 if the R_NOOVERWRITE
.I flag
.Va errno ) ,
0 on success, and 1 if the
.Dv R_NOOVERWRITE
flag
was set and the key already exists in the file.
.TP
seq
.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
.IR key ,
.Fa key ,
and the address and length of the data are returned in the
structure referenced
by
.IR data .
.IP
.Fa data .
.Pp
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 ,
position of the
.Dq cursor
is not affected by calls to the
.Va del ,
.Va get ,
.Va put ,
or
.I sync
.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.
.IP
The flag value
.B must
.Pp
The
.Fa flags
value
.Em must
be set to one of the following values:
.RS
.TP
R_CURSOR
.Bl -tag -width indent
.It Dv R_CURSOR
The data associated with the specified key is returned.
This differs from the
.I get
.Va 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
(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.)
.TP
R_FIRST
.It Dv 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
.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 DB_BTREE and DB_RECNO access methods.)
.TP
R_NEXT
(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 R_FIRST flag.
.TP
R_PREV
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 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
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.
.IP
.I Seq
.Pp
.Va Seq
routines return -1 on error (setting
.IR errno ),
.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 DB_RECNO access method is being used, and if the database file
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
.I seq
.Va seq
routines return 2.
.TP
sync
.It Va sync
A pointer to a routine to flush any cached information to disk.
If the database is in memory only, the
.I sync
.Va 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
.Pp
The
.Fa flags
value may be set to the following value:
.Bl -tag -width indent
.It Dv R_RECNOSYNC
If the
.Dv DB_RECNO
access method is being used, this flag causes
the
.Va sync
routine to apply to the btree file which underlies the
recno file, not the recno file itself.
(See the
.I bfname
.Va bfname
field of the
.IR recno (3)
.Xr recno 3
manual page for more information.)
.RE
.IP
.I Sync
.El
.Pp
.Va Sync
routines return -1 on error (setting
.IR errno )
.Va errno )
and 0 on success.
.SH "KEY/DATA PAIRS"
.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:
.PP
.Bd -literal
typedef struct {
.RS
void *data;
.br
size_t size;
.RE
void *data;
size_t size;
} DBT;
.PP
The elements of the DBT structure are defined as follows:
.TP
data
.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.
.TP
size
.It Va size
The length of the byte string.
.PP
.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
.Sh ERRORS
The
.I dbopen
.Fn dbopen
routine may fail and set
.I errno
.Va errno
for any of the errors specified for the library routines
.IR open (2)
.Xr open 2
and
.IR malloc (3)
.Xr malloc 3
or the following:
.TP
[EFTYPE]
.Bl -tag -width Er
.It Bq Er EFTYPE
A file is incorrectly formatted.
.TP
[EINVAL]
.It Bq Er EINVAL
A parameter has been specified (hash function, pad byte etc.) that is
incompatible with the current file specification or which is not
meaningful for the function (for example, use of the cursor without
prior initialization) or there is a mismatch between the version
number of file and the software.
.PP
.El
.Pp
The
.I close
.Va close
routines may fail and set
.I errno
.Va errno
for any of the errors specified for the library routines
.IR close (2),
.IR read (2),
.IR write (2),
.IR free (3),
.Xr close 2 ,
.Xr read 2 ,
.Xr write 2 ,
.Xr free 3 ,
or
.IR fsync (2).
.PP
.Xr fsync 2 .
.Pp
The
.IR del ,
.IR get ,
.I put
.Va del ,
.Va get ,
.Va put
and
.I seq
.Va seq
routines may fail and set
.I errno
.Va errno
for any of the errors specified for the library routines
.IR read (2),
.IR write (2),
.IR free (3)
.Xr read 2 ,
.Xr write 2 ,
.Xr free 3
or
.IR malloc (3).
.PP
.Xr malloc 3 .
.Pp
The
.I fd
.Va fd
routines will fail and set
.I errno
to ENOENT for in memory databases.
.PP
.Va errno
to
.Er ENOENT
for in memory databases.
.Pp
The
.I sync
.Va sync
routines may fail and set
.I errno
.Va 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
.Xr fsync 2 .
.Sh SEE ALSO
.Xr btree 3 ,
.Xr hash 3 ,
.Xr mpool 3 ,
.Xr recno 3
.Rs
.%T "LIBTP: Portable, Modular Transactions for UNIX"
.%A Margo Seltzer
.%A Michael Olson
.%R "USENIX proceedings"
.%D Winter 1992
.Re
.Sh BUGS
The typedef
.Ft DBT
is a mnemonic for
.Dq "data base thang" ,
and was used
because noone could think of a reasonable name that wasn't already used.
.PP
.Pp
The file descriptor interface is a kluge and will be deleted in a
future version of the interface.
.PP
.Pp
None of the access methods provide any form of concurrent access,
locking, or transactions.

221
lib/libc/db/man/hash.3
View File

@ -32,129 +32,160 @@
.\" @(#)hash.3 8.6 (Berkeley) 8/18/94
.\" $FreeBSD$
.\"
.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
.Dd August 18, 1994
.Dt HASH 3
.Os
.Sh NAME
.Nm hash
.Nd "hash database access method"
.Sh SYNOPSIS
.Fd "#include <sys/types.h>"
.Fd "#include <db.h>"
.Sh DESCRIPTION
The routine
.IR dbopen
.Fn dbopen
is the library interface to database files.
One of the supported file formats is hash files.
One of the supported file formats is
.Nm
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
.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
.I dbopen
is defined in the <db.h> include file as follows:
.sp
.Fn dbopen
is defined in the
.Aq Pa db.h
include file as follows:
.Bd -literal
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
u_int bsize;
u_int ffactor;
u_int nelem;
u_int cachesize;
u_int32_t (*hash)(const void *, size_t);
int lorder;
} HASHINFO;
.PP
.Ed
.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.
.Bl -tag -width indent
.It Va bsize
.Va Bsize
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.
.TP
ffactor
.I Ffactor
indicates a desired density within the hash table.
.It Va ffactor
.Va Ffactor
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 hash table grows or shrinks.
one bucket, determining when the
.Nm
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
.It Va nelem
.Va Nelem
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.
.TP
cachesize
.It Va cachesize
A suggested maximum size, in bytes, of the memory cache.
This value is
.B only
.Em 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
.It Va hash
.Va Hash
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 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
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.
.TP
lorder
.It Va lorder
The byte order for integers in the stored database metadata.
The number should represent the order as an integer; for example,
The number should represent the order as an integer; for example,
big endian order would be the number 4,321.
If
.I lorder
.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
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
.El
.Pp
If the file already exists (and the
.Dv O_TRUNC
flag is not specified), the
values specified for the parameters
.Va bsize , ffactor , lorder
and
.I ndbm
.Va nelem
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
.Sh ERRORS
The
.I hash
.Nm
access method routines may fail and set
.I errno
.Va 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
.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.

262
lib/libc/db/man/mpool.3
View File

@ -32,189 +32,207 @@
.\" @(#)mpool.3 8.1 (Berkeley) 6/4/93
.\" $FreeBSD$
.\"
.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
.Dd June 4, 1993
.Dt MPOOL 3
.Os
.Sh NAME
.Nm mpool
.Nd "shared memory buffer pool"
.Sh SYNOPSIS
.Fd "#include <db.h>"
.Fd "#include <mpool.h>"
.Ft MPOOL *
.Fn mpool_open "DBT *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
.Nm Mpool
is the library interface intended to provide page oriented buffer management
of files.
The buffers may be shared between processes.
.PP
.Pp
The function
.I mpool_open
.Fn mpool_open
initializes a memory pool.
The
.I key
.Fa 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.
.Fa key
is
.Dv NULL ,
the buffers are mapped into private memory.
The
.I fd
.Fa 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
.Fa key
is
.No non\- Ns Dv NULL
and matches a file already being mapped, the
.Fa fd
argument is ignored.
.PP
.Pp
The
.I pagesize
.Fa pagesize
argument is the size, in bytes, of the pages into which the file is broken up.
The
.I maxcache
.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
.Pp
The
.I mpool_filter
.Fn mpool_filter
function is intended to make transparent input and output processing of the
pages possible.
If the
.I pgin
.Fa 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
.Fa 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
.Fa pgcookie
pointer, the page number and a pointer to the page to being read or written.
.PP
.Pp
The function
.I mpool_new
takes an MPOOL pointer and an address as arguments.
.Fn mpool_new
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
.I pgnoaddr
.Fa pgnoaddr
address.
Otherwise, NULL is returned and errno is set.
.PP
Otherwise,
.Dv NULL
is returned and
.Va errno
is set.
.Pp
The function
.I mpool_get
takes a MPOOL pointer and a page number as arguments.
.Fn mpool_get
takes a
.Ft 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
Otherwise,
.Dv NULL
is returned and
.Va errno
is set.
The
.I mpool_close
.Fa flags
parameter is not currently used.
.Pp
The function
.Fn mpool_put
unpins the page referenced by
.Fa pgaddr .
.Fa Pgaddr
must be an address previously returned by
.Fn mpool_get
or
.Fn mpool_new .
The
.Fa flags
value 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
.Fn Mpool_put
returns 0 on success and -1 if an error occurs.
.Pp
The function
.Fn mpool_sync
writes all modified pages associated with the
.Ft MPOOL
pointer to the
backing file.
.Fn Mpool_sync
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
.B not
.Em not
written to the backing file.
.I Mpool_close
.Fn Mpool_close
returns 0 on success and -1 if an error occurs.
.SH ERRORS
.Sh ERRORS
The
.I mpool_open
.Fn mpool_open
function may fail and set
.I errno
.Va errno
for any of the errors specified for the library routine
.IR malloc (3).
.PP
.Xr malloc 3 .
.Pp
The
.I mpool_get
.Fn mpool_get
function may fail and set
.I errno
.Va errno
for the following:
.TP 15
[EINVAL]
.Bl -tag -width Er
.It Bq Er EINVAL
The requested record doesn't exist.
.PP
.El
.Pp
The
.I mpool_new
.Fn mpool_new
and
.I mpool_get
.Fn mpool_get
functions may fail and set
.I errno
.Va errno
for any of the errors specified for the library routines
.IR read (2) ,
.IR write (2) ,
.Xr read 2 ,
.Xr write 2 ,
and
.IR malloc (3).
.PP
.Xr malloc 3 .
.Pp
The
.I mpool_sync
.Fn mpool_sync
function may fail and set
.I errno
.Va errno
for any of the errors specified for the library routine
.IR write (2).
.PP
.Xr write 2 .
.Pp
The
.I mpool_close
.Fn mpool_close
function may fail and set
.I errno
.Va 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)
.Xr free 3 .
.Sh SEE ALSO
.Xr dbopen 3 ,
.Xr btree 3 ,
.Xr hash 3 ,
.Xr recno 3

225
lib/libc/db/man/recno.3
View File

@ -32,26 +32,26 @@
.\" @(#)recno.3 8.5 (Berkeley) 8/18/94
.\" $FreeBSD$
.\"
.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
.Dd August 18, 1994
.Dt RECNO 3
.Os
.Sh NAME
.Nm recno
.Nd "record number database access method"
.Sh SYNOPSIS
.Fd "#include <sys/types.h>"
.Fd "#include <db.h>"
.Sh DESCRIPTION
The routine
.IR dbopen
.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
.IR dbopen (3),
this manual page describes only the recno specific information.
.PP
.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.
@ -60,158 +60,173 @@ 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
.Pp
The
.Nm
access method specific data structure provided to
.Fn dbopen
is defined in the
.Aq Pa db.h
include file as follows:
.Bd -literal
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
u_long flags;
u_int cachesize;
u_int psize;
int lorder;
size_t reclen;
u_char bval;
char *bfname;
} RECNOINFO;
.PP
.Ed
.Pp
The elements of this structure are defined as follows:
.TP
flags
.Bl -tag -width indent
.It Va flags
The flag value is specified by
.IR or 'ing
.Em or Ns 'ing
any of the following values:
.RS
.TP
R_FIXEDLEN
.Bl -tag -width indent
.It Dv R_FIXEDLEN
The records are fixed-length, not byte delimited.
The structure element
.I reclen
.Va reclen
specifies the length of the record, and the structure element
.I bval
.Va bval
is used as the pad character.
Any records, inserted into the database, that are less than
.I reclen
.Va reclen
bytes long are automatically padded.
.TP
R_NOKEY
.It Dv R_NOKEY
In the interface specified by
.IR dbopen ,
.Fn 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
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.
.TP
R_SNAPSHOT
.It Dv R_SNAPSHOT
This flag requires that a snapshot of the file be taken when
.I dbopen
.Fn dbopen
is called, instead of permitting any unmodified records to be read from
the original file.
.RE
.TP
cachesize
.El
.It Va cachesize
A suggested maximum size, in bytes, of the memory cache.
This value is
.B only
.Em 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
.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
.I psize
.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
.IR btree (3)
.Xr btree 3
for more information.
.TP
lorder
.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
.I lorder
.Va lorder
is 0 (no order is specified) the current host order is used.
.TP
reclen
.It Va reclen
The length of a fixed-length record.
.TP
bval
.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 (``\en'') are used to mark the end
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.
.TP
bfname
The recno access method stores the in-memory copies of its records
.It Va bfname
The
.Nm
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
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
.I data
.Va 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.
.Ft recno_t ,
as defined in the
.Aq Pa db.h
include file.
This type is normally the largest unsigned integral type available to
the implementation.
The
.I size
.Va size
field of the key should be the size of that type.
.PP
.Pp
Because there can be no meta-data associated with the underlying
recno access method files, any changes made to the default values
.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
.Pp
In the interface specified by
.IR dbopen ,
.Fn dbopen ,
using the
.I put
.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
.Sh ERRORS
The
.I recno
.Nm
access method routines may fail and set
.I errno
.Va errno
for any of the errors specified for the library routine
.IR dbopen (3)
.Xr dbopen 3
or the following:
.TP
[EINVAL]
.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.
.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
.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.