1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
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 .
|
