dbz - operate on dbz databases of text

dbz [ -{axmc} ] [ -t c ] [ -l length ] [ -{qiue} ] [ -f old ] [ -p parms ] database file ...

Dbz is a shell-level interface to the dbz(3z) database routines for indexed access to a text file.

The database file must be a text file, one line per database record, with the key the first field on the line. The -t option sets the field-separator character; the default is tab. Setting the separator character to NUL (with -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 -l option. The limitations and restrictions of 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.

In the absence of options, dbz creates a dbz(3z) index for the database; the index comprises files database.pag and database.dir in the same directory. Any previous index is silently overwritten. The -a, -x, -m, and -c options specify other operations.

With -a, dbz appends lines from the file(s) (standard input if none) to the database, updating both the text file and the indexes.

With -x, dbz reads keys from the 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 -q option makes -x print the input lines whose keys are found instead of the database lines; this is somewhat faster.

With -m, operation is the same as for -x except that the keys which are not present in the database are printed.

With -c, dbz checks the database for internal consistency. The -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).

The -i option suppresses the use of dbz(3z)'s incore facility. This makes accesses slower, but keeps the files current during updating and reduces startup/shutdown overhead.

Normally, dbz checks whether a key is already in the database before adding it. The -u option suppresses this check, speeding things up at the expense of safety.

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 dbz(3z) for what tagging is about. (Note, these defaults can be changed when dbz(3z) is installed.)

If the -f option is given, size, case mapping, and tagging are instead initialized based on the database old. This is mostly useful when creating a new generation of an existing database. (See the description of dbzagain in dbz(3z) for details.)

If the -p option is given, the parms string specifies the size, case mapping, and tagging. If 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, parms can be three fields-a decimal number, a case-mapping code character, and a hexadecimal tag mask-separated by white space. The decimal number is, again, the expected number of records; 0 means ``use the default''. See dbz(3z) for possible choices of case-mapping code, but in particular, 0 means ``no case mapping''. See dbz(3z) for details on tag masks; 0 means ``use the default''.

If the -e option is given, the decimal number in -p is taken to be the exact table size, not the expected number of records, and invocation of dbzsize (see dbz(3z)) to predict a good size for that number of records is suppressed.

The .pag file is normally about 6 bytes per record (based on the estimate given to -p or the previous history of the -f database). The .dir file is tiny.

dbz(3)

Written at U of Toronto by Henry Spencer, for the C News project. See dbz(3z) for the history of the underlying database routines.

There are a number of undocumented options with obscure effects, meant for debugging and regression testing of dbz(3z).

Permissions for the index files probably ought to be taken from those of the base file.

The line-length limit is a blemish, alleviated only slightly by -l.