contrib/libio/dbz/dbz.1

   1 .TH DBZ 1 "11 Feb 1992"
   2 .BY "C News"
   3 .SH NAME
   4 dbz \- operate on dbz databases of text
   5 .SH SYNOPSIS
   6 .B dbz
   7 [
   8 .BR \- { axmc }
   9 ] [
  10 .B \-t
  11 c
  12 ] [
  13 .B \-l
  14 length
  15 ] [
  16 .BR \- { qiue }
  17 ] [
  18 .B \-f
  19 old
  20 ] [
  21 .B \-p
  22 parms
  23 ] database file ...
  24 .SH DESCRIPTION
  25 .I Dbz
  26 is a shell-level interface to the
  27 .IR dbz (3z)
  28 database routines for indexed access to a text file.
  29 .PP
  30 The
  31 .I database
  32 file must be a text file,
  33 one line per database record,
  34 with the key the first field on the line.
  35 The
  36 .B \-t
  37 option sets the field-separator character; the default is tab.
  38 Setting the separator character to NUL (with
  39 .BR "\-t\ ''" )
  40 makes the whole line the key.
  41 Lines must not exceed 1023 bytes in length including the newline;
  42 this limit can be increased with the
  43 .B \-l
  44 option.
  45 The limitations and restrictions of
  46 .IR dbz (3z)
  47 must also be observed;
  48 in particular, it remains the user's responsibility to ensure that
  49 no attempt is made to store two entries (whether identical or not)
  50 with the same key.
  51 .PP
  52 In the absence of options,
  53 .I dbz
  54 creates a
  55 .IR dbz (3z)
  56 index for the database;
  57 the index comprises files
  58 .IB database .pag
  59 and
  60 .IB database .dir
  61 in the same directory.
  62 Any previous index is silently overwritten.
  63 The
  64 .BR \-a ,
  65 .BR \-x ,
  66 .BR \-m ,
  67 and
  68 .B \-c
  69 options specify other operations.
  70 .PP
  71 With
  72 .BR \-a ,
  73 .I dbz
  74 appends lines from the
  75 .IR file (s)
  76 (standard input if none)
  77 to the database, updating both the
  78 text file and the indexes.
  79 .PP
  80 With
  81 .BR \-x ,
  82 .I dbz
  83 reads keys from the
  84 .IR file (s)
  85 (standard input if none)
  86 and prints (on standard output) the corresponding lines, if any,
  87 from the database.
  88 The input is in the form of database lines, although only the keys are
  89 significant.
  90 The
  91 .B \-q
  92 option makes
  93 .B \-x
  94 print the input lines whose keys are found instead of the database
  95 lines; this is somewhat faster.
  96 .PP
  97 With
  98 .BR \-m ,
  99 operation is the same as for
 100 .B \-x
 101 except that the keys which are \fInot\fR present in the database are printed.
 102 .PP
 103 With
 104 .BR \-c ,
 105 .I dbz
 106 checks the database for internal consistency.
 107 The
 108 .B \-q
 109 option causes this check to be done more quickly but less thoroughly
 110 (each key is looked up in the index, but no check is made to be sure
 111 that the index entry points to the right place).
 112 .PP
 113 The
 114 .B \-i
 115 option suppresses the use of
 116 .IR dbz (3z)'s
 117 .I incore
 118 facility.
 119 This makes accesses slower, but keeps the files current
 120 during updating
 121 and reduces
 122 startup/shutdown overhead.
 123 .PP
 124 Normally,
 125 .I dbz
 126 checks whether a key is already in the database before adding it.
 127 The
 128 .B \-u
 129 option suppresses this check, speeding things up at the expense of safety.
 130 .PP
 131 A new index is normally created with default size,
 132 case mapping, and tagging.
 133 The default size is right for 90-100,000 records.
 134 The default case mapping is right for RFC822 message-ids.
 135 See
 136 .IR dbz (3z)
 137 for what tagging is about.
 138 (Note, these defaults can be changed when
 139 .IR dbz (3z)
 140 is installed.)
 141 .PP
 142 If the
 143 .B \-f
 144 option is given,
 145 size, case mapping, and tagging
 146 are instead initialized based on the
 147 database
 148 .IR old .
 149 This is mostly useful when
 150 creating a new generation of an existing database.
 151 (See the description of
 152 .I dbzagain
 153 in
 154 .IR dbz (3z)
 155 for details.)
 156 .PP
 157 If the
 158 .B \-p
 159 option is given, the
 160 .I parms
 161 string specifies the size, case mapping, and tagging.
 162 If
 163 .I parms
 164 is a single decimal number,
 165 that is taken as the expected number of records
 166 in the index, with case mapping and tagging defaulted.
 167 Alternatively,
 168 .I parms
 169 can be three fields\(ema decimal number, a case-mapping code character, and a
 170 hexadecimal tag mask\(emseparated by white space.
 171 The decimal number is, again, the expected number of records;
 172 0 means ``use the default''.
 173 See
 174 .IR dbz (3z)
 175 for possible choices of case-mapping code,
 176 but in particular,
 177 .B 0
 178 means ``no case mapping''.
 179 See
 180 .IR dbz (3z)
 181 for details on tag masks;
 182 0 means ``use the default''.
 183 .PP
 184 If the
 185 .B \-e
 186 option is given, the decimal number in
 187 .B \-p
 188 is taken to be the exact table size, not the expected number of records,
 189 and invocation of
 190 .I dbzsize
 191 (see
 192 .IR dbz (3z))
 193 to predict a good size for that number of records is suppressed.
 194 .PP
 195 The
 196 .B \&.pag
 197 file is normally about 6 bytes per record (based on the estimate given to
 198 .B \-p
 199 or the previous history of the
 200 .B \-f
 201 database).
 202 The
 203 .B \&.dir
 204 file is tiny.
 205 .SH SEE ALSO
 206 dbz(3z)
 207 .SH HISTORY
 208 Written at U of Toronto by Henry Spencer, for the C News project.
 209 See
 210 .IR dbz (3z)
 211 for the history of the underlying database routines.
 212 .SH BUGS
 213 There are a number of undocumented options with obscure effects,
 214 meant for debugging and regression testing of
 215 .IR dbz (3z).
 216 .PP
 217 Permissions for the index files probably ought to be taken from those
 218 of the base file.
 219 .PP
 220 The line-length limit is a blemish, alleviated only slightly by
 221 .BR \-l .