usr.bin/db/db.1

   1 .\"     $NetBSD: db.1,v 1.24 2009/01/28 05:31:18 lukem Exp $
   2 .\"
   3 .\" Copyright (c) 2002-2009 The NetBSD Foundation, Inc.
   4 .\" All rights reserved.
   5 .\"
   6 .\" This code is derived from software contributed to The NetBSD Foundation
   7 .\" by Luke Mewburn of Wasabi Systems.
   8 .\"
   9 .\" Redistribution and use in source and binary forms, with or without
  10 .\" modification, are permitted provided that the following conditions
  11 .\" are met:
  12 .\" 1. Redistributions of source code must retain the above copyright
  13 .\"    notice, this list of conditions and the following disclaimer.
  14 .\" 2. Redistributions in binary form must reproduce the above copyright
  15 .\"    notice, this list of conditions and the following disclaimer in the
  16 .\"    documentation and/or other materials provided with the distribution.
  17 .\"
  18 .\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS
  19 .\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
  20 .\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
  21 .\" PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS
  22 .\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
  23 .\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
  24 .\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
  25 .\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
  26 .\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
  27 .\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
  28 .\" POSSIBILITY OF SUCH DAMAGE.
  29 .\"
  30 .Dd January 28, 2009
  31 .Dt DB 1
  32 .Os
  33 .
  34 .Sh NAME
  35 .Nm db
  36 .Nd
  37 manipulate
  38 .Xr db 3 Ns 's
  39 .Xr btree 3
  40 and
  41 .Xr hash 3
  42 databases
  43 .
  44 .Sh SYNOPSIS
  45 .Nm
  46 .Op Fl DKiNqV
  47 .Op Fl E Ar endian
  48 .Op Fl f Ar infile
  49 .Op Fl O Ar outsep
  50 .Op Fl S Ar visitem
  51 .Op Fl T Ar visspec
  52 .Op Fl U Ar unvisitem
  53 .Op Fl X Ar extravis
  54 .Ar type
  55 .Ar dbfile
  56 .Op Ar key Op Ar \&.\&.\&.
  57 .
  58 .Nm
  59 .Fl d
  60 .Op Fl iNq
  61 .Op Fl E Ar endian
  62 .Op Fl f Ar infile
  63 .Op Fl T Ar visspec
  64 .Op Fl U Ar unvisitem
  65 .Ar type
  66 .Ar dbfile
  67 .Op Ar key Op Ar \&.\&.\&.
  68 .
  69 .Nm
  70 .Fl w
  71 .Op Fl CDiNqR
  72 .Op Fl E Ar endian
  73 .Op Fl F Ar insep
  74 .Op Fl f Ar infile
  75 .Op Fl m Ar mode
  76 .Op Fl P Ar pagesize
  77 .Op Fl T Ar visspec
  78 .Op Fl U Ar unvisitem
  79 .Ar type
  80 .Ar dbfile
  81 .Op Ar key Ar value Op Ar \&.\&.\&.
  82 .
  83 .Sh DESCRIPTION
  84 .Nm
  85 allows manipulation of
  86 .Xr btree 3
  87 and
  88 .Xr hash 3
  89 .Pq Xr db 3
  90 databases.
  91 .Pp
  92 .Nm
  93 has three modes of operation to perform upon
  94 .Ar dbfile :
  95 .Bl -tag -width "delete" -offset indent
  96 .It read
  97 Displays the given
  98 .Ar key Ns s ,
  99 and keys described in
 100 .Ar infile .
 101 If no keys and no
 102 .Ar infile
 103 is specified, the entire database is displayed.
 104 This is the default mode of operation.
 105 .It delete
 106 Enabled with
 107 .Fl d .
 108 Deletes the given
 109 .Ar key Ns s ,
 110 and keys described in
 111 .Ar infile .
 112 .It write
 113 Enabled with
 114 .Fl w .
 115 Writes the given
 116 .Ar key Ns s
 117 and
 118 .Ar value Ns s ,
 119 and keys and values described in
 120 .Ar infile
 121 (in the latter case, entries are separated by
 122 .Ar insep ) .
 123 .El
 124 .Pp
 125 There are two mandatory arguments:
 126 .Ar type
 127 is the database type; either
 128 .Sq Sy btree
 129 or
 130 .Sq Sy hash ,
 131 and
 132 .Ar dbfile
 133 is the database file to manipulate.
 134 .Pp
 135 Options valid for all modes are:
 136 .Bl -tag -width Fl -offset indent
 137 .
 138 .It Fl E Ar endian
 139 Set the endianness of the database.
 140 .Ar endian
 141 may be one of:
 142 .Bl -tag -width 1n -offset indent -compact
 143 .It Sy B
 144 Big endian
 145 .It Sy H
 146 Host endian
 147 .It Sy L
 148 Little endian
 149 .El
 150 Defaults to
 151 .Sq H
 152 (host endian).
 153 .
 154 .It Fl f Ar infile
 155 Contains a list of keys
 156 (for read and delete), or
 157 .Ar insep
 158 separated keys and values (for write)
 159 to be used as arguments to the given mode.
 160 If
 161 .Ar infile
 162 is
 163 .Sq Sy - ,
 164 .Dv stdin
 165 is used.
 166 .
 167 .It Fl i
 168 Keys are converted to lower case before manipulation.
 169 .
 170 .It Fl N
 171 Do not include the NUL byte at the end of the key or value.
 172 .
 173 .It Fl q
 174 Quiet operation.
 175 In read mode, missing keys are not considered to be an error.
 176 In delete
 177 .Pq Fl d
 178 and write
 179 .Pq Fl w
 180 modes,
 181 the result of various operations is suppressed.
 182 .
 183 .It Fl T Ar visspec
 184 Control how the items specified by the
 185 .Fl S
 186 option are encoded
 187 and
 188 .Fl U
 189 option are decoded.
 190 The
 191 .Ar visspec
 192 option-argument is a string specifying
 193 .Xr strsvisx 3
 194 flags.
 195 The string consists of one or more characters:
 196 .Bl -tag -width 2n -offset indent -compact
 197 .It Sy b
 198 .Dv VIS_NOSLASH
 199 .It Sy c
 200 .Dv VIS_CSTYLE .
 201 Overrides
 202 .Sy h
 203 and
 204 .Sy o .
 205 .It Sy h
 206 .Dv VIS_HTTPSTYLE .
 207 Overrides
 208 .Sy c
 209 and
 210 .Sy o .
 211 .It Sy o
 212 .Dv VIS_OCTAL .
 213 Overrides
 214 .Sy c
 215 and
 216 .Sy h .
 217 .It Sy s
 218 .Dv VIS_SAFE
 219 .It Sy t
 220 .Dv VIS_TAB
 221 .It Sy w
 222 .Dv VIS_WHITE
 223 .El
 224 .Pp
 225 .Fl U
 226 only supports
 227 .Fl T
 228 .Sy h .
 229 .Pp
 230 See
 231 .Xr vis 1 Ns 's
 232 corresponding options for the meaning of these characters,
 233 and
 234 .Xr strsvisx 3
 235 for more detail on the flags.
 236 .
 237 .It Fl U Ar unvisitem
 238 Specify items to
 239 .Xr strunvisx 3
 240 decode.
 241 The
 242 .Ar unvisitem
 243 option-argument is a character specifying if the key
 244 .Pq Ar k ,
 245 the value
 246 .Pq Ar v
 247 or both
 248 .Pq Ar b
 249 should be decoded.
 250 .
 251 .El
 252 .
 253 .Pp
 254 Read mode specific options are:
 255 .
 256 .Bl -tag -width Fl -offset indent
 257 .
 258 .It Fl D
 259 Display duplicate entries in
 260 .Sy btree
 261 databases.
 262 .
 263 .It Fl K
 264 Display key.
 265 .
 266 .It Fl O Ar outsep
 267 Field separator string between key and value.
 268 Defaults to a single tab
 269 .Pq Sq \et .
 270 .
 271 .It Fl S Ar visitem
 272 Specify items to
 273 .Xr strsvisx 3
 274 encode.
 275 The
 276 .Ar visitem
 277 option-argument is a character specifying if the key
 278 .Pq Ar k ,
 279 the value
 280 .Pq Ar v
 281 or both
 282 .Pq Ar b
 283 should be encoded.
 284 .
 285 .It Fl V
 286 Display value.
 287 .
 288 .It Fl X Ar extravis
 289 When encoding items with
 290 .Fl S
 291 option also encode characters in
 292 .Ar extravis ,
 293 per
 294 .Xr strsvisx 3 .
 295 .
 296 .El
 297 .Pp
 298 .Bd -ragged -offset indent
 299 (If neither of
 300 .Fl K
 301 or
 302 .Fl V
 303 is given, both options are enabled.)
 304 .Ed
 305 .
 306 .Pp
 307 Write mode specific options are:
 308 .Bl -tag -width Fl -offset indent
 309 .
 310 .It Fl C
 311 Create new database, and truncate existing databases.
 312 .
 313 .It Fl D
 314 Allow duplicate entries in
 315 .Sy btree
 316 databases.
 317 (Requires
 318 .Fl R
 319 to be useful.)
 320 .
 321 .It Fl F Ar insep
 322 Input field separator string between key and value used when parsing
 323 .Ar infile .
 324 Defaults to a single space
 325 .Pq Sq \  .
 326 .
 327 .It Fl m Ar mode
 328 Octal mode of created database.
 329 Defaults to
 330 .Sq 0644 .
 331 .
 332 .It Fl P Ar pagesize
 333 Set the page size of the table to
 334 .Ar pagesize
 335 bytes.
 336 If set to
 337 .Sq 0 ,
 338 a database-specific default is determined,
 339 based on the block-size of the underlying file-system.
 340 Defaults to
 341 .Sq 4096 .
 342 .
 343 .It Fl R
 344 Overwrite existing entries.
 345 If not specified, writing to an existing entry raises an error.
 346 .
 347 .El
 348 .
 349 .Sh SEE ALSO
 350 .Xr vis 1 ,
 351 .Xr btree 3 ,
 352 .Xr db 3 ,
 353 .Xr hash 3 ,
 354 .Xr strsvisx 3 ,
 355 .Xr strunvisx 3
 356 .\" .Xr makemap 8
 357 .
 358 .Sh HISTORY
 359 The
 360 .Nm
 361 command appeared in
 362 .Nx 2.0 .
 363 .
 364 .Sh AUTHORS
 365 .An Luke Mewburn
 366 .Aq lukem@NetBSD.org .