222 lines
4.6 KiB
Groff
222 lines
4.6 KiB
Groff
.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 .
|