freebsd-nq/contrib/libio/dbz/dbz.1

.TH DBZ 1 "11 Feb 1992"
.BY "C News"
.SH NAME
dbz \- operate on dbz databases of text
.SH SYNOPSIS
.B dbz
[
.BR \- { axmc }
] [
.B \-t
c
] [
.B \-l
length
] [
.BR \- { qiue }
] [
.B \-f
old
] [
.B \-p
parms
] database file ...
.SH DESCRIPTION
.I Dbz
is a shell-level interface to the
.IR dbz (3z)
database routines for indexed access to a text file.
.PP
The
.I database
file must be a text file,
one line per database record,
with the key the first field on the line.
The
.B \-t
option sets the field-separator character; the default is tab.
Setting the separator character to NUL (with
.BR "\-t\ ''" )
makes the whole line the key.
Lines must not exceed 1023 bytes in length including the newline;
this limit can be increased with the
.B \-l
option.
The limitations and restrictions of
.IR dbz (3z)
must also be observed;
in particular, it remains the user's responsibility to ensure that
no attempt is made to store two entries (whether identical or not)
with the same key.
.PP
In the absence of options,
.I dbz
creates a
.IR dbz (3z)
index for the database;
the index comprises files
.IB database .pag
and
.IB database .dir
in the same directory.
Any previous index is silently overwritten.
The
.BR \-a ,
.BR \-x ,
.BR \-m ,
and
.B \-c
options specify other operations.
.PP
With
.BR \-a ,
.I dbz
appends lines from the
.IR file (s)
(standard input if none)
to the database, updating both the
text file and the indexes.
.PP
With
.BR \-x ,
.I dbz
reads keys from the
.IR file (s)
(standard input if none)
and prints (on standard output) the corresponding lines, if any,
from the database.
The input is in the form of database lines, although only the keys are
significant.
The
.B \-q
option makes
.B \-x
print the input lines whose keys are found instead of the database
lines; this is somewhat faster.
.PP
With
.BR \-m ,
operation is the same as for
.B \-x
except that the keys which are \fInot\fR present in the database are printed.
.PP
With
.BR \-c ,
.I dbz
checks the database for internal consistency.
The
.B \-q
option causes this check to be done more quickly but less thoroughly
(each key is looked up in the index, but no check is made to be sure
that the index entry points to the right place).
.PP
The
.B \-i
option suppresses the use of
.IR dbz (3z)'s
.I incore
facility.
This makes accesses slower, but keeps the files current
during updating
and reduces
startup/shutdown overhead.
.PP
Normally,
.I dbz
checks whether a key is already in the database before adding it.
The
.B \-u
option suppresses this check, speeding things up at the expense of safety.
.PP
A new index is normally created with default size,
case mapping, and tagging.
The default size is right for 90-100,000 records.
The default case mapping is right for RFC822 message-ids.
See
.IR dbz (3z)
for what tagging is about.
(Note, these defaults can be changed when
.IR dbz (3z)
is installed.)
.PP
If the
.B \-f
option is given,
size, case mapping, and tagging
are instead initialized based on the
database
.IR old .
This is mostly useful when
creating a new generation of an existing database.
(See the description of
.I dbzagain
in
.IR dbz (3z)
for details.)
.PP
If the
.B \-p
option is given, the
.I parms
string specifies the size, case mapping, and tagging.
If
.I parms
is a single decimal number,
that is taken as the expected number of records
in the index, with case mapping and tagging defaulted.
Alternatively,
.I parms
can be three fields\(ema decimal number, a case-mapping code character, and a
hexadecimal tag mask\(emseparated by white space.
The decimal number is, again, the expected number of records;
0 means ``use the default''.
See
.IR dbz (3z)
for possible choices of case-mapping code,
but in particular,
.B 0
means ``no case mapping''.
See
.IR dbz (3z)
for details on tag masks;
0 means ``use the default''.
.PP
If the
.B \-e
option is given, the decimal number in
.B \-p
is taken to be the exact table size, not the expected number of records,
and invocation of
.I dbzsize
(see
.IR dbz (3z))
to predict a good size for that number of records is suppressed.
.PP
The
.B \&.pag
file is normally about 6 bytes per record (based on the estimate given to
.B \-p
or the previous history of the
.B \-f
database).
The
.B \&.dir
file is tiny.
.SH SEE ALSO
dbz(3z)
.SH HISTORY
Written at U of Toronto by Henry Spencer, for the C News project.
See
.IR dbz (3z)
for the history of the underlying database routines.
.SH BUGS
There are a number of undocumented options with obscure effects,
meant for debugging and regression testing of
.IR dbz (3z).
.PP
Permissions for the index files probably ought to be taken from those
of the base file.
.PP
The line-length limit is a blemish, alleviated only slightly by
.BR \-l .