1 files changed, 221 insertions, 0 deletions
diff --git a/libio/dbz/dbz.1 b/libio/dbz/dbz.1
new file mode 100644
index 00000000000..d2fff17af98
--- /dev/null
+++ b/libio/dbz/dbz.1
@@ -0,0 +1,221 @@
+.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 .